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

# Migrate from SendGrid to MailChannels Email API

> Learn how to migrate a SendGrid sending integration to MailChannels sender-risk infrastructure.

## Core difference

SendGrid is broad and mature, with JSON send payloads, personalizations, headers, attachments, reply-to values, template-like data, event webhooks, marketing resources, unsubscribe groups, and branded links. MailChannels is built for platforms where many downstream senders share infrastructure and reputation. The migration should move send calls, but it should also map tenant boundaries, domain authorization, suppressions, webhooks, and containment paths so risky senders can be isolated without disrupting legitimate mail.

## Feature mapping

| SendGrid concept                 | MailChannels concept                         | Migration approach                                                                                                                             |
| -------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Mail Send API                    | `/send` payload                              | Rewrite the send call to MailChannels authentication, endpoint, and payload conventions. Personalizations and attachments usually map cleanly. |
| Personalizations                 | `personalizations`                           | Preserve recipient-specific variables and addressing, but verify field names and nesting.                                                      |
| Dynamic template data            | `dynamic_template_data` and Mustache content | Keep runtime merge data, but move template rendering into application-controlled content.                                                      |
| Dynamic transactional templates  | Application-managed content                  | Export and review templates, then store them in application code or a separate template system.                                                |
| Verified senders                 | `from` identities plus authenticated domains | Keep valid `from` addresses, but rely on MailChannels domain authentication for durable production sending.                                    |
| Authenticated domains            | DKIM and Domain Lockdown                     | Create MailChannels DKIM records, publish DNS, and validate before cutover.                                                                    |
| Link branding                    | MailChannels tracking behavior               | Review tracking links and deliverability requirements. Do not assume SendGrid-style branded-link resources exist.                              |
| Subusers                         | MailChannels sub-accounts                    | Map subusers to sub-accounts when isolation, credentials, billing, or reporting boundaries need to remain separate.                            |
| Unsubscribe groups               | Suppression list plus `transactional` flag   | Collapse group-specific semantics into MailChannels transactional versus non-transactional suppression policy.                                 |
| Event Webhooks                   | MailChannels webhooks                        | Recreate endpoint registration and update consumers for MailChannels event schemas and signing behavior.                                       |
| Marketing lists and Single Sends | External audience and campaign workflow      | Export audience data and replace campaign orchestration outside the MailChannels Email API.                                                    |

## Send payload notes

SendGrid integrations often require less restructuring than other providers because MailChannels also centers the send request on message content plus `personalizations`. During migration, compare these areas carefully:

| Concern                        | SendGrid behavior                                     | MailChannels behavior                                       |
| ------------------------------ | ----------------------------------------------------- | ----------------------------------------------------------- |
| API authentication             | SendGrid API key bearer token                         | MailChannels API key authentication                         |
| Endpoint                       | SendGrid mail-send endpoint                           | MailChannels `/send` or `/send-async`                       |
| Merge data                     | Dynamic template data attached to personalizations    | `dynamic_template_data` used with Mustache-rendered content |
| Tracking                       | Account, template, or request-level settings          | Per-message `tracking_settings`                             |
| Transactional versus marketing | Often modeled through products and unsubscribe groups | Explicit send classification and suppression behavior       |

## Template migration

Do not treat SendGrid dynamic templates as a target-side object copy. MailChannels sending can use runtime dynamic data, but template storage and versioning should move to application code, a CMS, or another template-management service. Preserve template IDs in your migration notes only long enough to connect old application paths to their new content source.

## Suppression policy

Recommended defaults:

| SendGrid source                       | MailChannels target                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
| Bounces, invalid emails, spam reports | Suppress as both `transactional` and `non-transactional`.                                     |
| Global unsubscribes                   | Suppress as `non-transactional` unless business policy requires a total block.                |
| Unsubscribe groups                    | Map to `non-transactional` suppressions unless a group clearly applies to transactional mail. |

## Marketing migration

MailChannels Email API does not provide a SendGrid Marketing Campaigns equivalent with managed audiences, Single Sends, and campaign scheduling. Move marketing audience storage and campaign orchestration into a separate system, then use MailChannels as the governed delivery layer for permission-based messages that should move through shared-sender controls.

## Cutover checklist

* Replace SendGrid endpoint and authentication.
* Translate payloads and verify personalization rendering.
* Move templates out of SendGrid.
* Create and publish MailChannels DKIM records.
* Recreate webhooks and update event consumers.
* Import or recreate suppressions with clear transactional policy.
* Replace Marketing Campaigns workflows externally.
* Run test sends for each sending domain before production cutover.