POST /api/contacts — Create or Update a Contact Record

POST /api/contacts is the primary way to sync contact data into Datamailer. It creates or updates the global contact record, creates or updates the audience- and client-scoped subscription, applies email validation and suppression state, and assigns audience-scoped tags — all in a single atomic request.

Endpoint

POST /api/contacts

Authentication

Requires a Bearer token issued to the client whose slug matches the client field in the request body.

Authorization: Bearer <client-api-key>

Request body

string

required

The recipient’s email address. Must be a valid RFC 5321 address. Normalized to lowercase before storage; the original casing is preserved for display.

audience

string

required

Slug of the audience to subscribe the contact to. Must belong to the same organization as the authenticated client.

client

string

required

Slug of the client making the request. Must exactly match the authenticated client’s slug or the request is rejected with 403 Forbidden.

status

string

default:"pending"

Subscription status to set. One of pending, subscribed, or unsubscribed. Defaults to pending when omitted.

Response

A successful call returns HTTP 200 with the full contact status payload plus a tags array.

contact_id

integer

Internal Datamailer ID for the contact record.

string

Normalized (lowercased) email address for the contact.

exists

boolean

Always true for a successful upsert response.

verified

boolean

Whether the contact has a verified_at timestamp set at the contact level.

verified_at

string | null

ISO-8601 UTC timestamp of contact-level verification, or null if not verified.

email_validation

object

Current email validation state.

Show email_validation fields

status

string

One of unknown, valid, invalid_syntax, no_mx, disposable, risky, manually_invalid, externally_validated.

reason

string

Provider-supplied reason string, or an empty string.

validated_at

string | null

ISO-8601 UTC timestamp of the last validation update, or null.

global_unsubscribed

boolean

Whether the contact has opted out of all marketing email globally.

hard_bounced

boolean

Whether the contact’s address has hard bounced.

complained

boolean

Whether the contact has filed a spam complaint.

audience

object

Audience-scoped subscription state.

Show audience fields

slug

string

The audience slug.

subscribed

boolean

Whether the audience-level subscription status is subscribed.

status

string | null

One of pending, subscribed, unsubscribed, or null if no audience subscription exists.

verified

boolean

Whether the audience subscription has a verified_at timestamp.

verified_at

string | null

ISO-8601 UTC timestamp of audience-subscription verification, or null.

unsubscribed_at

string | null

ISO-8601 UTC timestamp when the audience-level unsubscription occurred, or null.

unsubscribe_reason

string

Reason recorded at audience-level unsubscription, or an empty string.

client

object

Client-scoped subscription state. Same shape as audience.

Show client fields

slug

string

The client slug.

subscribed

boolean

Whether the client-level subscription status is subscribed.

status

string | null

One of pending, subscribed, unsubscribed, or null if no client subscription exists.

verified

boolean

Whether the client subscription has a verified_at timestamp.

verified_at

string | null

ISO-8601 UTC timestamp of client-subscription verification, or null.

unsubscribed_at

string | null

ISO-8601 UTC timestamp when the client-level unsubscription occurred, or null.

unsubscribe_reason

string

Reason recorded at client-level unsubscription, or an empty string.

can_send_marketing

boolean

Whether a marketing campaign email can currently be sent to this contact for this audience and client. false if the contact is suppressed, has a non-deliverable email validation status, is not subscribed, or has not been verified on any subscription level.

can_send_transactional

boolean

Whether a transactional email can currently be sent to this contact. false only if the contact has hard bounced or complained.

Example

Request

curl -X POST https://datamailer.example.com/api/contacts \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "learner@example.com",
    "audience": "dtc-courses",
    "client": "dtc-courses",
    "status": "subscribed",
    "tags": ["course-ml-zoomcamp"],
    "verified": true,
    "email_validation": {
      "status": "externally_validated",
      "reason": "client signup validation"
    }
  }'

Response

{
  "contact_id": 42,
  "email": "learner@example.com",
  "exists": true,
  "verified": true,
  "verified_at": "2024-09-01T10:00:00Z",
  "email_validation": {
    "status": "externally_validated",
    "reason": "client signup validation",
    "validated_at": "2024-09-01T10:00:00Z"
  },
  "global_unsubscribed": false,
  "hard_bounced": false,
  "complained": false,
  "audience": {
    "slug": "dtc-courses",
    "subscribed": false,
    "status": null,
    "verified": false,
    "verified_at": null,
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "client": {
    "slug": "dtc-courses",
    "subscribed": true,
    "status": "subscribed",
    "verified": true,
    "verified_at": "2024-09-01T10:00:00Z",
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "can_send_marketing": true,
  "can_send_transactional": true,
  "tags": ["course-ml-zoomcamp"]
}

Error codes

Validation errors return HTTP 400 (or 403 for client mismatch) with the following structure:

{
  "error": {
    "code": "validation_error",
    "fields": {
      "<field>": "<error_code>"
    }
  }
}

Field	Error code	Meaning
`email`	`required`	`email` was missing or blank.
`email`	`invalid`	`email` did not pass RFC 5321 format validation.
`audience`	`required`	`audience` was missing or blank.
`audience`	`not_found`	No audience with that slug exists in the authenticated client’s organization.
`client`	`required`	`client` was missing or blank.
`client`	`forbidden`	`client` does not match the authenticated client’s slug. Returns HTTP `403`.
`status`	`invalid`	`status` is not one of `pending`, `subscribed`, or `unsubscribed`.
`tags`	`must_be_list`	`tags` was provided but is not a JSON array.
`tags`	`must_be_non_empty_strings`	One or more tag entries are not non-empty strings.
`verified`	`must_be_boolean`	`verified` was provided but is not a boolean.
`email_validation`	`must_be_object`	`email_validation` was provided but is not a JSON object.
`email_validation.status`	`invalid`	`email_validation.status` is not a recognized `EmailValidationStatus` value.
`suppression`	`must_be_object`	`suppression` was provided but is not a JSON object.
`suppression.global_unsubscribed`	`must_be_boolean`	Suppression flag value is not a boolean.

Overview

Contacts

Subscriptions

Import & Export

Transactional

POST /api/contacts — Create or Update a Contact Record

Endpoint

Authentication

Request body

Response

Example

Request

Response

Error codes

Build docs developers (and LLMs) love

Overview

Contacts

Subscriptions

Import & Export

Transactional

Documentation Index

​Endpoint

​Authentication

​Request body

​Response

​Example

​Request

​Response

​Error codes

Build docs developers (and LLMs) love

Endpoint

Authentication

Request body

Response

Example

Request

Response

Error codes