`add_subscriber`

Adds a subscriber to a list, or merges attributes into one already on it.

Call it: to put an address on a list with its attributes.
Needs: an admin key with project_id, or a project key with scope write (its own project; the argument is ignored), and a list that is not deleted. Re-adding an address keeps its status and merges its attributes (new values win); null for an attribute removes it.
Returns: the subscriber, the same as POST /api/v1/projects/{project_id}/lists/{list_id}/subscribers (201 for a new subscriber, 200 on a re-add). There is no Idempotency-Key: the id is derived from the list and email, so a repeat is the same subscriber.

Arguments

object
emailstringrequired

The address; any case and surrounding whitespace are normalized.

example ann@example.com
list_idstring · uuidrequired

The list to add the subscriber to.
attributesmap of string → string | number | boolean | null

Attributes to set: a map of string, number or boolean values; null for a key removes it. Up to 64 keys, up to 4 KB of JSON.

default {}
project_idstring · uuid | null

The subscriber’s project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
attributesmap of string → string | number | boolean

The subscriber’s attributes: a map of string, number or boolean values.
confirmed_atstring · date-time | null

When the subscriber confirmed a double opt-in; null otherwise.
created_atstring · date-time
emailstring · email
idstring · uuid
list_idstring · uuid

The list the subscriber is on.
project_idstring · uuid

The subscriber’s project.
soft_bounce_streakinteger · uint32

Soft bounces in a row; reset by a delivery (P4+).

≥ 0
sourcestring

How the subscriber was added: api, import or confirm.
statusstring

pending, active, unsubscribed, bounced or complained.
unsubscribed_atstring · date-time | null

When the subscriber unsubscribed; null otherwise.
updated_atstring · date-time

The latest change: creation, an attribute merge.

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors