Migrate from SendGrid
to Posthawk
Migrate from SendGrid to Posthawk in under an hour. This guide covers API mapping, code changes, and common pitfalls to watch out for.
Migration steps
Export your data
Download your email templates, suppression lists, and domain settings from the SendGrid dashboard. Export templates as HTML to reuse them in Posthawk.
Tip: SendGrid templates can be exported via their API: GET /v3/templates with ?generations=dynamic.
Deploy Posthawk
Set up Posthawk using Docker Compose or deploy to your cloud provider. Follow the self-hosting guide for a complete walkthrough.
Configure your domain
Add your sending domain in the Posthawk dashboard. Update your DNS records with the provided DKIM, SPF, and DMARC values.
Tip: You can run both SendGrid and Posthawk simultaneously during the transition by using different subdomains.
Update your code
Replace SendGrid API calls with Posthawk equivalents. The API structure is similar — most changes are just URL and header updates.
Test thoroughly
Send test emails to verify delivery, check DKIM signatures, and validate webhooks are firing correctly. Use the Posthawk dashboard to monitor delivery events.
Go live
Update your DNS to point to Posthawk for production traffic. Monitor delivery rates in the dashboard and remove SendGrid once you're confident.
Tip: Keep SendGrid active for 24–48 hours after switching as a fallback.
API mapping
Before & after
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
await sgMail.send({
to: 'user@example.com',
from: 'hello@yourapp.com',
subject: 'Welcome!',
html: '<h1>Hello!</h1>',
});const response = await fetch('https://api.posthawk.dev/api/v1/email/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.POSTHAWK_API_KEY,
},
body: JSON.stringify({
to: 'user@example.com',
from: 'hello@yourapp.com',
subject: 'Welcome!',
html: '<h1>Hello!</h1>',
}),
});Common gotchas
API key format differs
SendGrid uses Bearer token auth (Authorization: Bearer SG.xxx). Posthawk uses x-api-key header. Update your auth headers accordingly.
Template syntax change
SendGrid uses Handlebars ({{variable}}). Posthawk templates support both Handlebars and React Email — choose based on your stack.
Webhook payloads differ
SendGrid webhook events have a different shape than Posthawk events. Update your webhook handler to match the new payload structure.
Rate limits are configurable
SendGrid enforces fixed rate limits. Posthawk rate limits are configurable per workspace — set them based on your SES sending limits.
More migration guides
Migrate from Resend
Switch from Resend to Posthawk while keeping the modern developer experience you love.
Read guideMigrate from Postmark
Move from Postmark to Posthawk and cut your email costs by up to 10x while maintaining the same delivery quality through AWS SES.
Read guideReady to migrate?
Deploy Posthawk and start sending in minutes. Free to self-host, no credit card required for cloud.