# Contacts (/concepts/contacts)

Contacts in Plunk represent an individual email recipient. Each contact has an identifier and is linked to an email address.

## Adding contacts

Contacts can be added to your Plunk project in several ways:

* Using [/v1/track](/api-reference/public-api/trackEvent), when tracking an event for a contact that does not yet exist, Plunk will automatically create it.
* Using [/contacts](/api-reference/contacts/createContact), to create a single contact.
* Import through CSV
* Manually through the dashboard

## Contact Data

You can associate custom data with each contact using key-value pairs. This data can be used for segmentation and personalization.

### Data types

Contact data types are inferred based on the value provided:

| Type    | Description                                   |
| ------- | --------------------------------------------- |
| String  | Any text value                                |
| Number  | Numeric values, including integers and floats |
| Boolean | True or false values                          |
| Date    | Date values in ISO 8601 format                |

<Callout title="Default data type" variant="idea">
  If you accidentally mix data types for a specific key, Plunk will default to treating the value as a string.
</Callout>

### Reserved keys

Certain keys are reserved by the system and automatically set by Plunk:

| Key        | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| email      | The contact's email address                                     |
| createdAt  | Timestamp of when the contact was created                       |
| updatedAt  | Timestamp of the last update to the contact                     |
| subscribed | Boolean indicating if the contact is globally subscribed or not |

### Special keys

| Key    | Description                                                                                                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| locale | The contact's preferred locale in ISO 639 (e.g. 'en', 'fr', 'es'). Specifying the locale field on a contact will override the project-wide locale for contact-facing pages and email footers |

## Subscription State

Every contact has a `subscribed` field that determines which types of emails they will receive. A newly created contact is subscribed by default.

### How contacts become unsubscribed

A contact can become unsubscribed in several ways:

* **Manually** through the dashboard or via the API
* **Self-service** by clicking the unsubscribe link in an email
* **Automatically** when an email to the contact bounces or results in a complaint

### Emails by subscription state

The subscription state controls whether a contact receives marketing emails. Transactional emails are always delivered regardless of subscription state.

| Email type                                                                           | Subscribed | Unsubscribed  |
| ------------------------------------------------------------------------------------ | ---------- | ------------- |
| **Transactional** (via [/v1/send](/api-reference/public-api/sendTransactionalEmail)) | Delivered  | Delivered     |
| **Campaigns** (marketing)                                                            | Delivered  | Not delivered |
| **Campaigns** (headless)                                                             | Delivered  | Not delivered |
| **Campaigns** (transactional)                                                        | Delivered  | Delivered     |
| **Automations** (marketing template)                                                 | Delivered  | Not delivered |
| **Automations** (headless template)                                                  | Delivered  | Not delivered |
| **Automations** (transactional template)                                             | Delivered  | Delivered     |

<Callout title="Transactional emails and marketing templates" variant="warn">
  Even when using the transactional API endpoint (`/v1/send`), you cannot send a marketing template to an unsubscribed contact. Use a transactional template instead if the email must reach unsubscribed contacts.
</Callout>