Core difference
SendGrid and MailChannels have similar runtime send models: both support JSON payloads with personalizations, headers, attachments, reply-to values, template-like data, and event webhooks. The main differences are around provider-managed templates, marketing-campaign resources, unsubscribe-group semantics, branded links, and domain authentication workflow.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 pluspersonalizations. 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 only as the delivery API for messages that should be sent through MailChannels.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.