---
title: "Emails API"
description: "Emails in the OneSend API: 6 endpoints. Send, inspect and cancel email. Each email shows the providers it was routed through."
url: https://onesend.email/docs/api-reference/emails/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Emails

Send, inspect and cancel email. Each email shows the providers it was routed through.

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 emails

GET `/v1/emails`

Filter by status, provider (provider id or connection id), tag, free-text (`q` on recipients/subject) and time range.

**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` |  |
| `provider` | query | `string` |  |
| `tag` | query | `string` |  |
| `q` | query | `string` |  |
| `from` | query | `string (date-time)` |  |
| `until` | query | `string (date-time)` |  |
| `rerouted` | query | `"true" \| "false"` |  |
| `source` | query | `string` |  |
| `type` | query | `"transactional" \| "broadcast"` |  |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "email",
    "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
    "type": "transactional" | "broadcast",
    "from": string,
    "to": [string],
    "cc": [string] or null,
    "bcc": [string] or null,
    "subject": string,
    "tags": [string],
    "metadata": map of string or null,
    "templateId": string or null,
    "source": "api" | "smtp" | "mcp" | "dashboard" | "broadcast",
    "connectionId": string or null,
    "provider": string or null,
    "providerMessageId": string or null,
    "attemptCount": number,
    "lastError": string or null,
    "openCount": number,
    "clickCount": number,
    "scheduledAt": string or null,
    "sentAt": string or null,
    "createdAt": string
  }],
  "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`)

## Send an email

POST `/v1/emails`

Queues an email and routes it through your providers by policy, failing over on provider errors (never on recipient errors). Pass `Idempotency-Key` to make retries safe. Use `template` + `variables` to render a stored template.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `idempotency-key` | header | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `from`required | `string` | Sender: `a@b.com` or `Name <a@b.com>`. The domain should be added under Domains so providers accept it. |
| `to`required | `string or array of string` | One address or a list (at most 50). Each is `a@b.com` or `Name <a@b.com>`. |
| `cc` | `string or array of string` | Carbon copy: one address or a list. |
| `bcc` | `string or array of string` | Blind carbon copy: one address or a list. |
| `replyTo` | `string or array of string` | Reply-To address or addresses. |
| `subject` | `string` | Subject line. Optional with `template` (the template subject is used). `{{variables}}` are filled in like the body. |
| `html` | `string` | HTML body (at most 5 MB). `{{variables}}` and system variables such as `{{unsubscribe_url}}` are filled in. |
| `text` | `string` | Plain-text body (at most 2 MB). |
| `template` | `string` | Template id or slug. Renders the published version (or the latest) with `variables`. |
| `variables` | `object` | Values for `{{variables}}` in the subject, html and template. Missing ones render empty and are listed in `warnings`. |
| `headers` | `map of string` | Extra headers. Reserved names (To, Cc, Bcc, From, Subject, Reply-To, …) are refused. |
| `attachments` | `array of object` | Up to 20 files, each with `content` (base64) or a public `url`. At most 20 items. |
| `attachments[].filename`required | `string` | File name shown to the recipient. |
| `attachments[].content` | `string` | Base64 content (at most 10 MB). |
| `attachments[].url` | `string (uri)` | Public http(s) URL to fetch instead of `content`. |
| `attachments[].contentType` | `string` | MIME type, for example application/pdf. |
| `tags` | `array of string` | Labels for filtering logs and statistics, and for routing rules. At most 20 items. |
| `metadata` | `map of string` | Your own key/value data, returned with the email and in webhooks. |
| `type` | `"transactional" \| "broadcast"` | `transactional` (default) or `broadcast` (marketing: adds List-Unsubscribe, honours broadcast unsubscribes and only uses providers that allow campaigns). Default "transactional". |
| `policy` | `string` | Routing policy id or name. Defaults to the workspace default policy. |
| `provider` | `string` | Force one sending provider (connection id). Skips routing order and failover. |
| `scheduledAt` | `string (date-time)` | Send later: an ISO 8601 time with an offset, for example 2030-01-01T09:00:00+01:00. |
| `tracking` | `object` | Open and click tracking for this email. Wins over the sending domain's tracking settings, which win over the workspace defaults. |
| `tracking.opens` | `boolean` |  |
| `tracking.clicks` | `boolean` |  |

### Responses

`202` Success

```
{
  "id": string,
  "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
  "warnings": [string]
}
```

