Migrate from SendGrid to turboSMTP: SMTP and API Guide

To migrate from SendGrid, update your SMTP settings or convert v3 Mail Send requests to turboSMTP’s JSON format. This guide also covers DNS, suppressions, and webhooks. Global and EU sending hosts are available; review processing terms for your regional requirements.

SendGrid settings checked on 27 October 2026 against Twilio’s SMTP guide and Mail Send reference. SendGrid also has regional EU hosts; use your existing region when reviewing these examples.

Before you start

Create a turboSMTP account

Authenticate your sending domain

Merge turboSMTP’s SPF include into your existing single SPF record and add its DKIM record. Keep SendGrid authorized until migration and queued delivery are complete. See SPF, DKIM, and DMARC.

Export your suppressions

Export bounces, unsubscribes, and spam reports from SendGrid and use POST /suppressions/import to add them to turboSMTP. Preserve subscription-group preferences in your application when an account-wide suppression would be too broad. See the Suppressions API.

Option 1: Switch SMTP credentials

If your application, CMS, or framework sends through smtp.sendgrid.net, replace these settings:

Setting	SendGrid	turboSMTP
Host	`smtp.sendgrid.net`	`pro.turbo-smtp.com` (EU: `pro.eu.turbo-smtp.com`)
Port and encryption	587 with STARTTLS	587 or 2525 with STARTTLS; 465 or 25025 with implicit TLS; 25 also available
Username	`apikey`	Your turboSMTP Consumer Key
Password	Your SendGrid API key	Your turboSMTP Consumer Secret

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=YOUR_SENDGRID_API_KEY

SMTP_HOST=pro.eu.turbo-smtp.com
SMTP_PORT=587
SMTP_USER=YOUR_CONSUMER_KEY
SMTP_PASS=YOUR_CONSUMER_SECRET

SMTP_HOST=smtp.sendgrid.net
SMTP_HOST=pro.eu.turbo-smtp.com
SMTP_PORT=587
SMTP_USER=apikey
SMTP_USER=YOUR_CONSUMER_KEY
SMTP_PASS=YOUR_SENDGRID_API_KEY
SMTP_PASS=YOUR_CONSUMER_SECRET

Require STARTTLS for these port 587 examples. Global and EU support the same ports and TLS modes. Enable SMTP Sending on your key and check any IP restrictions. See SMTP Setup.

Option 2: Convert API calls

Replace https://api.sendgrid.com/v3/mail/send with https://api.turbo-smtp.com/api/v2/mail/send (EU: https://api.eu.turbo-smtp.com/api/v2/mail/send) and send your credentials as headers instead of a Bearer token. 1. Change the endpoint and authentication headers:

curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data @payload.json

curl --request POST \
  --url https://api.eu.turbo-smtp.com/api/v2/mail/send \
  --header 'consumerKey: YOUR_CONSUMER_KEY' \
  --header 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --header 'Content-Type: application/json' \
  --data @payload.json

curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \ # [!code --]
  --url https://api.eu.turbo-smtp.com/api/v2/mail/send \ # [!code ++]
  --header 'Authorization: Bearer YOUR_API_KEY' \ # [!code --]
  --header 'consumerKey: YOUR_CONSUMER_KEY' \ # [!code ++]
  --header 'consumerSecret: YOUR_CONSUMER_SECRET' \ # [!code ++]
  --header 'Content-Type: application/json' \
  --data @payload.json

2. Flatten the payload: This example maps one personalization. For separate messages, per-recipient subjects, templates, or substitutions, render and send each intended message separately. Flattening several personalizations into one recipient list can expose recipients or change the message they receive.

{
  "personalizations": [{
    "to": [{ "email": "recipient@example.com" }],
    "cc": [{ "email": "team@example.com" }]
  }],
  "from": { "email": "you@yourdomain.com" },
  "subject": "Your order has shipped",
  "content": [
    { "type": "text/plain", "value": "Your order is on its way." },
    { "type": "text/html", "value": "<p>Your order is on its way.</p>" }
  ]
}

{
  "from": "you@yourdomain.com",
  "to": "recipient@example.com",
  "cc": "team@example.com",
  "subject": "Your order has shipped",
  "content": "Your order is on its way.",
  "html_content": "<p>Your order is on its way.</p>"
}

