Skip to main content
POST
Add Recipients
Append-only bulk add: up to 1000 entries per request, each a plain email address or an object with email plus optional name, external_id and attributes. Each address is validated individually; invalid entries are reported in the invalid array rather than failing the batch. Addresses are deduplicated case-insensitively, and addresses already on the list — active, removed or unsubscribed — are counted in skipped_existing and left untouched, so re-syncing never resurrects an opt-out. A list holds at most 500 active recipients.
To keep a list in sync with another system (update names, reactivate removed contacts, change an address by external_id), use Upsert Recipients instead. This endpoint never modifies an existing recipient.

Authentication

This endpoint requires an API token passed as a Bearer token in the Authorization header.
API tokens are created in the Dashboard under API Keys. The list must belong to the token’s project.

Path Parameters

string
required
The mailing list’s unique identifier (UUID). List ids come from List Mailing Lists.

Body

(string | object)[]
required
Between 1 and 1000 entries. A plain string is an email address; an object carries email (required) plus optional name, external_id and attributes — the same shape as Upsert Recipients.

Request

Response

integer
required
Number of addresses added to the list
integer
required
Number of entries already on the list in any status (including unsubscribed ones, which are never re-activated)
string[]
required
Addresses that failed validation and were not added

Example Response

200

Errors

Rate Limits

This endpoint is limited to 30 requests per minute per IP.