# Organization API: Organizations & Members: Subscribers

> The 8 Organization API operations for subscribers.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/subscribers/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/subscribers`](#op-get-api-v1-orgs-org-slug-subscribers) | List the newsletter's leads and count who can be mailed |
| GET | [`/api/v1/orgs/{org_slug}/subscribers/export.csv`](#op-get-api-v1-orgs-org-slug-subscribers-export-csv) | Download the addresses that can be mailed as a CSV file |
| GET | [`/api/v1/orgs/{org_slug}/subscribers/settings`](#op-get-api-v1-orgs-org-slug-subscribers-settings) | Read the newsletter form's settings |
| PUT | [`/api/v1/orgs/{org_slug}/subscribers/settings`](#op-put-api-v1-orgs-org-slug-subscribers-settings) | Turn the newsletter form on or off and change its words |
| GET | [`/api/v1/orgs/{org_slug}/subscribers/suppressions`](#op-get-api-v1-orgs-org-slug-subscribers-suppressions) | List the addresses that get no marketing email |
| POST | [`/api/v1/orgs/{org_slug}/subscribers/suppressions`](#op-post-api-v1-orgs-org-slug-subscribers-suppressions) | Add an address to the suppression list |
| DELETE | [`/api/v1/orgs/{org_slug}/subscribers/suppressions/{suppression_id}`](#op-delete-api-v1-orgs-org-slug-subscribers-suppressions-suppression-id) | Take an address off the suppression list |
| DELETE | [`/api/v1/orgs/{org_slug}/subscribers/{lead_id}`](#op-delete-api-v1-orgs-org-slug-subscribers-lead-id) | Delete a lead |

### List the newsletter's leads and count who can be mailed {#op-get-api-v1-orgs-org-slug-subscribers}

`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).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no | Part of the address. |
| `source` | query | string or null | no | Only leads that came from this source. |
| `consent` | query | boolean or null | no | true for leads who agreed to email, false for the rest. |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Download the addresses that can be mailed as a CSV file {#op-get-api-v1-orgs-org-slug-subscribers-export-csv}

`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.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Read the newsletter form's settings {#op-get-api-v1-orgs-org-slug-subscribers-settings}

`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.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Turn the newsletter form on or off and change its words {#op-put-api-v1-orgs-org-slug-subscribers-settings}

`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.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no | Whether the storefront's newsletter form accepts sign-ups. |
| `turnstile` | boolean or null | no | Whether the form asks for a Turnstile check. It applies when the brand has Turnstile keys. |
| `consent_text` | string or null | no | The words beside the form's checkbox, at most 300 characters. An empty text goes back to the default. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List the addresses that get no marketing email {#op-get-api-v1-orgs-org-slug-subscribers-suppressions}

`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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no | Part of the address. |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add an address to the suppression list {#op-post-api-v1-orgs-org-slug-subscribers-suppressions}

`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``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | The address that gets no marketing email. |
| `reason` | string | no | Why it is on the list. A person adds an address with the reason "manual". |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Take an address off the suppression list {#op-delete-api-v1-orgs-org-slug-subscribers-suppressions-suppression-id}

`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``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `suppression_id` | path | integer | yes | The id of a row of the suppression list. |
| `org_slug` | path | string | yes |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete a lead {#op-delete-api-v1-orgs-org-slug-subscribers-lead-id}

`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.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `lead_id` | path | integer | yes | The id of a lead. |
| `org_slug` | path | string | yes |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |