DocumentationContacts and audience
Contacts and audience
Contact model, externalId, locale, and opt-in for newsletter sends.
Contacts are your newsletter audience inside a tenant. Sync them from your CRM or app via the API; campaigns fan out to matching contacts at send time.
Required API key scopes: contacts:read (list and read) and contacts:write (create, update, bulk import, GDPR erasure).
Authorization: Bearer mc_live_xxxx
X-Tenant-Id: clxxxxxxxx
See API keys and scopes.
Contact model
| Field | Description |
|---|---|
email | Primary address (unique per tenant) |
externalId | Your system's id (max 128 chars); used for upsert and DELETE |
locale | Preferred language (es, en, it, fr, ca, de) for template routing |
optIn | Marketing consent flag; campaigns can filter on this |
attributes | Free-form JSON (name, plan, tags, etc.) |
consentVersion | Version string of the consent text the user accepted |
source | Where the contact came from (signup, import, api) |
projectId | Optional SMTP project scope |
List contacts
GET /contacts?page=1&limit=50&locale=en&optIn=true
Query parameters:
| Parameter | Description |
|---|---|
page / limit | Pagination (limit max 500) |
locale | Filter by locale |
optIn | Filter by consent (true / false) |
updatedSince | ISO timestamp — incremental sync |
cursor | Cursor-based pagination |
projectId | Filter by project |
Read one contact
GET /contacts/{idOrExternalId}
Accepts the internal MailingCore id or your externalId.
GDPR erasure
DELETE /contacts/{externalId}
Permanently removes the contact and triggers the erasure flow. Requires contacts:write.
Related endpoints
| Action | Page |
|---|---|
| Create or update one | Upsert contact |
| Import many | Bulk import |
| Unsubscribe flow | Unsubscribe |