---
title: "Migrating from SendGrid"
description: "You can keep sending through your SendGrid account: connect it under Sending providers and OneSend routes through it, with other providers behind it for failover."
url: https://onesend.email/docs/migrate/sendgrid/
---
# Migrating from SendGrid

You can keep sending through your SendGrid account: connect it under **Sending providers** and OneSend routes through it, with other providers behind it for failover.

## Option 1: the compatibility endpoint

`POST /compat/sendgrid/v3/mail/send` accepts the SendGrid v3 Mail Send payload. Authenticate with `Authorization: Bearer <OneSend API key>`, as the SendGrid libraries do. A successful request returns 202 with an empty body, like SendGrid, plus:

- `X-Message-Id`: the OneSend id of the first email.
- `X-OneSend-Message-Ids`: every email id, comma-separated (one per personalization).

Point the client at `https://<your server>/compat/sendgrid`; the library appends `/v3/mail/send`.

```js
// Node.js: @sendgrid/mail with a custom client
const client = require('@sendgrid/client');
const sgMail = require('@sendgrid/mail');
client.setApiKey(process.env.ONESEND_API_KEY);
client.setDefaultRequest('baseUrl', 'https://mail.example.com/compat/sendgrid');
sgMail.setClient(client);
await sgMail.send({ to: 'ada@example.com', from: 'hello@acme.dev', subject: 'Hello', text: 'Hi', html: '<p>Hi</p>' });
```

```python
# Python: sendgrid
from sendgrid import SendGridAPIClient
sg = SendGridAPIClient(api_key=os.environ["ONESEND_API_KEY"], host="https://mail.example.com/compat/sendgrid")
```

Check the option names against the library version you use.

### Field mapping

| SendGrid | OneSend | Notes |
|---|---|---|
| `personalizations[]` | one email each | `to`, `cc`, `bcc`, `subject`, `headers`, `custom_args`, `send_at`, `from` per personalization override the top-level values. All `to` addresses of one personalization receive one email together, as in SendGrid. At most 1,000 personalizations and 1,000 recipients in total. |
| `from`, `reply_to`, `reply_to_list` (`{ email, name }`) | `from`, `replyTo` | Formatted as `Name <email>`. |
| `subject` | `subject` | |
| `content[]` `text/plain`, `text/html` | `text`, `html` | Other content types are ignored. |
| `substitutions` | replaced in subject and content | Literal replacement, as SendGrid does for legacy substitutions. |
| `template_id` + `dynamic_template_data` | `template` + `variables` | `template_id` is a OneSend template id or slug. OneSend templates use `{{variable}}` syntax, close to Handlebars; check conditionals and loops after moving a template. |
| `categories` | `tags` | At most 10. |
| `custom_args` | `metadata` | Top-level and per-personalization values are merged. Returned in OneSend webhooks. |
| `send_at` (UNIX seconds) | `scheduledAt` | Not limited to 72 hours. |
| `attachments[]` `content`, `filename`, `type` | `attachments[]` | |
| `tracking_settings.open_tracking.enable`, `click_tracking.enable` | `tracking.opens`, `tracking.clicks` | |
| `mail_settings.sandbox_mode.enable` | validate only | Returns 200 and sends nothing. |
| `Idempotency-Key` header (OneSend addition) | idempotency | Item *i* uses `<key>:<i>` when there are several personalizations. |

Ignored (listed in `X-OneSend-Ignored-Fields`): `asm` (unsubscribe groups; send marketing with `X-OneSend-Type: broadcast` and OneSend's one-click unsubscribe), `batch_id`, `ip_pool_name`, other `mail_settings` and `tracking_settings` (subscription tracking, Google Analytics), inline attachments (`disposition: inline`, `content_id`).

Errors use SendGrid's shape: `{ "errors": [{ "message", "field", "help": null }] }` with 400 for invalid payloads, 401 for a missing or invalid key and 403 for a key that may not send.

Other SendGrid APIs (Marketing Campaigns, contacts, stats, suppressions, sender authentication) have no compat equivalent. Use `/v1/campaigns`, `/v1/contacts`, `/v1/statistics/overview`, `/v1/suppressions` and `/v1/domains`.

## Option 2: the native API

| SendGrid | OneSend |
|---|---|
| `sgMail.send(msg)` | `onesend.emails.send(...)` or `POST /v1/emails` |
| `sgMail.send([...])` / several personalizations | `POST /v1/emails/batch` with up to 100 emails |
| Dynamic templates | OneSend templates (block editor or HTML) with `template` and `variables` |
| Categories | `tags` |
| Event Webhook | OneSend webhooks ([Webhooks](https://onesend.email/docs/webhooks/)) |

## DNS

With automated security, SendGrid's records are CNAMEs (`em1234.<domain>`, `s1._domainkey`, `s2._domainkey`). Keep them: OneSend reads the SendGrid domain status through the API. Remove `include:sendgrid.net` from your root SPF if it is there only for SendGrid with automated security; it is not needed and costs lookups. Add the `_onesend-verify` TXT record and the records for any providers you add.

## Suppressions

Export bounces, blocks, spam reports, invalid emails and global unsubscribes from SendGrid (Suppressions in the SendGrid app, or its suppression API) and import them as described in the [cutover checklist](https://onesend.email/docs/migrate/#general-cutover-checklist). Group unsubscribes map to `"scope":"broadcast"`.

Then follow the [general cutover checklist](https://onesend.email/docs/migrate/#general-cutover-checklist).
