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)
- Sign up at receivehq.com, create a tenant, and add the inbound domain (the hostname you already receive on, or a test subdomain first).
- 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) —
payloadFormatidmailgun_sendgrid. - Optional Basic auth on the endpoint.
- 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,envelopeare present. - Attachments are raw binary under
attachment1,attachment2, … (not base64). ReceiveHQ also sendsattachment-1, … — a parser that iterates every file part may see each attachment twice; skip the hyphenated duplicates if you already countattachment1. - Idempotency: ReceiveHQ retries are at-least-once. If you keyed on a SendGrid-only id, pick a stable header or hash of the raw
emailfield.
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. -
envelopeJSON (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
- Lower the receiving hostname's MX TTL ahead of time (how far ahead depends on the current TTL).
- Change MX from
mx.sendgrid.nettomx.receivehq.com. - Wait for DNS. Then send a real test to an address on that hostname.
- Watch ReceiveHQ deliveries and your app for a full TTL window (and a little longer) so cached resolvers drain.
- 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
- Twilio SendGrid: Inbound Email Parse Webhook (MX
mx.sendgrid.net, 2xx / 5xx retries, 3-day drop, 30 MB cap, no redirects) - ReceiveHQ Webhook API docs and docs.md
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)