Docs / API reference

Compatibility

Send endpoints that accept the Resend, SendGrid and Postmark payloads, for moving an app to OneSend without code changes. Outside /v1; authenticate with a OneSend API key the way that provider's SDK passes its key.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

Send an email (Resend-compatible)

POST /compat/resend/emails

Accepts the Resend POST /emails payload. Point a Resend SDK at <your server>/compat/resend and use a OneSend API key as the key. The email goes through your routing policy like POST /v1/emails. Tags become OneSend tags name:value; template.id is a OneSend template id or slug. Not supported: react (render it before sending), topic_id, attachment content_id (inline images). text is not generated from html.

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

Parameters

NameInTypeDescription
idempotency-keyheaderstring
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

FieldTypeDescription
fromrequiredstring
torequiredstring or array of string
subjectrequiredstring
ccstring or array of string
bccstring or array of string
reply_tostring or array of string
htmlstring
textstring
headersmap of string
attachmentsarray of object
attachments[].filenamestring
attachments[].contentstring
attachments[].pathstring
attachments[].content_typestring
tagsarray of object
tags[].namerequiredstring
tags[].valuerequiredstring
scheduled_atstring
templateobject
template.idrequiredstring
template.variablesobject

Responses

200 Queued

{
  "id": string
}
Errors: 401, 403, 404, 409, 422, 429
  • 401 No API key (missing_api_key)
  • 403 Invalid or expired API key (validation_error; OneSend key_expired), a key without send permission, a key used from an address it does not allow (OneSend ip_not_allowed), a recipient outside the key's allowlist (recipient_not_allowed), or a session that needs two-factor authentication (all restricted_api_key); a sender domain the key may not use (validation_error)
  • 404 Template not found (not_found)
  • 409 Idempotency-Key reused with a different body (invalid_idempotent_request)
  • 422 Invalid or missing fields (validation_error, missing_required_field), and, as validation_error: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain). A batch is refused whole: nothing is queued.
  • 429 The key's hourly or daily send limit (rate_limit_exceeded; OneSend key_rate_limited), with Retry-After

Send up to 100 emails (Resend-compatible)

POST /compat/resend/emails/batch

Accepts the Resend POST /emails/batch payload: a JSON array of emails. By default one invalid email rejects the batch; with x-batch-validation: permissive valid emails are sent and the rest listed in errors. With Idempotency-Key, item i uses <key>:<i>.

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

Parameters

NameInTypeDescription
idempotency-keyheaderstring
x-batch-validationheader"strict" | "permissive"
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

[{
  "from": string,
  "to": string or array of string,
  "subject": string,
  "cc": string or array of string,
  "bcc": string or array of string,
  "reply_to": string or array of string,
  "html": string,
  "text": string,
  "headers": map of string,
  "attachments": [{
    "filename": string,
    "content": string,
    "path": string,
    "content_type": string
  }],
  "tags": [{
    "name": string,
    "value": string
  }],
  "scheduled_at": string,
  "template": {
    "id": string,
    "variables": object
  }
}]

Responses

200 Queued

{
  "data": [{
    "id": string
  }],
  "errors": [{
    "index": number,
    "message": string
  }]
}
Errors: 401, 403, 404, 409, 422, 429
  • 401 No API key (missing_api_key)
  • 403 Invalid or expired API key (validation_error; OneSend key_expired), a key without send permission, a key used from an address it does not allow (OneSend ip_not_allowed), a recipient outside the key's allowlist (recipient_not_allowed), or a session that needs two-factor authentication (all restricted_api_key); a sender domain the key may not use (validation_error)
  • 404 Template not found (not_found)
  • 409 Idempotency-Key reused with a different body (invalid_idempotent_request)
  • 422 Invalid or missing fields (validation_error, missing_required_field), and, as validation_error: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain). A batch is refused whole: nothing is queued.
  • 429 The key's hourly or daily send limit (rate_limit_exceeded; OneSend key_rate_limited), with Retry-After

Send email (SendGrid v3-compatible)

POST /compat/sendgrid/v3/mail/send

Accepts the SendGrid v3 POST /v3/mail/send payload. Point a SendGrid client at <your server>/compat/sendgrid and use a OneSend API key as the key. Each personalization becomes one OneSend email. Mapping: categories → tags, custom_args → metadata, send_at → scheduled send, substitutions are replaced in subject and content, template_id is a OneSend template id or slug with dynamic_template_data as its variables, tracking_settings.open_tracking/click_tracking → tracking. mail_settings.sandbox_mode.enable validates without sending (200). Ignored: asm, batch_id, ip_pool_name, other mail and tracking settings, inline attachments (content_id). Returns 202 with X-Message-Id (the first email) and X-OneSend-Message-Ids (all of them).

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

Parameters

NameInTypeDescription
idempotency-keyheaderstring
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

