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.
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
| Name | In | Type | Description |
|---|---|---|---|
idempotency-key | header | string | |
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
| Field | Type | Description |
|---|---|---|
fromrequired | string | |
torequired | string or array of string | |
subjectrequired | 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 | array of object | |
attachments[].filename | string | |
attachments[].content | string | |
attachments[].path | string | |
attachments[].content_type | string | |
tags | array of object | |
tags[].namerequired | string | |
tags[].valuerequired | string | |
scheduled_at | string | |
template | object | |
template.idrequired | string | |
template.variables | object |
Responses
{
"id": string
}Errors: 401, 403, 404, 409, 422, 429
401No API key (missing_api_key)403Invalid or expired API key (validation_error; OneSendkey_expired), a key without send permission, a key used from an address it does not allow (OneSendip_not_allowed), a recipient outside the key's allowlist (recipient_not_allowed), or a session that needs two-factor authentication (allrestricted_api_key); a sender domain the key may not use (validation_error)404Template not found (not_found)409Idempotency-Key reused with a different body (invalid_idempotent_request)422Invalid or missing fields (validation_error,missing_required_field), and, asvalidation_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.429The key's hourly or daily send limit (rate_limit_exceeded; OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
idempotency-key | header | string | |
x-batch-validation | header | "strict" | "permissive" | |
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
[{
"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
{
"data": [{
"id": string
}],
"errors": [{
"index": number,
"message": string
}]
}Errors: 401, 403, 404, 409, 422, 429
401No API key (missing_api_key)403Invalid or expired API key (validation_error; OneSendkey_expired), a key without send permission, a key used from an address it does not allow (OneSendip_not_allowed), a recipient outside the key's allowlist (recipient_not_allowed), or a session that needs two-factor authentication (allrestricted_api_key); a sender domain the key may not use (validation_error)404Template not found (not_found)409Idempotency-Key reused with a different body (invalid_idempotent_request)422Invalid or missing fields (validation_error,missing_required_field), and, asvalidation_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.429The key's hourly or daily send limit (rate_limit_exceeded; OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
idempotency-key | header | string | |
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
| Field | Type | Description |
|---|---|---|
personalizationsrequired | array of object | At most 1000 items. |
personalizations[].torequired | array of object | |
personalizations[].to[].emailrequired | string | |
personalizations[].to[].name | string | |
personalizations[].cc | array of object | |
personalizations[].cc[].emailrequired | string | |
personalizations[].cc[].name | string | |
personalizations[].bcc | array of object | |
personalizations[].bcc[].emailrequired | string | |
personalizations[].bcc[].name | string | |
personalizations[].subject | string | |
personalizations[].headers | map of string | |
personalizations[].substitutions | map of string | |
personalizations[].dynamic_template_data | object | |
personalizations[].custom_args | map of string | |
personalizations[].send_at | number | |
fromrequired | object | |
from.emailrequired | string | |
from.name | string | |
reply_to | object | |
reply_to.emailrequired | string | |
reply_to.name | string | |
reply_to_list | array of object | |
reply_to_list[].emailrequired | string | |
reply_to_list[].name | string | |
subject | string | |
content | array of object | |
content[].typerequired | string | |
content[].valuerequired | string | |
attachments | array of object | |
attachments[].contentrequired | string | |
attachments[].filenamerequired | string | |
attachments[].type | string | |
attachments[].disposition | string | |
template_id | string | |
headers | map of string | |
categories | array of string | At most 10 items. |
custom_args | map of string | |
send_at | number |
Responses
Errors: 400, 401, 403, 429
400Invalid 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.401Missing, invalid or expired API key (OneSendkey_expired)403The 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 authentication429The key's hourly or daily send limit (OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
| Field | Type | Description |
|---|---|---|
Fromrequired | string | |
Torequired | string | |
Cc | string | |
Bcc | string | |
Subject | string | |
Tag | string | |
HtmlBody | string | |
TextBody | string | |
ReplyTo | string | |
Headers | array of object | |
Headers[].Namerequired | string | |
Headers[].Valuerequired | string | |
TrackOpens | boolean | |
TrackLinks | "None" | "HtmlAndText" | "HtmlOnly" | "TextOnly" | |
Metadata | map of string | |
Attachments | array of object | |
Attachments[].Namerequired | string | |
Attachments[].Contentrequired | string | |
Attachments[].ContentType | string | |
MessageStream | string |
Responses
{
"To": string,
"SubmittedAt": string,
"MessageID": string,
"ErrorCode": number,
"Message": string
}Errors: 401, 422, 429
401Missing, invalid or expired X-Postmark-Server-Token (ErrorCode10; OneSendkey_expired)422Invalid message (ErrorCode300), 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 withErrorCode300: 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)429The key's hourly or daily send limit (OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
| Field | Type | Description |
|---|---|---|
Fromrequired | string | |
Torequired | string | |
Cc | string | |
Bcc | string | |
Subject | string | |
Tag | string | |
HtmlBody | string | |
TextBody | string | |
ReplyTo | string | |
Headers | array of object | |
Headers[].Namerequired | string | |
Headers[].Valuerequired | string | |
TrackOpens | boolean | |
TrackLinks | "None" | "HtmlAndText" | "HtmlOnly" | "TextOnly" | |
Metadata | map of string | |
Attachments | array of object | |
Attachments[].Namerequired | string | |
Attachments[].Contentrequired | string | |
Attachments[].ContentType | string | |
MessageStream | string | |
TemplateId | number or string | |
TemplateAlias | string | |
TemplateModel | object |
Responses
{
"To": string,
"SubmittedAt": string,
"MessageID": string,
"ErrorCode": number,
"Message": string
}Errors: 401, 422, 429
401Missing, invalid or expired X-Postmark-Server-Token (ErrorCode10; OneSendkey_expired)422Invalid message (ErrorCode300), 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 withErrorCode300: 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)429The key's hourly or daily send limit (OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
[{
"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
[{
"To": string,
"SubmittedAt": string,
"MessageID": string,
"ErrorCode": number,
"Message": string
}]Errors: 401, 422, 429
401Missing, invalid or expired X-Postmark-Server-Token (ErrorCode10; OneSendkey_expired)422Invalid message (ErrorCode300), 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 withErrorCode300: 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)429The key's hourly or daily send limit (OneSendkey_rate_limited), withRetry-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
| Name | In | Type | Description |
|---|---|---|---|
x-onesend-type | header | "transactional" | "broadcast" | Send as marketing email (broadcast): adds List-Unsubscribe headers and uses only providers allowed for campaigns. |
Request body
| Field | Type | Description |
|---|---|---|
Messagesrequired | array of object | At most 500 items. |
Messages[].Fromrequired | string | |
Messages[].Torequired | string | |
Messages[].Cc | string | |
Messages[].Bcc | string | |
Messages[].Subject | string | |
Messages[].Tag | string | |
Messages[].HtmlBody | string | |
Messages[].TextBody | string | |
Messages[].ReplyTo | string | |
Messages[].Headers | array of object | |
Messages[].Headers[].Namerequired | string | |
Messages[].Headers[].Valuerequired | string | |
Messages[].TrackOpens | boolean | |
Messages[].TrackLinks | "None" | "HtmlAndText" | "HtmlOnly" | "TextOnly" | |
Messages[].Metadata | map of string | |
Messages[].Attachments | array of object | |
Messages[].Attachments[].Namerequired | string | |
Messages[].Attachments[].Contentrequired | string | |
Messages[].Attachments[].ContentType | string | |
Messages[].MessageStream | string | |
Messages[].TemplateId | number or string | |
Messages[].TemplateAlias | string | |
Messages[].TemplateModel | object |
Responses
[{
"To": string,
"SubmittedAt": string,
"MessageID": string,
"ErrorCode": number,
"Message": string
}]Errors: 401, 422, 429
401Missing, invalid or expired X-Postmark-Server-Token (ErrorCode10; OneSendkey_expired)422Invalid message (ErrorCode300), 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 withErrorCode300: 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)429The key's hourly or daily send limit (OneSendkey_rate_limited), withRetry-After