Migrate from SendGrid to MailChannels Email API

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.

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Migrate from SendGrid to MailChannels Email API

Core difference

Feature mapping

Send payload notes

Template migration

Suppression policy

Marketing migration

Cutover checklist

​Core difference

​Feature mapping

​Send payload notes

​Template migration

​Suppression policy

​Marketing migration

​Cutover checklist

Core difference

Feature mapping

Send payload notes

Template migration

Suppression policy

Marketing migration

Cutover checklist