Organization API: Organizations & Members: Subscribers

Part of Organizations & Members.

GET /api/v1/orgs/{org_slug}/subscribers

The addresses visitors gave the storefront's newsletter form, newest first.

Needs the Admin or Owner role. Every row is one address: id, email, source (where it was collected), consent (whether the visitor agreed to email), consent_text (the words they agreed to), customer_id (the customer with that address, if there is one), suppressed (true when the address is on the suppression list and gets no marketing email whatever its consent says) and created_at. Filter by part of the address with q, by source and by consent; total is every lead the filters match. counts covers the whole organization: leads (every lead), consenting_customers (active customers who agreed to marketing email) and suppressed (addresses on the suppression list).

GET /api/v1/orgs/{org_slug}/subscribers/export.csv

Every address the organization may send marketing email to, as a CSV file.

Needs the Admin or Owner role. The columns are email, source, consent, kind (lead or customer) and created_at. The file lists leads who agreed to email and active customers who agreed to marketing email, once for each address (an address that is both is a lead). It never lists an address on the suppression list. A cell that starts with =, +, - or @ begins with an apostrophe so a spreadsheet does not run it. A file holds at most 100,000 rows and the answer's X-Export-Truncated: true header says when a list was longer. At most 12 exports an hour (429). Every export is audited as subscribers.exported before the file is answered.

GET /api/v1/orgs/{org_slug}/subscribers/settings

Whether the newsletter form is on, whether it asks for a Turnstile check and the words beside its checkbox.

Needs the Admin or Owner role. The form is off until an admin turns it on: while it is off, the storefront's POST /storefront/newsletter answers 404. consent_text is what a sign-up stores as the visitor's agreement when the form sends no words of its own, and default_consent_text is what an empty text falls back to.

PUT /api/v1/orgs/{org_slug}/subscribers/settings

Change the newsletter form's settings. Send only what changes.

Needs the Admin or Owner role. consent_text is at most 300 characters and an empty one goes back to the default words; a longer one answers 422 {"detail", "field"}. The answer is the same as the GET plus changed, the keys that differ from before. A save that changes nothing writes no audit entry; a change is audited as subscribers.settings_updated with the values before and after.

application/json (required)

GET /api/v1/orgs/{org_slug}/subscribers/suppressions

The organization's suppression list, newest first.

Needs the Admin or Owner role. An address on the list gets no marketing email, whatever its owner's consent says. Every row has id, email, reason (unsubscribed, bounced, complained or manual), source (link, account, console or api) and created_at. Filter by part of the address with q; total is every row that matches. The list belongs to this organization alone: an address another brand suppressed is not here.

POST /api/v1/orgs/{org_slug}/subscribers/suppressions

Stop marketing email to one address.

Needs the Admin or Owner role. reason must be manual (the other reasons are set by an unsubscribe, a bounce or a complaint). The row's source is console. Adding an address cancels the flow emails still waiting for it, takes marketing consent back from a customer with that address and marks a lead with it as not consenting. An address already on the list stays as it was and the answer has added: false. A bad address or reason answers 422 {"detail", "field"}. The answer is {suppression, added} and a new entry is audited as suppression.added.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/subscribers/suppressions/{suppression_id}

Let marketing email reach an address again.

Needs the Admin or Owner role. This removes the row only: it does not give anyone's consent back, so a customer or lead who withdrew still has to agree again before they get marketing email. 404 for an id that is not on this organization's list. Audited as suppression.lifted.

DELETE /api/v1/orgs/{org_slug}/subscribers/{lead_id}

Delete one lead for good.

Needs the Admin or Owner role. Only the lead row goes: the customer with that address, their consent and the suppression list are not touched, so an address that unsubscribed stays unsubscribed. 404 for an id that is not this organization's lead. Audited as subscriber.deleted with the lead's id and source, never its address.