Add a subscriber

Adds a subscriber to the list, or, if the address is already on it, merges the attributes (new values win) and keeps its status. Needs scope write. A new subscriber answers 201; a re-add answers 200.

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`list_id`required	path	string · uuid	The list’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

CreateSubscriberRequest object · all fields required
attributesobject

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.
emailstring · email

The address; any case and surrounding whitespace are normalized.

example ann@example.com

Responses

200

The address was already on the list; its attributes were merged

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.

Subscriber object · all fields required
attributesobject

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

example ann@example.com
idstring · uuid

example 01900000-0000-7000-8000-000000000001
list_idstring · uuid

The list the subscriber is on.
project_idstring · uuid

The subscriber’s project.
soft_bounce_streakinteger · int32

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.

example active
unsubscribed_atstring · date-time | null

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

The latest change: creation, an attribute merge, a status change.

201

The subscriber was created

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.
`Location`	string	The subscriber’s URL

Subscriber object · all fields required
attributesobject

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

example ann@example.com
idstring · uuid

example 01900000-0000-7000-8000-000000000001
list_idstring · uuid

The list the subscriber is on.
project_idstring · uuid

The subscriber’s project.
soft_bounce_streakinteger · int32

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.

example active
unsubscribed_atstring · date-time | null

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

The latest change: creation, an attribute merge, a status change.

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope write (forbidden)

Problem (application/problem+json)

404

No such project or list, or another project’s (not_found)

Problem (application/problem+json)

409

The project or list is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): a bad email, an attribute that is not a scalar, a bad key, too many keys or too large; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)