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

# Migrate from Mailgun to turboSMTP: SMTP and API Guide

> Step-by-step guide to move from Mailgun to turboSMTP: switch SMTP credentials, convert form-data API calls to JSON, migrate webhooks, and cut over safely.

Switching from Mailgun to turboSMTP comes down to two changes: new SMTP credentials, or converting Mailgun's form-data messages endpoint to turboSMTP's JSON API. This guide walks through both, along with DNS, suppressions, webhooks, and a safe cutover. Mailgun EU-region users can move straight to turboSMTP's EU hosts.

> [!NOTE]
>
> Mailgun settings checked on 27 October 2026 against its [API overview](https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview), [SMTP guide](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-smtp), and [send reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages/post-v3--domain-name--messages). Confirm current plan requirements before cutover.

## 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 Mailgun authorized until cutover and queued delivery are complete. See [SPF, DKIM, and DMARC](/docs/deliverability/spf-dkim-dmarc.md).

**3. Export your suppressions**

Export bounces, unsubscribes, and complaints from Mailgun and import them with `POST /suppressions/import`. Review domain and list-specific opt-outs before mapping them to account suppressions. See the [Suppressions API](/docs/api-reference/suppressions.md).

## Option 1: Switch SMTP credentials

| Setting | Mailgun | turboSMTP |
| - | - | - |
| Host | `smtp.mailgun.org` (EU: `smtp.eu.mailgun.org`) | `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 | Your per-domain SMTP user | Your turboSMTP Consumer Key |
| Password | Your per-domain SMTP password | Your turboSMTP Consumer Secret |

```bash Mailgun theme={"system"}
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@YOUR_DOMAIN_NAME
SMTP_PASS=YOUR_MAILGUN_SMTP_PASSWORD
```

```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.mailgun.org # [!code --]
SMTP_HOST=pro.eu.turbo-smtp.com # [!code ++]
SMTP_PORT=587
SMTP_USER=postmaster@YOUR_DOMAIN_NAME # [!code --]
SMTP_USER=YOUR_CONSUMER_KEY # [!code ++]
SMTP_PASS=YOUR_MAILGUN_SMTP_PASSWORD # [!code --]
SMTP_PASS=YOUR_CONSUMER_SECRET # [!code ++]
```

> [!NOTE]
>
> Configure your client to 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).

Remove any `X-Mailgun-*` headers (for example `X-Mailgun-Tag` or `X-Mailgun-Variables`) from your messages. They have no effect on turboSMTP.

## Option 2: Convert API calls

Mailgun sends form fields to a per-domain URL with Basic auth. turboSMTP takes a JSON body on a single endpoint with header authentication.

Enable **HTTP API Sending** on the Consumer Key used below.

**1. Replace Basic auth and form fields with headers and a JSON body:**

```bash Mailgun theme={"system"}
curl -s --user 'api:YOUR_API_KEY' \
  https://api.eu.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
  -F from='Shop <orders@yourdomain.com>' \
  -F to='recipient-1@example.com' \
  -F to='recipient-2@example.com' \
  -F subject='Your order has shipped' \
  -F text='Your order is on its way.' \
  --form-string html='<p>Your order is on its way.</p>'
```

```bash turboSMTP theme={"system"}
curl -X POST https://api.eu.turbo-smtp.com/api/v2/mail/send \
  -H "consumerKey: YOUR_CONSUMER_KEY" \
  -H "consumerSecret: YOUR_CONSUMER_SECRET" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

```bash Diff nocopy theme={"system"}
curl -s --user 'api:YOUR_API_KEY' \ # [!code --:8]
  https://api.eu.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
  -F from='Shop <orders@yourdomain.com>' \
  -F to='recipient-1@example.com' \
  -F to='recipient-2@example.com' \
  -F subject='Your order has shipped' \
  -F text='Your order is on its way.' \
  --form-string html='<p>Your order is on its way.</p>'
curl -X POST https://api.eu.turbo-smtp.com/api/v2/mail/send \ # [!code ++:5]
  -H "consumerKey: YOUR_CONSUMER_KEY" \
  -H "consumerSecret: YOUR_CONSUMER_SECRET" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

**2. Move the form fields into the JSON payload:**

```json payload.json theme={"system"}
{
  "from": "Shop <orders@yourdomain.com>",
  "to": "recipient-1@example.com,recipient-2@example.com",
  "subject": "Your order has shipped",
  "content": "Your order is on its way.",
  "html_content": "<p>Your order is on its way.</p>"
}
```

### Field mapping

| Mailgun | turboSMTP | Notes |
| - | - | - |
| `--user 'api:KEY'` | `consumerKey` + `consumerSecret` headers | `Authorization` is ignored by `/mail/send`; it cannot authenticate the request |
| `/v3/{domain}/messages` | `/api/v2/mail/send` | One endpoint for all domains |
| `from` | `from` | Address, optionally `Name <address>` |
| `to` (repeated) | `to` | Comma-separated string |
| `cc` / `bcc` | `cc` / `bcc` | Comma-separated strings |
| `text` | `content` | Plain text body |
| `html` | `html_content` | HTML body |
| `attachment` (file upload) | `attachments[]` | Base64 `content`, `name`, `type`. See [Attachments](/docs/sending/attachments.md) |
| `h:X-Custom-Header` | `custom_headers` | Object of header names and values |
| `v:my-var` | No direct equivalent for a metadata map | Store metadata in your application; use a UUID `reference_id` for correlation |
| `o:tag` | `X-campaign-ID` | Review how your application groups messages; these are not identical features |
| `inline` | `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) |
| `/messages.mime` | [SMTP relay](/docs/sending/smtp-relay.md) | `/mail/send` does not use `mime_raw`; send pre-built MIME over SMTP with your Consumer Key and Secret |

## Replace webhooks

Configure turboSMTP [webhooks](/docs/analytics/webhooks.md) and map Mailgun events to turboSMTP's delivery events (`PROCESSED`, `DROPPED`, `DELIVERED`, `DEFERRED`, `BOUNCED`) and engagement events (`OPENED`, `CLICKED`, `UNSUBSCRIBED`, `REPORT`).

turboSMTP webhooks are unsigned. Replace any Mailgun signature check 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.

## Cut over safely

**1. Send a test**

Send to an internal address and confirm SPF and DKIM pass.

**2. Ramp up gradually**

Route part of your traffic to turboSMTP and compare results 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 Mailgun's queue has drained, remove only the DNS records and SPF mechanisms no longer needed by another service.

## Frequently asked questions

> [accordion] I use Mailgun's EU region. Which turboSMTP host should I use?
>
> Use `api.eu.turbo-smtp.com` for API sending and `pro.eu.turbo-smtp.com` for SMTP. Review regional setup and processing terms for your requirements.

> [accordion] Do I need separate credentials per domain like Mailgun?
>
> No. One Consumer Key and Consumer Secret pair works for all your authenticated domains. Use [subaccounts](/docs/account/subaccounts.md) if you need to separate clients or projects.

> [accordion] Can turboSMTP help me migrate?
>
> [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.