---
title: "Automations API"
description: "Automations in the OneSend API: 19 endpoints. Method, path, parameters, request body and response shape for each."
url: https://onesend.email/docs/api-reference/automations/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Automations

Automated journeys: a trigger (list, form, attribute change, custom event, date, campaign engagement, conversion or manual) and steps (emails, waits, branches, attribute and list updates, webhooks, splits), with versions, test runs and reports per step.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List automations

GET `/v1/automations`

Newest first, with run counts (entered, in progress, completed, exited).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 50. 1 to 200. |
| `status` | query | `string` | Comma-separated: draft, active, paused, stopped. |
| `q` | query | `string` |  |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "automation",
    "name": string,
    "description": string or null,
    "status": "draft" | "active" | "paused" | "stopped",
    "trigger": object,
    "steps": [object],
    "settings": object,
    "goals": [object],
    "version": number,
    "stats": {
      "entered": number,
      "active": number,
      "completed": number,
      "exited": number,
      "failed": number
    },
    "activatedAt": string or null,
    "createdAt": string,
    "updatedAt": string,
    "webhookDisabledReason": string or null
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Create an automation

POST `/v1/automations`

Created as a draft. Activate it with `POST /v1/automations/{id}/activate`. A `webhook` step (it sends contact data to a URL) needs a signed-in admin or a live `admin` key (403 otherwise), and the workspace owners get a security alert.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` |  |
| `description` | `string or null` |  |
| `recipe` | `string` | Create from a starter recipe (GET /v1/automations/recipes). Fields you send override the recipe. |
| `trigger` | `object` |  |
| `steps` | `array of object` | At most 200 items. |
| `settings` | `object` |  |
| `settings.reentry` | `object` | `never`: once per contact. `after`: again `days` after the last entry. `always`: whenever the contact has no run in progress. |
| `settings.reentry.mode`required | `"never" \| "after" \| "always"` |  |
| `settings.reentry.days` | `integer or null` |  |
| `settings.maxActiveRuns` | `integer or null` |  |
| `settings.frequencyCap` | `object or null` | At most `emails` automation emails per contact in `hours`, across every automation. Later emails wait. |
| `settings.frequencyCap.emails`required | `integer` |  |
| `settings.frequencyCap.hours`required | `number` |  |
| `settings.quietHours` | `object or null` |  |
| `settings.quietHours.start`required | `string` | Local time HH:MM in the workspace time zone. |
| `settings.quietHours.end`required | `string` | Local time HH:MM in the workspace time zone. |
| `settings.testMode` | `boolean` | Emails are logged but not delivered. |
| `settings.exitOnUnsubscribe` | `boolean` |  |
| `settings.exitConditions` | `array of object or null` |  |
| `settings.includeInactive` | `boolean` |  |
| `settings.includeQualityIssues` | `boolean` |  |
| `settings.migrateRuns` | `"safe" \| "none"` |  |
| `goals` | `array of object` | At most 10 items. |

### Responses

`201` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Automation recipes

GET `/v1/automations/recipes`

Complete automations to start from: welcome series, double opt-in follow-up, abandoned cart, win-back, renewal reminder and post-purchase review request. Create one with `POST /v1/automations` and `recipe`.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "name": string,
    "description": string,
    "definition": object
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Get an automation

GET `/v1/automations/{id}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Edit an automation

PATCH `/v1/automations/{id}`

