Migrate from SendGrid

What changes, what doesn't

Both are REST APIs built around one call per email plus webhooks for delivery events, so the shape of your integration survives. SendGrid's structure is more elaborate (personalizations arrays, content type/value pairs) because it grew to support bulk personalization at scale; EuroMail's request body is a flatter JSON object for the common case. The honest side-by-side, including where SendGrid remains the better fit, is at euromail vs SendGrid.

Verify your domain on EuroMail while SendGrid still handles production traffic, then cut over. A config change, not a rewrite.

API mapping

The biggest structural change: SendGrid nests recipients inside personalizations to support per-recipient template substitution in one request. EuroMail's to is a flat field, for personalized batch sends, loop and call the endpoint once per recipient (or per intended batch), passing idempotency_key so retries never double-send. See Sending Emails.

Code before and after

curl:

# Before: SendGrid
curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer SG.xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "[email protected]" }] }],
    "from": { "email": "[email protected]" },
    "subject": "Welcome aboard",
    "content": [{ "type": "text/html", "value": "<h1>Welcome!</h1>" }]
  }'

# After: EuroMail
curl -X POST https://api.euromail.dev/v1/emails \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome aboard",
    "html_body": "<h1>Welcome!</h1>"
  }'

TypeScript:

// Before: SendGrid
import sgMail from "@sendgrid/mail";
sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

await sgMail.send({
  to: "[email protected]",
  from: "[email protected]",
  subject: "Welcome aboard",
  html: "<h1>Welcome!</h1>",
});

// After: EuroMail
import { EuroMail } from "@euromail/sdk";
const client = new EuroMail({ apiKey: process.env.EUROMAIL_API_KEY! });

await client.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome aboard",
  html_body: "<h1>Welcome!</h1>",
});

Python, Rust, and Go SDKs use the same field names as the REST API.

SMTP cutover

Same literal username, so most SMTP-relay plugin presets need only a host and password change. Full walkthroughs (WordPress, framework mailers) in Send Email via SMTP.

DNS: verify your domain before switching

1. Add your domain in the EuroMail dashboard and publish its DKIM, SPF, and DMARC records. See Domain Verification.
2. Keep SendGrid's records in place during the dual-run. DKIM lives under a different selector and SPF include:s stack, so both providers verify simultaneously.
3. Remove SendGrid's records on your own schedule after cutover.

Webhook event mapping

Signature verification changes: SendGrid signs with ECDSA over X-Twilio-Email-Event-Webhook-Signature / -Timestamp headers, which needs their helper library to verify correctly. EuroMail signs every payload with plain HMAC-SHA256 in the X-EuroMail-Signature header. A five-line function in any language, no library required. Swap your handler for the one in Webhooks.

Bring your suppression list

Export suppressions (bounces, spam reports, unsubscribes) from the SendGrid dashboard, then replay them:

curl -X POST https://api.euromail.dev/v1/suppressions \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "[email protected]",
    "reason": "migrated from SendGrid: hard bounce"
  }'

Details in Suppression Lists.

Your first 24 hours

Every new account spends its first 24 hours -- counted from account creation, not from your first send -- inside a probation window with two limits designed to stop day-one spam blasts without starving a real migration:

• A send-rate cap: 5 emails per minute and 25 per hour on day one, loosening over the first week.
• A recipient allowance: a token bucket of 20 that refills at 2 per hour, counted per deliverable recipient (to plus every cc and bcc). A settled, non-zero invoice raises the allowance to 1,000 -- a paid plan still inside its trial does not count as a payment. The allowance lifts entirely once the account is 24 hours old.

A refused send returns 429 with a retry-after header (the SMTP relay returns 452, which well-behaved mailers retry). Test sends from a not-yet-verified domain to your own address (sandbox mode) never consume the allowance, so integration testing is free.

The practical consequence for a migration: create your EuroMail account and verify your domain at least a day before cutover. By the time production traffic moves, the recipient allowance has expired and only the loosened week-one rate cap (15/minute, 75/hour) remains. If you must cut over with real volume on day one, settle your first invoice first -- 1,000 recipients covers a typical day -- or keep SendGrid running in parallel for the first 24 hours.

Honest gaps

• Dynamic templates with Handlebars-style logic don't port directly. SendGrid's template_id + dynamic_template_data system supports conditionals and loops in templates; move that logic into your application code, or rebuild the template with EuroMail's template engine.
• No categories cap. EuroMail's tags array has no fixed limit, unlike SendGrid's 10-category ceiling. Nothing to adapt, just noting the difference.
• IP pools and warm-up. If you use SendGrid's dedicated IP pools, EuroMail handles IP reputation and warm-up automatically per account. See Deliverability Insights.
• Full comparison at euromail vs SendGrid.

Cutover checklist

1. Create a EuroMail account at least 24 hours before cutover (probation limits expire with account age) and an API key with the emails:send scope (API Keys).
2. Verify your sending domain; confirm DKIM/SPF/DMARC show green.
3. Register your webhook endpoint and swap the signature verification.
4. Import suppressions from your SendGrid export.
5. Switch the endpoint, auth header, and flatten personalizations/content into to/html_body/text_body (or the two SMTP settings), accepting 202 as success.
6. Send a staging email end-to-end; confirm the delivered webhook arrives.
7. Cut production traffic over; watch the first hour in Analytics and Deliverability Insights.
8. Keep SendGrid read-only for a rollback window, then retire it.