**Errors: 400, 401, 402, 403, 404, 409, 413, 415, 422, 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`. Sending: an API key past its expiry (`key_expired`).
- `402` Payment required (type `payment_required`), for live email only (test keys and Sandbox mode are never refused): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled (they are off by default), `plan_required` (the workspace has no plan), `email_limit` (the month's emails are used, counted per recipient; `details.resetsAt`) and `domain_limit` (the plan sends from its own domains only), with `details.upgradeUrl` where to change the plan.
- `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`. Sending: a recipient outside the key's recipient allowlist (`recipient_not_allowed`), a key used from an address it does not allow (`ip_not_allowed`), a sender domain the key may not use (`domain_not_allowed`), a session that needs two-factor authentication (`two_factor_required`) or a role that cannot send (`insufficient_role`).
- `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`)
- `422` Unprocessable (type `invalid_request`): `no_provider_for_domain`, no sending provider of the routing path may or can send for the From domain; `details.candidates` says why each provider was left out. Live email only.
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`) Sending: the key's hourly or daily send limit (`key_rate_limited`); retry after `Retry-After` seconds.
- `500` Unexpected server error (`internal`)

## Send up to 100 emails

POST `/v1/emails/batch`

Every item is validated (templates, providers, policies, headers, plan and key limits, and whether a provider can send for its From domain) before any is sent: one invalid item rejects the whole batch with its error (400, 402, 403, 404, 422 or 429) and `details.index`, and nothing is queued. The plan's monthly emails and the key's send limits must have room for the whole batch. Each email is then routed independently. With `Idempotency-Key`, item _i_ uses `<key>:<i>`.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `idempotency-key` | header | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `emails`required | `array of object` | At most 100 items. |
| `emails[].from`required | `string` | Sender: `a@b.com` or `Name <a@b.com>`. The domain should be added under Domains so providers accept it. |
| `emails[].to`required | `string or array of string` | One address or a list (at most 50). Each is `a@b.com` or `Name <a@b.com>`. |
| `emails[].cc` | `string or array of string` | Carbon copy: one address or a list. |
| `emails[].bcc` | `string or array of string` | Blind carbon copy: one address or a list. |
| `emails[].replyTo` | `string or array of string` | Reply-To address or addresses. |
| `emails[].subject` | `string` | Subject line. Optional with `template` (the template subject is used). `{{variables}}` are filled in like the body. |
| `emails[].html` | `string` | HTML body (at most 5 MB). `{{variables}}` and system variables such as `{{unsubscribe_url}}` are filled in. |
| `emails[].text` | `string` | Plain-text body (at most 2 MB). |
| `emails[].template` | `string` | Template id or slug. Renders the published version (or the latest) with `variables`. |
| `emails[].variables` | `object` | Values for `{{variables}}` in the subject, html and template. Missing ones render empty and are listed in `warnings`. |
| `emails[].headers` | `map of string` | Extra headers. Reserved names (To, Cc, Bcc, From, Subject, Reply-To, …) are refused. |
| `emails[].attachments` | `array of object` | Up to 20 files, each with `content` (base64) or a public `url`. At most 20 items. |
| `emails[].attachments[].filename`required | `string` | File name shown to the recipient. |
| `emails[].attachments[].content` | `string` | Base64 content (at most 10 MB). |
| `emails[].attachments[].url` | `string (uri)` | Public http(s) URL to fetch instead of `content`. |
| `emails[].attachments[].contentType` | `string` | MIME type, for example application/pdf. |
| `emails[].tags` | `array of string` | Labels for filtering logs and statistics, and for routing rules. At most 20 items. |
| `emails[].metadata` | `map of string` | Your own key/value data, returned with the email and in webhooks. |
| `emails[].type` | `"transactional" \| "broadcast"` | `transactional` (default) or `broadcast` (marketing: adds List-Unsubscribe, honours broadcast unsubscribes and only uses providers that allow campaigns). Default "transactional". |
| `emails[].policy` | `string` | Routing policy id or name. Defaults to the workspace default policy. |
| `emails[].provider` | `string` | Force one sending provider (connection id). Skips routing order and failover. |
| `emails[].scheduledAt` | `string (date-time)` | Send later: an ISO 8601 time with an offset, for example 2030-01-01T09:00:00+01:00. |
| `emails[].tracking` | `object` | Open and click tracking for this email. Wins over the sending domain's tracking settings, which win over the workspace defaults. |
| `emails[].tracking.opens` | `boolean` |  |
| `emails[].tracking.clicks` | `boolean` |  |

### Responses

`202` Success

```
{
  "data": [{
    "id": string,
    "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
    "warnings": [string]
  }]
}
```

