Email Marketing

Batch sync

Move a list in one call. Each row is validated on its own, so a bad address does not roll back the rows that succeeded.

Request

POST/api/v1/email/contacts/batchcontacts:write

audienceId	Required. Every row is added to this audience.
contacts	Required array. At most 500 objects. Each object needs email.
defaultStatus	Optional. subscribed, pending, or unsubscribed. Defaults to subscribed.

A row may set its own status, firstName, lastName, tags, and attributes. Tags are merged with tags already on that contact.

curl

curl -sS https://api.thealtermeai.com/api/v1/email/contacts/batch \
  -H "Authorization: Bearer emk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audienceId": "YOUR_AUDIENCE_ID",
    "defaultStatus": "subscribed",
    "contacts": [
      { "email": "[email protected]", "firstName": "Ada" },
      { "email": "[email protected]", "status": "pending" }
    ]
  }'

Response

The body reports succeeded, failed, and a results array. At least one success returns 200. If every row fails validation, the status is 400. This response includes X-MCOS-Key-Environment.

Duplicate and existing emails

Each row upserts on email for your organization. Addresses already on the target audience (or only on other audiences) are updated or linked — they do not fail the batch. Read Contacts → Re-imports and partial success for CSV behavior, unsubscribe rules, and how identity works across lists.