Emails
Send, inspect and cancel email. Each email shows the providers it was routed through.
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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
fromrequired | string | Sender: a@b.com or Name <a@b.com>. The domain should be added under Domains so providers accept it. |
torequired | 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[].filenamerequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized. Sending: an API key past its expiry (key_expired).402Payment required (typepayment_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) anddomain_limit(the plan sends from its own domains only), withdetails.upgradeUrlwhere to change the plan.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden. 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).404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)422Unprocessable (typeinvalid_request):no_provider_for_domain, no sending provider of the routing path may or can send for the From domain;details.candidatessays why each provider was left out. Live email only.429Too many requests; retry after the time in theRetry-Afterheader (rate_limited) Sending: the key's hourly or daily send limit (key_rate_limited); retry afterRetry-Afterseconds.500Unexpected 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
| Field | Type | Description |
|---|---|---|
emailsrequired | array of object | At most 100 items. |
emails[].fromrequired | string | Sender: a@b.com or Name <a@b.com>. The domain should be added under Domains so providers accept it. |
emails[].torequired | 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[].filenamerequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized. Sending: an API key past its expiry (key_expired).402Payment required (typepayment_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) anddomain_limit(the plan sends from its own domains only), withdetails.upgradeUrlwhere to change the plan.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden. 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).404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)422Unprocessable (typeinvalid_request):no_provider_for_domain, no sending provider of the routing path may or can send for the From domain;details.candidatessays why each provider was left out. Live email only.429Too many requests; retry after the time in theRetry-Afterheader (rate_limited) Sending: the key's hourly or daily send limit (key_rate_limited); retry afterRetry-Afterseconds.500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"status": "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | "deferred" | …,
"warnings": [string]
}Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized. Sending: an API key past its expiry (key_expired).402Payment required (typepayment_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) anddomain_limit(the plan sends from its own domains only), withdetails.upgradeUrlwhere to change the plan.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden. 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).404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)422Unprocessable (typeinvalid_request):no_provider_for_domain, no sending provider of the routing path may or can send for the From domain;details.candidatessays why each provider was left out. Live email only.429Too many requests; retry after the time in theRetry-Afterheader (rate_limited) Sending: the key's hourly or daily send limit (key_rate_limited); retry afterRetry-Afterseconds.500Unexpected server error (internal)