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 and errors are described in the overview.

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

NameInTypeDescription
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
statusquerystring
providerquerystring
tagquerystring
qquerystring
fromquerystring (date-time)
untilquerystring (date-time)
reroutedquery"true" | "false"
sourcequerystring
typequery"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

NameInTypeDescription
idempotency-keyheaderstring

Request body

application/json, required.

FieldTypeDescription
fromrequiredstringSender: a@b.com or Name <a@b.com>. The domain should be added under Domains so providers accept it.
torequiredstring or array of stringOne address or a list (at most 50). Each is a@b.com or Name <a@b.com>.
ccstring or array of stringCarbon copy: one address or a list.
bccstring or array of stringBlind carbon copy: one address or a list.
replyTostring or array of stringReply-To address or addresses.
subjectstringSubject line. Optional with template (the template subject is used). {{variables}} are filled in like the body.
htmlstringHTML body (at most 5 MB). {{variables}} and system variables such as {{unsubscribe_url}} are filled in.
textstringPlain-text body (at most 2 MB).
templatestringTemplate id or slug. Renders the published version (or the latest) with variables.
variablesobjectValues for {{variables}} in the subject, html and template. Missing ones render empty and are listed in warnings.
headersmap of stringExtra headers. Reserved names (To, Cc, Bcc, From, Subject, Reply-To, …) are refused.
attachmentsarray of objectUp to 20 files, each with content (base64) or a public url. At most 20 items.
attachments[].filenamerequiredstringFile name shown to the recipient.
attachments[].contentstringBase64 content (at most 10 MB).
attachments[].urlstring (uri)Public http(s) URL to fetch instead of content.
attachments[].contentTypestringMIME type, for example application/pdf.
tagsarray of stringLabels for filtering logs and statistics, and for routing rules. At most 20 items.
metadatamap of stringYour 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".
policystringRouting policy id or name. Defaults to the workspace default policy.
providerstringForce one sending provider (connection id). Skips routing order and failover.
scheduledAtstring (date-time)Send later: an ISO 8601 time with an offset, for example 2030-01-01T09:00:00+01:00.
trackingobjectOpen and click tracking for this email. Wins over the sending domain's tracking settings, which win over the workspace defaults.
tracking.opensboolean
tracking.clicksboolean

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

NameInTypeDescription
idempotency-keyheaderstring

Request body

application/json, required.

FieldTypeDescription
emailsrequiredarray of objectAt most 100 items.
emails[].fromrequiredstringSender: a@b.com or Name <a@b.com>. The domain should be added under Domains so providers accept it.
emails[].torequiredstring or array of stringOne address or a list (at most 50). Each is a@b.com or Name <a@b.com>.
emails[].ccstring or array of stringCarbon copy: one address or a list.
emails[].bccstring or array of stringBlind carbon copy: one address or a list.
emails[].replyTostring or array of stringReply-To address or addresses.
emails[].subjectstringSubject line. Optional with template (the template subject is used). {{variables}} are filled in like the body.
emails[].htmlstringHTML body (at most 5 MB). {{variables}} and system variables such as {{unsubscribe_url}} are filled in.
emails[].textstringPlain-text body (at most 2 MB).
emails[].templatestringTemplate id or slug. Renders the published version (or the latest) with variables.
emails[].variablesobjectValues for {{variables}} in the subject, html and template. Missing ones render empty and are listed in warnings.
emails[].headersmap of stringExtra headers. Reserved names (To, Cc, Bcc, From, Subject, Reply-To, …) are refused.
emails[].attachmentsarray of objectUp to 20 files, each with content (base64) or a public url. At most 20 items.
emails[].attachments[].filenamerequiredstringFile name shown to the recipient.
emails[].attachments[].contentstringBase64 content (at most 10 MB).
emails[].attachments[].urlstring (uri)Public http(s) URL to fetch instead of content.
emails[].attachments[].contentTypestringMIME type, for example application/pdf.
emails[].tagsarray of stringLabels for filtering logs and statistics, and for routing rules. At most 20 items.
emails[].metadatamap of stringYour 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[].policystringRouting policy id or name. Defaults to the workspace default policy.
emails[].providerstringForce one sending provider (connection id). Skips routing order and failover.
emails[].scheduledAtstring (date-time)Send later: an ISO 8601 time with an offset, for example 2030-01-01T09:00:00+01:00.
emails[].trackingobjectOpen and click tracking for this email. Wins over the sending domain's tracking settings, which win over the workspace defaults.
emails[].tracking.opensboolean
emails[].tracking.clicksboolean

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

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)