Migrate from SendGrid

Moving from SendGrid to Mailhuset is mostly a change of request shape: SendGrid nests recipients and content in personalizations and content arrays, and Mailhuset keeps them flat. Plan for an afternoon, most of it waiting on DNS.

1. Verify your sending domain

Add your domain under Domains and publish the SPF, DKIM and DMARC records, the same idea as SendGrid's domain authentication. See Verify a sending domain. Keep SendGrid's records in place until you have cut over, so both providers can send in parallel.

Sending through SendGrid's SMTP service rather than its API? Then you can skip step 2: point your app's SMTP settings at smtp.mailhuset.com (port 587 with STARTTLS) with an SMTP credential, and no code changes. SMTP is included on paid plans.

2. Swap the API call

A SendGrid request like this:

{
  "personalizations": [{ "to": [{ "email": "a@example.com" }] }],
  "from": { "email": "hello@yourdomain.com", "name": "Acme" },
  "subject": "Your receipt",
  "content": [{ "type": "text/html", "value": "<p>Thanks for your order</p>" }]
}

becomes:

POST https://api.mailhuset.com/v1/email
Authorization: Bearer $MAILHUSET_API_KEY

{ "from": "Acme <hello@yourdomain.com>", "to": ["a@example.com"],
  "subject": "Your receipt", "html": "<p>Thanks for your order</p>" }

SendGrid sends one request with several personalizations as separate messages. In Mailhuset that is POST /v1/email/batch, up to 500 messages per call. See Send email via the API, or use an official SDK.

3. Recreate templates

Re-create your SendGrid dynamic templates under Templates. Give each an alias and pass the same data as templateModel. Plain fields carry over as they are: {{ first_name }}, dotted paths like {{ order.total }}, and {{{ raw_html }}} for unescaped HTML.

Mailhuset templates have no {{#if}} or {{#each}} blocks. Where a SendGrid template loops over line items or shows a section conditionally, build that part in your code and pass it in as one field (for example {{{ items_html }}}), or send the finished html directly. See Templates.

4. Bring your suppressions with you

Export SendGrid's bounces, spam reports and unsubscribes, then import them so Mailhuset never mails an address SendGrid already learned to avoid:

POST https://api.mailhuset.com/v1/suppressions/import
Authorization: Bearer $MAILHUSET_API_KEY

{ "entries": [
  { "address": "old@example.com", "reason": "HARD_BOUNCE" },
  { "address": "angry@example.com", "reason": "COMPLAINT" },
  { "address": "optout@example.com", "reason": "UNSUBSCRIBE" }
] }

Up to 20,000 entries per call. Bad rows are skipped and counted, never fatal. See Suppressions.

5. Point webhooks at Mailhuset

Add your endpoint under Webhooks and map SendGrid's Event Webhook types:

SendGrid's processed corresponds to Mailhuset accepting your API call, and deferred has no event because Mailhuset retries for you. Every Mailhuset event is signed, so verify it with your endpoint's signing secret. See Webhooks.

6. Cut over

Send a share of traffic through Mailhuset first, watch delivery and events in Activity, then move the rest. Raise volume over a few days rather than in one spike, so mailbox providers get used to the new sending path.

Questions during migration? Email support@mailhuset.com.

Need help? Email support@mailhuset.com.