> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from SendGrid to turboSMTP: SMTP and API Guide

> Step-by-step guide to move from SendGrid to turboSMTP: swap SMTP credentials, convert v3 Mail Send payloads, set up DNS and webhooks, and cut over safely.

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.

> [!NOTE]
>
> SendGrid settings checked on 27 October 2026 against Twilio's [SMTP guide](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/integrating-with-the-smtp-api) and [Mail Send reference](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send). SendGrid also has regional EU hosts; use your existing region when reviewing these examples.

## Before you start

**1. Create a turboSMTP account**

[Sign up for free](https://serversmtp.com/en/signup) and create a Consumer Key and Consumer Secret. See [API Keys](/docs/get-started/api-keys.md).

**2. 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](/docs/deliverability/spf-dkim-dmarc.md).

**3. 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](/docs/api-reference/suppressions.md).

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

```bash SendGrid theme={"system"}
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=YOUR_SENDGRID_API_KEY
```

```bash turboSMTP theme={"system"}
SMTP_HOST=pro.eu.turbo-smtp.com
SMTP_PORT=587
SMTP_USER=YOUR_CONSUMER_KEY
SMTP_PASS=YOUR_CONSUMER_SECRET
```

```bash Diff nocopy theme={"system"}
SMTP_HOST=smtp.sendgrid.net # [!code --]
SMTP_HOST=pro.eu.turbo-smtp.com # [!code ++]
SMTP_PORT=587
SMTP_USER=apikey # [!code --]
SMTP_USER=YOUR_CONSUMER_KEY # [!code ++]
SMTP_PASS=YOUR_SENDGRID_API_KEY # [!code --]
SMTP_PASS=YOUR_CONSUMER_SECRET # [!code ++]
```

> [!NOTE]
>
> 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](/docs/get-started/smtp-configuration.md).

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

```bash SendGrid theme={"system"}
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
```

```bash turboSMTP theme={"system"}
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
```

```bash Diff nocopy theme={"system"}
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.

```json SendGrid theme={"system"}
{
  "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>" }
  ]
}
```

```json turboSMTP theme={"system"}
{
  "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>"
}
```

```json Diff nocopy theme={"system"}
{
  "personalizations": [{ // [!code --:5]
    "to": [{ "email": "recipient@example.com" }],
    "cc": [{ "email": "team@example.com" }]
  }],
  "from": { "email": "you@yourdomain.com" },
  "from": "you@yourdomain.com", // [!code ++:3]
  "to": "recipient@example.com",
  "cc": "team@example.com",
  "subject": "Your order has shipped",
  "content": [ // [!code --:4]
    { "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.", // [!code ++:2]
  "html_content": "<p>Your order is on its way.</p>"
}
```

> [!WARNING]
>
> `/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](/docs/sending/attachments.md) |
| `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](/docs/sending/attachments.md#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](/docs/analytics/webhooks.md) 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](/docs/integrations/symfony-mailer.md).

## Cut over safely

**1. Send a test**

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

**2. Ramp up gradually**

Route a small share of traffic to turboSMTP and compare delivery in the [statistics dashboard](/docs/analytics/statistics-dashboard.md).

**3. 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

> [accordion] 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.

> [accordion] 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.

> [accordion] Can turboSMTP help with my migration?
>
> [Contact support](https://serversmtp.com/contact-us/) to discuss your migration. Available support channels depend on your plan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.