{
  "personalizations": [{ 
    "to": [{ "email": "recipient@example.com" }],
    "cc": [{ "email": "team@example.com" }]
  }],
  "from": { "email": "you@yourdomain.com" },
  "from": "you@yourdomain.com", 
  "to": "recipient@example.com",
  "cc": "team@example.com",
  "subject": "Your order has shipped",
  "content": [ 
    { "type": "text/plain", "value": "Your order is on its way." },
    { "type": "text/html", "value": "<p>Your order is on its way.</p>" }
  ]
  "content": "Your order is on its way.", 
  "html_content": "<p>Your order is on its way.</p>"
}

/mail/send authenticates only with consumerKey and consumerSecret. It ignores Authorization, so a request carrying only that header is refused. Enable HTTP API Sending on your key.

Field mapping

SendGrid v3	turboSMTP	Notes
`personalizations[].to[].email`	`to`	Comma-separated string of addresses
`personalizations[].cc` / `bcc`	`cc` / `bcc`	Comma-separated strings
`from.email` and `from.name`	`from`	Address, optionally `Name <address>`
`subject`	`subject`	Unchanged
`content[]` with `text/plain`	`content`	Plain text body
`content[]` with `text/html`	`html_content`	HTML body
`attachments[]` (`content`, `filename`, `type`)	`attachments[]` (`content`, `name`, `type`)	Base64 content; the whole email must be less than 24 MB. See Attachments
`attachments[]` with `disposition: inline` and `content_id`	`attachments[]` with `content_id`	Use a bare `content_id` such as `logo`; reference it in HTML as `cid:logo@<sender-domain>`. See inline images
`headers`	`custom_headers`	Object of header names and values
`reply_to` / `reply_to_list`	`custom_headers: {"Reply-To": "..."}`	Only the first Reply-To address is kept
`custom_args`	No direct equivalent for a metadata map	Store metadata in your application; use a UUID `reference_id` for correlation

A successful request returns {"message":"OK","mid":...}. This acknowledges acceptance, not delivery. Store mid or your UUID reference_id to match later events. mid exceeds JavaScript’s safe-integer range; parse it losslessly, for example as a string or BigInt. Base64 adds roughly one third to attachment data before MIME overhead; 24 MB is not a raw-file allowance.

Replace the Event Webhook

Configure a turboSMTP webhook callback and map SendGrid event names to turboSMTP’s delivery events (PROCESSED, DROPPED, DELIVERED, DEFERRED, BOUNCED) and engagement events (OPENED, CLICKED, UNSUBSCRIBED, REPORT). turboSMTP requests are unsigned. Replace SendGrid signature verification with endpoint protection appropriate for turboSMTP, such as HTTP Basic authentication. Check enabled events and plan availability under Settings → Notifications → Webhooks → Edit. Free and Basic include a 30-day webhook demo; settings changes can take up to one hour. Symfony users can check the upcoming Mailer bridge.

Cut over safely

Send a test

Send to an internal address and confirm it arrives with SPF and DKIM passing.

Ramp up gradually

Route a small share of traffic to turboSMTP and compare delivery in the statistics dashboard.

Switch fully and clean up DNS

Move all traffic and sync new opt-outs. After SendGrid’s queue has drained, remove only the DNS records and SPF mechanisms no longer needed by another service.

Frequently asked questions

How long does a SendGrid to turboSMTP migration take?

It depends on your DNS access, application features, templates, suppression data, and webhook consumers. Test each sending flow before moving production traffic.

Do I need to remove SendGrid's DNS records first?

No. Keep both providers authorized within one SPF record and retain their DKIM records until cutover and queued delivery are complete.

Can turboSMTP help with my migration?

Contact support to discuss your migration. Available support channels depend on your plan.

Comparisons

Migration Guides

Migrate from SendGrid to turboSMTP: SMTP and API Guide

Before you start

Option 1: Switch SMTP credentials

Option 2: Convert API calls

Field mapping

Replace the Event Webhook

Cut over safely

Frequently asked questions

​Before you start

​Option 1: Switch SMTP credentials

​Option 2: Convert API calls

​Field mapping

​Replace the Event Webhook

​Cut over safely

​Frequently asked questions

Before you start

Option 1: Switch SMTP credentials

Option 2: Convert API calls

Field mapping

Replace the Event Webhook

Cut over safely

Frequently asked questions