Contacts in Mailrify represent an individual email recipient. Each contact has an identifier and is linked to an email address.
Contacts can be added to your Mailrify project in several ways:
- Using /v1/track, when tracking an event for a contact that does not yet exist, Mailrify will automatically create it.
- When you send a transactional email via /v1/send, Mailrify automatically creates or updates a contact for the recipient. You do not need to pre-create contacts before sending.
- Using /contacts, to create a single contact.
- Import through CSV
- Manually through the dashboard
Each plan includes a maximum number of active contacts.
Active contacts are the contacts that count toward your plan limit. When you reach the active contact limit, Mailrify will not block transactional sends. Instead, new recipients are created as pending contacts.
Pending contacts are temporary contacts created when you send a transactional email (or track an event for a new recipient) while your active contact limit is reached.
- Pending contacts receive the email/event flow normally.
- Pending contacts do not count toward your active contact limit.
- Pending contacts are excluded from segments and campaigns.
- Pending contacts are automatically deleted after 24 hours.
- You can promote a pending contact to active from the dashboard or API if you have available active-contact capacity.
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 |
If you accidentally mix data types for a specific key, Mailrify will default to treating the value as a string.
Reserved keys
Certain keys are reserved by the system and automatically set by Mailrify:
| 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.
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 |
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.
