---
title: "Compatibility API"
description: "Compatibility in the OneSend API: 7 endpoints. Send endpoints that accept the Resend, SendGrid and Postmark payloads, for moving an app to OneSend without code changes."
url: https://onesend.email/docs/api-reference/compatibility/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/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](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `from`required | `string` |  |
| `to`required | `string or array of string` |  |
| `subject`required | `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[].name`required | `string` |  |
| `tags[].value`required | `string` |  |
| `scheduled_at` | `string` |  |
| `template` | `object` |  |
| `template.id`required | `string` |  |
| `template.variables` | `object` |  |

### 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

| 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

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

| 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `personalizations`required | `array of object` | At most 1000 items. |
| `personalizations[].to`required | `array of object` |  |
| `personalizations[].to[].email`required | `string` |  |
| `personalizations[].to[].name` | `string` |  |
| `personalizations[].cc` | `array of object` |  |
| `personalizations[].cc[].email`required | `string` |  |
| `personalizations[].cc[].name` | `string` |  |
| `personalizations[].bcc` | `array of object` |  |
| `personalizations[].bcc[].email`required | `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` |  |
| `from`required | `object` |  |
| `from.email`required | `string` |  |
| `from.name` | `string` |  |
| `reply_to` | `object` |  |
| `reply_to.email`required | `string` |  |
| `reply_to.name` | `string` |  |
| `reply_to_list` | `array of object` |  |
| `reply_to_list[].email`required | `string` |  |
| `reply_to_list[].name` | `string` |  |
| `subject` | `string` |  |
| `content` | `array of object` |  |
| `content[].type`required | `string` |  |
| `content[].value`required | `string` |  |
| `attachments` | `array of object` |  |
| `attachments[].content`required | `string` |  |
| `attachments[].filename`required | `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

`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

| 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `From`required | `string` |  |
| `To`required | `string` |  |
| `Cc` | `string` |  |
| `Bcc` | `string` |  |
| `Subject` | `string` |  |
| `Tag` | `string` |  |
| `HtmlBody` | `string` |  |
| `TextBody` | `string` |  |
| `ReplyTo` | `string` |  |
| `Headers` | `array of object` |  |
| `Headers[].Name`required | `string` |  |
| `Headers[].Value`required | `string` |  |
| `TrackOpens` | `boolean` |  |
| `TrackLinks` | `"None" \| "HtmlAndText" \| "HtmlOnly" \| "TextOnly"` |  |
| `Metadata` | `map of string` |  |
| `Attachments` | `array of object` |  |
| `Attachments[].Name`required | `string` |  |
| `Attachments[].Content`required | `string` |  |
| `Attachments[].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 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `From`required | `string` |  |
| `To`required | `string` |  |
| `Cc` | `string` |  |
| `Bcc` | `string` |  |
| `Subject` | `string` |  |
| `Tag` | `string` |  |
| `HtmlBody` | `string` |  |
| `TextBody` | `string` |  |
| `ReplyTo` | `string` |  |
| `Headers` | `array of object` |  |
| `Headers[].Name`required | `string` |  |
| `Headers[].Value`required | `string` |  |
| `TrackOpens` | `boolean` |  |
| `TrackLinks` | `"None" \| "HtmlAndText" \| "HtmlOnly" \| "TextOnly"` |  |
| `Metadata` | `map of string` |  |
| `Attachments` | `array of object` |  |
| `Attachments[].Name`required | `string` |  |
| `Attachments[].Content`required | `string` |  |
| `Attachments[].ContentType` | `string` |  |
| `MessageStream` | `string` |  |
| `TemplateId` | `number or string` |  |
| `TemplateAlias` | `string` |  |
| `TemplateModel` | `object` |  |

### 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

| 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

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

| 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `Messages`required | `array of object` | At most 500 items. |
| `Messages[].From`required | `string` |  |
| `Messages[].To`required | `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[].Name`required | `string` |  |
| `Messages[].Headers[].Value`required | `string` |  |
| `Messages[].TrackOpens` | `boolean` |  |
| `Messages[].TrackLinks` | `"None" \| "HtmlAndText" \| "HtmlOnly" \| "TextOnly"` |  |
| `Messages[].Metadata` | `map of string` |  |
| `Messages[].Attachments` | `array of object` |  |
| `Messages[].Attachments[].Name`required | `string` |  |
| `Messages[].Attachments[].Content`required | `string` |  |
| `Messages[].Attachments[].ContentType` | `string` |  |
| `Messages[].MessageStream` | `string` |  |
| `Messages[].TemplateId` | `number or string` |  |
| `Messages[].TemplateAlias` | `string` |  |
| `Messages[].TemplateModel` | `object` |  |

### 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`
