SendGrid Inbound Parse pipeline: receiving mail by webhook

TL;DR

In Settings > Inbound Parse, add the hostname and the exact HTTPS URL that receives the parsed POSTs. Slow handlers cause retries and duplicates.

Steps

1. Goal: inbound mail arriving as structured POSTs at your endpoint.
2. Step 1. Point the receiving domain's MX records at mx.sendgrid.net. Mail for the domain now flows to SendGrid.
3. Step 2. In Settings > Inbound Parse, add the hostname and the exact HTTPS URL that receives the parsed POSTs. No redirects in front of it.
4. Step 3. Build the receiver: parse the raw MIME payload, return 2xx immediately, and hand the message to a queue for real processing. Slow handlers cause retries and duplicates.
5. Step 4. Handle the failure modes: 5xx responses are retried, so make processing idempotent; messages undeliverable after three days are dropped, so monitor for gaps.
6. Step 5. Test with real messages including attachments and odd encodings before pointing production MX at it.
7. Verify: test messages arrive within seconds, retries from a forced 5xx do not double-process, and attachments parse. Pitfall: MX changes propagate slowly; keep the old receiver live during the cutover.

When to use

You are seeing this: Goal: inbound mail arriving as structured POSTs at your endpoint. Use this skill when you run into "SendGrid Inbound Parse pipeline: receiving mail by webhook".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The inbound parse doc: point the domain's MX records at mx.sendgrid.net, configure a hostname and URL in the console, and SendGrid POSTs the raw MIME message; the endpoint must return 2xx quickly, failed POSTs returning 5xx are retried, and undelivered messages are dropped after three days. Webhooks do not follow redirects. Sources: https://docs.sendgrid.com/for-developers/parsing-email/inbound-email