A draft is edited in place. Changing the trigger, steps, settings or goals of an active or paused automation publishes a new version: new entries use it, and runs in progress move to it when their current step still exists with the same type (unless `settings.migrateRuns` is `none`). The new definition must be valid (400 `automation_invalid`).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `description` | `string or null` |  |
| `trigger` | `object` |  |
| `steps` | `array of object` | At most 200 items. |
| `settings` | `object` |  |
| `settings.reentry` | `object` | `never`: once per contact. `after`: again `days` after the last entry. `always`: whenever the contact has no run in progress. |
| `settings.reentry.mode`required | `"never" \| "after" \| "always"` |  |
| `settings.reentry.days` | `integer or null` |  |
| `settings.maxActiveRuns` | `integer or null` |  |
| `settings.frequencyCap` | `object or null` | At most `emails` automation emails per contact in `hours`, across every automation. Later emails wait. |
| `settings.frequencyCap.emails`required | `integer` |  |
| `settings.frequencyCap.hours`required | `number` |  |
| `settings.quietHours` | `object or null` |  |
| `settings.quietHours.start`required | `string` | Local time HH:MM in the workspace time zone. |
| `settings.quietHours.end`required | `string` | Local time HH:MM in the workspace time zone. |
| `settings.testMode` | `boolean` | Emails are logged but not delivered. |
| `settings.exitOnUnsubscribe` | `boolean` |  |
| `settings.exitConditions` | `array of object or null` |  |
| `settings.includeInactive` | `boolean` |  |
| `settings.includeQualityIssues` | `boolean` |  |
| `settings.migrateRuns` | `"safe" \| "none"` |  |
| `goals` | `array of object` | At most 10 items. |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Delete an automation

DELETE `/v1/automations/{id}`

Pause or stop an active automation first. Runs and step history are deleted; emails it sent stay in the email logs.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Check an automation

POST `/v1/automations/{id}/validate`

Every problem that would stop activation, with the step it belongs to.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "valid": boolean,
  "problems": [{
    "stepId": string or null,
    "field": string,
    "message": string
  }]
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Activate (or resume) an automation

POST `/v1/automations/{id}/activate`

Publishes the current definition as a new version when it changed, then starts accepting entries. A paused automation resumes: runs continue where they were. Fails with 400 `automation_invalid` and `details.problems` when something is missing.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 402, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `402` Payment required (type `payment_required`): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled, `plan_required` (the workspace has no plan; `details.upgradeUrl`).
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Pause an automation

POST `/v1/automations/{id}/pause`

No new entries, and runs in progress wait where they are until the automation is activated again.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Stop an automation

POST `/v1/automations/{id}/stop`

No new entries, and every run in progress is canceled. It can be activated again later.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation",
  "name": string,
  "description": string or null,
  "status": "draft" | "active" | "paused" | "stopped",
  "trigger": object,
  "steps": [object],
  "settings": object,
  "goals": [object],
  "version": number,
  "stats": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "activatedAt": string or null,
  "createdAt": string,
  "updatedAt": string,
  "webhookDisabledReason": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Enroll contacts

POST `/v1/automations/{id}/enroll`

Up to 1,000 contacts by id or email, or a whole list or segment (in the background). Re-entry rules, trigger conditions and the most runs in progress apply; unsubscribed, bounced and complained contacts are skipped. Works with any trigger type.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `contactIds` | `array of string` | At most 1000 items. |
| `emails` | `array of string (email)` | At most 1000 items. |
| `listId` | `string` | Enroll the whole list in the background. |
| `segmentId` | `string` | Enroll the whole segment in the background. |

### Responses

`202` Success

```
{
  "enrollmentId": string,
  "background": boolean,
  "enrolled": number,
  "notFound": number,
  "skipped": map of number
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Test with one contact

POST `/v1/automations/{id}/test`

`dryRun: true` (default) walks the current definition for the contact without sending or changing anything and returns the path, with the subject of each email and the time each step would run. `dryRun: false` starts a real run on the published version with emails sandboxed (logged, not delivered); the automation must be active.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `contactId` | `string` |  |
| `email` | `string (email)` |  |
| `dryRun` | `boolean` | `true`: preview the path without sending or changing anything. `false`: a real run on the published version with emails sandboxed. Default true. |
| `event` | `object` | Dry run: the trigger event to use for {{event.x}} variables and event conditions. |
| `event.name`required | `string` |  |
| `event.properties` | `object` |  |

### Responses

`200` Success

```
object
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Automation report

GET `/v1/automations/{id}/report`

