Subscribers API

Cursor-paginated. Pass updated_since with the synced_through value from your previous run to fetch only what changed; you will occasionally re-see a row, so upsert by id. Deletes are not visible to updated_since.

Subscribers are distinct from contacts: a contact is a cold-outreach record, a subscriber is on a newsletter list. Creating one does not create the other.

Creates one subscriber. The email is normalised (trimmed and lower-cased) and must be unique within the team — a duplicate is a 409 resource_already_exists, not a silent upsert, unlike the v1 endpoint this replaces. When name is omitted it is composed from first_name and last_name, matching what the app does.

status accepts ENABLED or DISABLED. BLOCKLISTED cannot be written in either direction: it is the stored record of a global opt-out, owned by the unsubscribe and suppression machinery.

The new subscriber is on NO list — attach them with POST /lists/{listId}/subscribers, which requires lists:write and lets the list's own opt-in setting decide how the subscription starts. Subscribers are distinct from contacts: creating one does not create the other.

Automations do not run on subscribers created this way: a "subscriber is created" trigger will not fire, and no webhook is emitted.

Merge-patch: fields you omit are left alone, and null clears a nullable field (name is not nullable — clear it with ""). tags REPLACES the whole array — v1 merged them, this does not — while custom_fields merges key by key so a value written by an import is not lost; clear one custom field by sending it as null.

Changing email is allowed and must not collide with another subscriber in the team (409 resource_already_exists).

A BLOCKLISTED subscriber — someone who globally opted out — keeps that status: sending status for them is a 409 resource_state_invalid, because re-enabling an opt-out is not a routine write. Their other fields can still be edited.

List membership is not editable here — that is POST /lists/{listId}/subscribers under lists:write. Field-update automations do not run on edits made this way.

Permanent, and there is no undo — call with ?dry_run=true first.

The subscriber row is removed and their engagement trail goes with it: list memberships cascade — INCLUDING any per-list unsubscribe records, so re-creating the same address and re-adding it to a list would mail someone who had left that list — and open/click tracking rows are deleted. The send log is kept for campaign analytics with its email anonymised in the same transaction.

A GLOBAL opt-out survives: the suppression list is keyed by email address, not by subscriber, and deleting the subscriber does not touch it. This is also not a complete GDPR erasure for the person — the address may still appear as a contact or in the inbox; use the account data-erasure flow for that.