> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailglyph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Manage and organize your contacts effectively

Contacts in MailGlyph 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 MailGlyph workspace in several ways:

* Using [/v1/track](https://docs.mailglyph.com/api-reference/public-api/trackEvent.md), when tracking an event for a contact that does not yet exist, MailGlyph will automatically create it.
* When you send a transactional email via [/v1/send](https://docs.mailglyph.com/api-reference/public-api/sendEmail.md), MailGlyph automatically creates or updates a contact for the recipient. You do not need to pre-create contacts before sending.
* Using [/contacts](https://docs.mailglyph.com/api-reference/contacts/createContact.md), to create a single contact.
* Import through CSV
* Manually through the dashboard

## Contact limits

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, MailGlyph will not block transactional sends. Instead, new recipients are created as pending contacts.

## 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.

## 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 and date-time values in ISO 8601 format |

> [!NOTE]
>
> If you accidentally mix data types for a specific key, MailGlyph will default to treating the value as a string.

For date fields, send UTC ISO 8601 strings with a `Z` timezone suffix so MailGlyph can detect them consistently:

```json theme={null}
{
  "subscription_started_date": "2026-06-15T10:30:00Z"
}
```

In PHP, use `gmdate('Y-m-d\TH:i:s\Z')` for this format.

### Reserved keys

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

| 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 workspace-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](https://docs.mailglyph.com/api-reference/public-api/sendEmail.md)) | 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 |

> [!WARNING]
>
> Even when using the transactional API endpoint (`/v1/send`), you cannot send a marketing or headless template to an unsubscribed contact. Use a transactional template instead if the email must reach unsubscribed contacts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.