Contacts
Manage and organize your contacts effectively
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, when tracking an event for a contact that does not yet exist, Plunk will automatically create it.
- Using /contacts, 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 |
Default data type
If you accidentally mix data types for a specific key, Plunk will default to treating the value as a string.
Reserved keys
Certain keys are reserved by the system and automatically set by Plunk:
| Key | Description |
|---|---|
| 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) | Delivered | Delivered |
| Campaigns | Delivered | Not delivered |
| Automations (transactional template) | Delivered | Delivered |
| Automations (marketing template) | Delivered | Not delivered |
Transactional emails and marketing templates
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.