Docs / Sending and domains
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.
// 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: 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) |
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. Group unsubscribes map to "scope":"broadcast".
Then follow the general cutover checklist.