**Errors: 400, 401, 402, 403, 404, 409, 413, 415, 422, 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`. Sending: an API key past its expiry (`key_expired`).
- `402` Payment required (type `payment_required`), for live email only (test keys and Sandbox mode are never refused): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled (they are off by default), `plan_required` (the workspace has no plan), `email_limit` (the month's emails are used, counted per recipient; `details.resetsAt`) and `domain_limit` (the plan sends from its own domains only), with `details.upgradeUrl` where to change the plan.
- `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`. Sending: a recipient outside the key's recipient allowlist (`recipient_not_allowed`), a key used from an address it does not allow (`ip_not_allowed`), a sender domain the key may not use (`domain_not_allowed`), a session that needs two-factor authentication (`two_factor_required`) or a role that cannot send (`insufficient_role`).
- `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`)
- `422` Unprocessable (type `invalid_request`): `no_provider_for_domain`, no sending provider of the routing path may or can send for the From domain; `details.candidates` says why each provider was left out. Live email only.
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`) Sending: the key's hourly or daily send limit (`key_rate_limited`); retry after `Retry-After` seconds.
- `500` Unexpected server error (`internal`)

## Get an email with its routing attempts and events

GET `/v1/emails/{id}`

Test-mode keys only see sandboxed emails (404 otherwise): every sandboxed email of the workspace, whichever test key sent it. Reading needs a `read` or `full` key; a `send` key, the default, gets 403 `insufficient_scope`.

**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": "email",
  "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
  "type": "transactional" | "broadcast",
  "from": string,
  "to": [string],
  "cc": [string] or null,
  "bcc": [string] or null,
  "subject": string,
  "tags": [string],
  "metadata": map of string or null,
  "templateId": string or null,
  "source": "api" | "smtp" | "mcp" | "dashboard" | "broadcast",
  "connectionId": string or null,
  "provider": string or null,
  "providerMessageId": string or null,
  "attemptCount": number,
  "lastError": string or null,
  "openCount": number,
  "clickCount": number,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "createdAt": string,
  "html": string or null,
  "text": string or null,
  "attempts": [{
    "id": string,
    "seq": number,
    "connectionId": string,
    "provider": string,
    "outcome": "success" | "retry_next" | "retry_same" | "recipient_fatal" | "config_fatal" | "skipped",
    "errorCode": string or null,
    "errorMessage": string or null,
    "httpStatus": number or null,
    "latencyMs": number or null,
    "createdAt": string
  }],
  "events": [{
    "id": string,
    "type": string,
    "messageId": string or null,
    "provider": string or null,
    "connectionId": string or null,
    "recipient": string or null,
    "data": object or null,
    "occurredAt": 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`)

## Cancel a scheduled or deferred email

POST `/v1/emails/{id}/cancel`

System email (security alerts, sign-in and invitation links) cannot be canceled with an API key: 403 `system_email`.

**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,
  "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
  "warnings": [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`)

## Send a copy of an email again (new id, same content)

POST `/v1/emails/{id}/resend`

A fresh send: new Message-ID, tracking and unsubscribe links; not attributed to a campaign; sandboxed for test keys and sandbox workspaces. 409 `body_unavailable` when the content is no longer stored (older than `ONESEND_RETENTION_DAYS`).

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

### Parameters

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

### Responses

`202` Success

```
{
  "id": string,
  "status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
  "warnings": [string]
}
```

**Errors: 400, 401, 402, 403, 404, 409, 422, 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`. Sending: an API key past its expiry (`key_expired`).
- `402` Payment required (type `payment_required`), for live email only (test keys and Sandbox mode are never refused): `license_required`, a self-hosted server without an active license key (`details.buyUrl`); on the cloud, only when cloud plans are enabled (they are off by default), `plan_required` (the workspace has no plan), `email_limit` (the month's emails are used, counted per recipient; `details.resetsAt`) and `domain_limit` (the plan sends from its own domains only), with `details.upgradeUrl` where to change the plan.
- `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`. Sending: a recipient outside the key's recipient allowlist (`recipient_not_allowed`), a key used from an address it does not allow (`ip_not_allowed`), a sender domain the key may not use (`domain_not_allowed`), a session that needs two-factor authentication (`two_factor_required`) or a role that cannot send (`insufficient_role`).
- `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`)
- `422` Unprocessable (type `invalid_request`): `no_provider_for_domain`, no sending provider of the routing path may or can send for the From domain; `details.candidates` says why each provider was left out. Live email only.
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`) Sending: the key's hourly or daily send limit (`key_rate_limited`); retry after `Retry-After` seconds.
- `500` Unexpected server error (`internal`)
