Skip to main content
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, 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, MailGlyph 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

​
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:
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:
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:

​
Special keys

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