DEV Community

ReceiveHQ
ReceiveHQ

Posted on

Migrate from SendGrid Inbound Parse to ReceiveHQ

Migrate from SendGrid Inbound Parse to ReceiveHQ

This is a cut-over plan: keep the URL your app already POSTs to, change DNS, and use ReceiveHQ's SendGrid-compatible multipart format. It is written from official SendGrid Inbound Parse docs and ReceiveHQ's Webhook API docs / docs.md.

It is not a claim that every SendGrid field or size cap is identical. Compatibility is documented at the field level below.

What stays the same, and what does not

Same idea. Both products receive SMTP for a hostname and HTTP POST a parsed message to a URL you control.

MX host. Official SendGrid setup is: point the MX of the receiving domain or subdomain at mx.sendgrid.net. ReceiveHQ's MX is mx.receivehq.com. You will replace the MX, not add a second one that competes for the same hostname.

Payload. ReceiveHQ's payloadFormat id mailgun_sendgrid posts multipart/form-data. Field map for the SendGrid side of that format:

Purpose ReceiveHQ / SendGrid field
From from
To to
Subject subject
Plain text text
HTML html
Charsets charsets
Envelope (JSON string) envelope
SPF SPF
Raw RFC822 email
Attachment count attachments
Attachment n (raw binary) attachment1, attachment2, … and the same bytes again as attachment-1, attachment-2, …

The same POST also includes Mailgun-named copies (sender, recipient, body-plain, body-html, stripped-text, message-headers, attachment-count, content-id-map) because this format is a dual Mailgun/SendGrid payload. If your parser only reads SendGrid names, you can ignore the Mailgun keys.

Auth. ReceiveHQ does not send provider HMAC or signature headers (including no SendGrid-style signed webhook). If your app currently verifies a SendGrid signature, replace that check with HTTPS plus ReceiveHQ Basic auth, or another secret you control. Configure the username and password on the endpoint (console, or basicAuthUser / basicAuthPass on the MCP create/update tools). ReceiveHQ then sends Authorization: Basic <base64(user:pass)>.

Retries and status codes. ReceiveHQ: 2xx = success; 406 = permanent drop; any other status is retried with backoff 1m → 5m → 30m → 1h → 2h, up to the endpoint's maxAttempts setting. Official SendGrid Inbound Parse: unsuccessful POSTs that return 5xx are queued and retried; a 2xx stops retries; messages that cannot be delivered are dropped after 3 days, with no pre-drop notification. Do not assume the retry clocks match.

Redirects. Official SendGrid: the Inbound Parse webhook does not follow redirects. Use the final HTTPS URL in ReceiveHQ as well.

Size. Official SendGrid: total message size, including attachments, is 30 MB. Before you cut MX, send a test with the largest attachment you actually expect.

Step 1 — Inventory

In SendGrid and DNS, write down:

  • The receiving hostname (the one whose MX is mx.sendgrid.net).
  • The webhook URL (SendGrid will not follow a redirect — use that exact URL).
  • Whether you verify a signature.
  • Whether the app reads text / html / envelope / attachment1… or other keys (charsets, email, SPF, …).
  • Whether the destination must return 2xx quickly.

In ReceiveHQ, plan a tenant and inbound domain for that same hostname.

Step 2 — Create the ReceiveHQ endpoint (do not touch MX yet)

  1. Sign up at receivehq.com, create a tenant, and add the inbound domain (the hostname you already receive on, or a test subdomain first).
  2. Create a webhook endpoint:
    • URL: the existing app URL, unless you are introducing Basic auth and want a staged path first.
    • Format: Mailgun / SendGrid (multipart) — payloadFormat id mailgun_sendgrid.
    • Optional Basic auth on the endpoint.
  3. If you add Basic auth, ship the matching check in the app before production mail arrives. A 401 is retried, not dropped. Do not return 406 for an auth failure — 406 would drop the message.

Mail does not move until MX changes. DNS can be prepared in draft, but do not lower TTL and flip until you have tested (Step 4).

Step 3 — Code compatibility check

Keep your existing multipart parser if it already reads SendGrid field names. Confirm:

  • from, to, subject, text, html, envelope are present.
  • Attachments are raw binary under attachment1, attachment2, … (not base64). ReceiveHQ also sends attachment-1, … — a parser that iterates every file part may see each attachment twice; skip the hyphenated duplicates if you already count attachment1.
  • Idempotency: ReceiveHQ retries are at-least-once. If you keyed on a SendGrid-only id, pick a stable header or hash of the raw email field.

If the app was built on Postmark JSON, do not keep payloadFormat=postmark and expect SendGrid field names. A format mismatch can look like empty fields even when the delivery logged 2xx.

Step 4 — Test before the MX cut

Preferred: a test subdomain (inbound-test.example.com) with MX already on mx.receivehq.com, pointing at a staging copy of the webhook (or the production URL if you can filter by recipient).

Send messages that cover:

  • Plain text and HTML.
  • A known From / To / Subject.
  • envelope JSON (compare with what SendGrid used to post).
  • At least one attachment (attachment1).
  • A failure case: return 500 once and confirm a retry; return 2xx and confirm retries stop.

Inspect both your app logs and the ReceiveHQ console (deliveries, status, response).

Step 5 — MX cut-over

  1. Lower the receiving hostname's MX TTL ahead of time (how far ahead depends on the current TTL).
  2. Change MX from mx.sendgrid.net to mx.receivehq.com.
  3. Wait for DNS. Then send a real test to an address on that hostname.
  4. Watch ReceiveHQ deliveries and your app for a full TTL window (and a little longer) so cached resolvers drain.
  5. Leave the old SendGrid Inbound Parse setting in place until you are sure no residual mail is still arriving there; then remove it.

SMTP in flight or sitting on SendGrid during the cut will not automatically replay into ReceiveHQ. Plan a short overlap window and, if needed, a temporary subdomain rather than an instant hard cut on a busy address.

Step 6 — Aftercare

  • Confirm SPF/DMARC still match how you send (this product is inbound only; changing inbound MX does not replace your outbound SPF).
  • Pricing after the 10-email trial: €10/month or €100/year for 100,000 inbound emails, then €10 per additional 100,000, as published on receivehq.com.
  • If something in the multipart body does not match your SendGrid fixtures, treat that as a bug or a documented gap — do not assume unlisted SendGrid fields exist.

Further reading

When you are ready to move inbound parse off SendGrid, ReceiveHQ can keep your existing webhook URL and the mailgun_sendgrid multipart shape.

Top comments (0)