Runs entered, in progress, completed and exited (with reasons); goal reached; email results (sent, delivered, opened, clicked, converted, revenue); and per step: runs at the step now, runs that finished it, outcomes (sent or skipped, yes or no, split paths) and email results. Rates: open and click = unique / delivered.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "automation": {
    "id": string,
    "object": "automation",
    "name": string,
    "description": string or null,
    "status": "draft" | "active" | "paused" | "stopped",
    "trigger": object,
    "steps": [object],
    "settings": object,
    "goals": [object],
    "version": number,
    "stats": {
      "entered": number,
      "active": number,
      "completed": number,
      "exited": number,
      "failed": number
    },
    "activatedAt": string or null,
    "createdAt": string,
    "updatedAt": string,
    "webhookDisabledReason": string or null
  },
  "runs": {
    "entered": number,
    "active": number,
    "completed": number,
    "exited": number,
    "failed": number
  },
  "goalReached": number,
  "exitReasons": map of number,
  "emails": {
    "sent": number,
    "delivered": number,
    "opened": number,
    "clicked": number,
    "converted": number,
    "revenue": number,
    "bounced": number,
    "unsubscribed": number,
    "complained": number,
    "total": number,
    "rates": {
      "delivery": number,
      "open": number,
      "click": number,
      "conversion": number
    }
  },
  "steps": [{
    "stepId": string,
    "type": string,
    "name": string or null,
    "inStep": number,
    "completed": number,
    "outcomes": map of number,
    "emails": {
      "sent": number,
  …
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## List runs

GET `/v1/automations/{id}/runs`

One run per contact and entry, newest first.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 50. 1 to 200. |
| `status` | query | `string` | Comma-separated run statuses. |
| `stepId` | query | `string` |  |
| `contactId` | query | `string` |  |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "automation_run",
    "automationId": string,
    "automationName": string or null,
    "version": number,
    "contactId": string,
    "email": string or null,
    "status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
    "stepId": string or null,
    "waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
    "nextRunAt": string or null,
    "exitReason": string or null,
    "lastError": string or null,
    "test": boolean,
    "emailsSent": number,
    "goalReachedAt": string or null,
    "enteredAt": string,
    "completedAt": string or null
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Get a run with its step history

GET `/v1/automations/{id}/runs/{runId}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `runId`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation_run",
  "automationId": string,
  "automationName": string or null,
  "version": number,
  "contactId": string,
  "email": string or null,
  "status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
  "stepId": string or null,
  "waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
  "nextRunAt": string or null,
  "exitReason": string or null,
  "lastError": string or null,
  "test": boolean,
  "emailsSent": number,
  "goalReachedAt": string or null,
  "enteredAt": string,
  "completedAt": string or null,
  "steps": [{
    "stepId": string,
    "type": string,
    "outcome": string,
    "detail": object or null,
    "messageId": string or null,
    "at": string
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Remove a contact from an automation

POST `/v1/automations/{id}/runs/{runId}/exit`

Ends a run in progress (exit reason `removed`).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `runId`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "automation_run",
  "automationId": string,
  "automationName": string or null,
  "version": number,
  "contactId": string,
  "email": string or null,
  "status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
  "stepId": string or null,
  "waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
  "nextRunAt": string or null,
  "exitReason": string or null,
  "lastError": string or null,
  "test": boolean,
  "emailsSent": number,
  "goalReachedAt": string or null,
  "enteredAt": string,
  "completedAt": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Published versions

GET `/v1/automations/{id}/versions`

Newest first, with the number of runs still in progress on each.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "data": [{
    "version": number,
    "trigger": object,
    "steps": [object],
    "settings": object,
    "goals": [object],
    "createdAt": string,
    "runsInProgress": number
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Webhook step signing secret

GET `/v1/automations/{id}/signing-secret`

Webhook steps sign their requests with this secret: `x-onesend-signature: v1=<HMAC-SHA256 of "<x-onesend-timestamp>.<body>">`, as outgoing webhooks do.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "secret": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Rotate the signing secret

POST `/v1/automations/{id}/rotate-secret`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "secret": string
}
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
