# Organization API: Organizations & Members: Flows

> The 4 Organization API operations for flows.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/flows`](#op-get-api-v1-orgs-org-slug-flows) | List the automatic email flows, with their settings and how many emails each sent |
| GET | [`/api/v1/orgs/{org_slug}/flows/messages`](#op-get-api-v1-orgs-org-slug-flows-messages) | Read the log of flow emails, newest first |
| PUT | [`/api/v1/orgs/{org_slug}/flows/{key}`](#op-put-api-v1-orgs-org-slug-flows-key) | Turn an email flow on or off and change its settings |
| POST | [`/api/v1/orgs/{org_slug}/flows/{key}/test`](#op-post-api-v1-orgs-org-slug-flows-key-test) | Send a flow's sample email to yourself |

### List the automatic email flows, with their settings and how many emails each sent {#op-get-api-v1-orgs-org-slug-flows}

`GET /api/v1/orgs/{org_slug}/flows`

Every automatic email flow of the organization, whether or not it was ever turned on.

Needs the Admin or Owner role. There is one entry for each of ``unpaid_invoice``, ``stuck_setup``,
``free_upgrade``, ``winback``, ``onboarding`` and ``review_invite``. An entry has its ``label``, ``kind``
(``service`` flows are about the customer's own order and need no marketing consent, ``marketing`` flows
go only to customers who agreed to marketing email) and ``description``; ``enabled`` and ``config``, the
saved settings with the defaults filled in; ``fields``, what a form for the settings asks (``key``,
``label``, ``kind``, ``default``, ``min``, ``max``, ``hint``); ``template_slugs``, one for each step;
``blocked``, the sentence that says why the flow cannot send even when on (the review invitation needs a
saved Trustpilot review link), or null; and ``stats``, how many emails are ``scheduled``, ``sent``,
``skipped``, ``failed`` or ``canceled`` and ``last_sent_at``. Every flow is off until turned on. One customer
gets at most one flow email in 3 days, from any flow.

#### 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 log of flow emails, newest first {#op-get-api-v1-orgs-org-slug-flows-messages}

`GET /api/v1/orgs/{org_slug}/flows/messages`

Every email a flow scheduled, newest first, with what became of it.

Needs the Admin or Owner role. A row has ``flow``, ``step``, ``status``, ``email``, ``scheduled_at``,
``sent_at``, ``customer_id`` and ``error``. ``scheduled`` waits for the next pass (at most ten minutes),
``sent`` went to the mail server, ``skipped`` was left out on purpose (``error`` says why: the address
unsubscribed, the account is not active, another flow email went to the customer in the last 3 days, or
it was due more than a day ago), ``canceled`` lost its reason before it went (the invoice was paid, the
server is running, the customer withdrew consent, the flow was turned off) and ``failed`` was refused by
the mail server. ``count`` is the total that match, before ``limit`` and ``offset``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `flow` | query | string or null | no | Only this flow: unpaid_invoice, stuck_setup, free_upgrade, winback, onboarding or review_invite. |
| `status` | query | string or null | no | Only this status: scheduled, sent, skipped, failed or canceled. |
| `limit` | query | integer | no | How many rows to answer, 1 to 200. Default: `50`. |
| `offset` | query | integer | no | How many rows to skip. Default: `0`. |

#### Responses

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

### Turn an email flow on or off and change its settings {#op-put-api-v1-orgs-org-slug-flows-key}

`PUT /api/v1/orgs/{org_slug}/flows/{key}`

Turn a flow on or off and change its settings. Send only what changes.

Needs the Admin or Owner role. ``config`` keys replace the saved ones; GET lists them in ``fields`` with
their ranges. ``coupon_code`` (win-back) takes a coupon of the organization, or null to remove it. A value
that does not fit answers 422 with ``detail``, the sentence to show, and ``field``, the input it belongs
to (``config.after_days``, or ``enabled`` for the review invitation without a saved Trustpilot review
link), and changes nothing. The answer is ``{flow, changed}``: the flow as GET lists it and the names that
differ. Saving what is already saved changes nothing and writes no audit entry. A change is audited as
``flows.updated`` with the settings before and after. A flow starts mailing at its next pass, within ten
minutes, and only customers who qualify from then on.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | path | string | yes | The flow: unpaid_invoice, stuck_setup, free_upgrade, winback, onboarding or review_invite. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no | Turn the flow on or off. The review invitation can only be turned on once a Trustpilot review link is saved and on (422 otherwise). |
| `config` | object or null | no | The flow's settings to change, by name, as GET lists them in `fields`. A value outside its range answers 422 and changes nothing. |

#### Responses

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

### Send a flow's sample email to yourself {#op-post-api-v1-orgs-org-slug-flows-key-test}

`POST /api/v1/orgs/{org_slug}/flows/{key}/test`

Send the flow's email, filled with made-up facts, to the address of the signed-in member.

Needs the Admin or Owner role. The test goes out whether or not the flow is on, as service mail, with the
brand's own links and the flow's coupon code, and writes nothing to the flow log. An address on the
organization's unsubscribe list gets nothing (409). `step` picks the email of a flow with two (422 for a
step the flow lacks). The member needs an address on their account (400). At most ten test emails an hour
for one member (429). The answer is ``{sent, to, flow, step, template}``; 502 when the mail server did not
accept it. Audited as ``flows.test_sent``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | path | string | yes | The flow: unpaid_invoice, stuck_setup, free_upgrade, winback, onboarding or review_invite. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `step` | string or null | no | Which email of the flow to send, `1` or `2`. The default is `1`. Only unpaid_invoice and onboarding have a second step. |

#### Responses

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