FieldTypeDescription
personalizationsrequiredarray of objectAt most 1000 items.
personalizations[].torequiredarray of object
personalizations[].to[].emailrequiredstring
personalizations[].to[].namestring
personalizations[].ccarray of object
personalizations[].cc[].emailrequiredstring
personalizations[].cc[].namestring
personalizations[].bccarray of object
personalizations[].bcc[].emailrequiredstring
personalizations[].bcc[].namestring
personalizations[].subjectstring
personalizations[].headersmap of string
personalizations[].substitutionsmap of string
personalizations[].dynamic_template_dataobject
personalizations[].custom_argsmap of string
personalizations[].send_atnumber
fromrequiredobject
from.emailrequiredstring
from.namestring
reply_toobject
reply_to.emailrequiredstring
reply_to.namestring
reply_to_listarray of object
reply_to_list[].emailrequiredstring
reply_to_list[].namestring
subjectstring
contentarray of object
content[].typerequiredstring
content[].valuerequiredstring
attachmentsarray of object
attachments[].contentrequiredstring
attachments[].filenamerequiredstring
attachments[].typestring
attachments[].dispositionstring
template_idstring
headersmap of string
categoriesarray of stringAt most 10 items.
custom_argsmap of string
send_atnumber

Responses

200 Sandbox mode: valid, nothing sent

202 Queued

Errors: 400, 401, 403, 429
  • 400 Invalid payload, or no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain). Nothing is queued for any personalization.
  • 401 Missing, invalid or expired API key (OneSend key_expired)
  • 403 The key may not send, may not send from this domain or to this recipient (recipient_not_allowed), is used from an address it does not allow (ip_not_allowed), or a session needs two-factor authentication
  • 429 The key's hourly or daily send limit (OneSend key_rate_limited), with Retry-After

Send an email (Postmark-compatible)

POST /compat/postmark/email

Accepts the Postmark POST /email payload. Point a Postmark client at <your server>/compat/postmark and use a OneSend API key as the server token. Tag → tag, Metadata → metadata, TrackOpens/TrackLinks → tracking (TextOnly link tracking is treated as on), a MessageStream whose name contains "broadcast" sends as marketing email. Ignored: InlineCss, attachment ContentID (inline images).

Authentication: an API key in the X-Postmark-Server-Token header.

Parameters

NameInTypeDescription
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

FieldTypeDescription
Fromrequiredstring
Torequiredstring
Ccstring
Bccstring
Subjectstring
Tagstring
HtmlBodystring
TextBodystring
ReplyTostring
Headersarray of object
Headers[].Namerequiredstring
Headers[].Valuerequiredstring
TrackOpensboolean
TrackLinks"None" | "HtmlAndText" | "HtmlOnly" | "TextOnly"
Metadatamap of string
Attachmentsarray of object
Attachments[].Namerequiredstring
Attachments[].Contentrequiredstring
Attachments[].ContentTypestring
MessageStreamstring

Responses

200 Accepted

{
  "To": string,
  "SubmittedAt": string,
  "MessageID": string,
  "ErrorCode": number,
  "Message": string
}
Errors: 401, 422, 429
  • 401 Missing, invalid or expired X-Postmark-Server-Token (ErrorCode 10; OneSend key_expired)
  • 422 Invalid message (ErrorCode 300), sender domain not allowed for this key (400), invalid JSON (402), key may not send, recipient not allowed, address not allowed or two-factor authentication needed (405), template not found (1101); and with ErrorCode 300: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain)
  • 429 The key's hourly or daily send limit (OneSend key_rate_limited), with Retry-After

Send with a template (Postmark-compatible)

POST /compat/postmark/email/withTemplate

Accepts the Postmark POST /email/withTemplate payload. TemplateId or TemplateAlias is a OneSend template id or slug; TemplateModel holds its variables. Point a Postmark client at <your server>/compat/postmark and use a OneSend API key as the server token. Tag → tag, Metadata → metadata, TrackOpens/TrackLinks → tracking (TextOnly link tracking is treated as on), a MessageStream whose name contains "broadcast" sends as marketing email. Ignored: InlineCss, attachment ContentID (inline images).

Authentication: an API key in the X-Postmark-Server-Token header.

Parameters

NameInTypeDescription
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

FieldTypeDescription
Fromrequiredstring
Torequiredstring
Ccstring
Bccstring
Subjectstring
Tagstring
HtmlBodystring
TextBodystring
ReplyTostring
Headersarray of object
Headers[].Namerequiredstring
Headers[].Valuerequiredstring
TrackOpensboolean
TrackLinks"None" | "HtmlAndText" | "HtmlOnly" | "TextOnly"
Metadatamap of string
Attachmentsarray of object
Attachments[].Namerequiredstring
Attachments[].Contentrequiredstring
Attachments[].ContentTypestring
MessageStreamstring
TemplateIdnumber or string
TemplateAliasstring
TemplateModelobject

Responses

200 Accepted

