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

SendGridOneSendNotes
personalizations[]one email eachto, 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, replyToFormatted as Name <email>.
subjectsubject
content[] text/plain, text/htmltext, htmlOther content types are ignored.
substitutionsreplaced in subject and contentLiteral replacement, as SendGrid does for legacy substitutions.
template_id + dynamic_template_datatemplate + variablestemplate_id is a OneSend template id or slug. OneSend templates use {{variable}} syntax, close to Handlebars; check conditionals and loops after moving a template.
categoriestagsAt most 10.
custom_argsmetadataTop-level and per-personalization values are merged. Returned in OneSend webhooks.
send_at (UNIX seconds)scheduledAtNot limited to 72 hours.
attachments[] content, filename, typeattachments[]
tracking_settings.open_tracking.enable, click_tracking.enabletracking.opens, tracking.clicks
mail_settings.sandbox_mode.enablevalidate onlyReturns 200 and sends nothing.
Idempotency-Key header (OneSend addition)idempotencyItem 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

SendGridOneSend
sgMail.send(msg)onesend.emails.send(...) or POST /v1/emails
sgMail.send([...]) / several personalizationsPOST /v1/emails/batch with up to 100 emails
Dynamic templatesOneSend templates (block editor or HTML) with template and variables
Categoriestags
Event WebhookOneSend 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.