Lists API

Cursor-paginated. Pass updated_since with the synced_through value from your previous run to fetch only what changed.

subscriber_count is not on this response — it costs one COUNT(*) per list and would be 100 of them on a full page. Retrieve a single list to get it, or page GET /lists/{listId}/subscribers.

Creates one empty list. Names are NOT required to be unique — the app does not enforce it either, so two lists may share a name and are told apart by id.

optin decides how a subscription to this list starts: on a SINGLE list a new member is CONFIRMED immediately, on a DOUBLE list they are UNCONFIRMED until they click a confirmation link. Choose it now — changing it later does not revisit the members already on the list.

Includes subscriber_count: every subscriber who is a member of this list, whatever their status and whatever their per-list subscription state.

Merge-patch: fields you omit are left alone. Nothing on a list is nullable, so sending null for a field is a 400 — clear description with "" and tags with [].

Changing optin applies to FUTURE members only. Moving a list from SINGLE to DOUBLE does not retroactively unconfirm anyone already on it, and moving it the other way does not confirm anyone.

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

The subscribers on the list are NOT deleted; they keep every other list they are on. What is removed is their membership of THIS list, including any record that someone had unsubscribed from it — so re-creating the list and re-adding the same people will mail addresses that had opted out of it. Prefer leaving an unused list in place.

Two references are silently detached rather than blocked. A newsletter campaign that targeted this list keeps its targeting row with the list unset (the list NAME is retained on it for reporting), and any integration configured to sync into this list is left with no destination and will stop delivering into it. Check both before deleting a list something else feeds.

The members of one list, in the same subscriber shape and with the same filters as GET /subscribers. Cursor-paginated, and updated_since tracks the SUBSCRIBER's updated_at, not the membership row's — so a subscriber added to this list without being edited will not appear in an incremental poll. Do a full walk when you need membership changes.

Requires subscribers:read, not lists:read: this returns people, not lists. It is exactly equivalent to GET /subscribers?list_id=, which is gated the same way.

The membership record itself is never returned. It holds a double-opt-in confirmation token, which is a bearer secret.

Attaches subscribers that already exist in your team to this list, up to 100 per call. It never CREATES a subscriber — that is subscribers:write — so an id with no subscriber behind it comes back under not_found rather than being minted.

Partial success is the normal outcome and the response says exactly which ids landed where: added, already_member (left alone, so re-posting the same batch is safe), unsubscribed and not_found.

Someone who previously unsubscribed from this list is NOT re-added. They are reported under unsubscribed and their opt-out stands; re-subscribing an opt-out is a deliberate act and this endpoint is the routine one.

New members start CONFIRMED on a SINGLE opt-in list and UNCONFIRMED on a DOUBLE one, decided by the list — there is no request field that overrides it. Note that on a DOUBLE list this endpoint sends no confirmation email, so those members stay unmailable until they confirm through one of your own flows.

Automations do not run on membership added this way: a "subscriber joins list" trigger will not fire for these people.

Removes one subscriber from this list's mailable membership by marking their subscription UNSUBSCRIBED.

The membership record is deliberately KEPT rather than deleted, which is why this answers with the membership rather than deleted: true. The record IS the opt-out: deleting it would leave nothing to say this person had ever left, and the next POST /lists/{listId}/subscribers would silently re-add them and start mailing them again. For the same reason this is not reversible through the API — re-adding them reports unsubscribed and changes nothing.

The subscriber itself is untouched and keeps every other list they are on. They still count towards this list's subscriber_count, which counts membership rather than mailability.

Calling this again is a no-op that succeeds. A subscriber who was never on the list is a 404.