{
  "To": string,
  "SubmittedAt": string,
  "MessageID": string,
  "ErrorCode": number,
  "Message": string
}
Errors: 401, 422, 429
  • 401 Missing, invalid or expired X-Postmark-Server-Token (ErrorCode 10; OneSend key_expired)
  • 422 Invalid message (ErrorCode 300), sender domain not allowed for this key (400), invalid JSON (402), key may not send, recipient not allowed, address not allowed or two-factor authentication needed (405), template not found (1101); and with ErrorCode 300: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain)
  • 429 The key's hourly or daily send limit (OneSend key_rate_limited), with Retry-After

Send up to 500 emails (Postmark-compatible)

POST /compat/postmark/email/batch

Accepts the Postmark POST /email/batch payload. Each message is validated and sent on its own: check ErrorCode in every result. Point a Postmark client at <your server>/compat/postmark and use a OneSend API key as the server token. Tag → tag, Metadata → metadata, TrackOpens/TrackLinks → tracking (TextOnly link tracking is treated as on), a MessageStream whose name contains "broadcast" sends as marketing email. Ignored: InlineCss, attachment ContentID (inline images).

Authentication: an API key in the X-Postmark-Server-Token header.

Parameters

NameInTypeDescription
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

[{
  "From": string,
  "To": string,
  "Cc": string,
  "Bcc": string,
  "Subject": string,
  "Tag": string,
  "HtmlBody": string,
  "TextBody": string,
  "ReplyTo": string,
  "Headers": [{
    "Name": string,
    "Value": string
  }],
  "TrackOpens": boolean,
  "TrackLinks": "None" | "HtmlAndText" | "HtmlOnly" | "TextOnly",
  "Metadata": map of string,
  "Attachments": [{
    "Name": string,
    "Content": string,
    "ContentType": string
  }],
  "MessageStream": string
}]

Responses

200 Accepted

[{
  "To": string,
  "SubmittedAt": string,
  "MessageID": string,
  "ErrorCode": number,
  "Message": string
}]
Errors: 401, 422, 429
  • 401 Missing, invalid or expired X-Postmark-Server-Token (ErrorCode 10; OneSend key_expired)
  • 422 Invalid message (ErrorCode 300), sender domain not allowed for this key (400), invalid JSON (402), key may not send, recipient not allowed, address not allowed or two-factor authentication needed (405), template not found (1101); and with ErrorCode 300: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain)
  • 429 The key's hourly or daily send limit (OneSend key_rate_limited), with Retry-After

Send up to 500 emails with templates (Postmark-compatible)

POST /compat/postmark/email/batchWithTemplates

Accepts the Postmark POST /email/batchWithTemplates payload. Point a Postmark client at <your server>/compat/postmark and use a OneSend API key as the server token. Tag → tag, Metadata → metadata, TrackOpens/TrackLinks → tracking (TextOnly link tracking is treated as on), a MessageStream whose name contains "broadcast" sends as marketing email. Ignored: InlineCss, attachment ContentID (inline images).

Authentication: an API key in the X-Postmark-Server-Token header.

Parameters

NameInTypeDescription
x-onesend-typeheader"transactional" | "broadcast"Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns.

Request body

application/json, required.

FieldTypeDescription
Messagesrequiredarray of objectAt most 500 items.
Messages[].Fromrequiredstring
Messages[].Torequiredstring
Messages[].Ccstring
Messages[].Bccstring
Messages[].Subjectstring
Messages[].Tagstring
Messages[].HtmlBodystring
Messages[].TextBodystring
Messages[].ReplyTostring
Messages[].Headersarray of object
Messages[].Headers[].Namerequiredstring
Messages[].Headers[].Valuerequiredstring
Messages[].TrackOpensboolean
Messages[].TrackLinks"None" | "HtmlAndText" | "HtmlOnly" | "TextOnly"
Messages[].Metadatamap of string
Messages[].Attachmentsarray of object
Messages[].Attachments[].Namerequiredstring
Messages[].Attachments[].Contentrequiredstring
Messages[].Attachments[].ContentTypestring
Messages[].MessageStreamstring
Messages[].TemplateIdnumber or string
Messages[].TemplateAliasstring
Messages[].TemplateModelobject

Responses

200 Accepted

[{
  "To": string,
  "SubmittedAt": string,
  "MessageID": string,
  "ErrorCode": number,
  "Message": string
}]
Errors: 401, 422, 429
  • 401 Missing, invalid or expired X-Postmark-Server-Token (ErrorCode 10; OneSend key_expired)
  • 422 Invalid message (ErrorCode 300), sender domain not allowed for this key (400), invalid JSON (402), key may not send, recipient not allowed, address not allowed or two-factor authentication needed (405), template not found (1101); and with ErrorCode 300: no plan or license for live email (plan_required, license_required), the plan's monthly emails used (email_limit), a sender domain outside the plan (domain_limit), or no sending provider that may or can send for the From domain (no_provider_for_domain)
  • 429 The key's hourly or daily send limit (OneSend key_rate_limited), with Retry-After