SendGrid Inbound Parse Webhook: Extract Email Data to JSON

SendGrid Inbound Parse is a popular way to receive email at your application. Point an MX record at SendGrid, and every message sent to that domain gets posted to a URL you control. It is genuinely useful infrastructure. The catch that surprises most developers is that it delivers the email's parts, the text, the HTML, the attachments, but it does not pull out the order number, the invoice total, or the customer name. That last step is still your code to write and maintain. This guide covers exactly how Inbound Parse works, how to set it up, what the payload contains, and where the line sits between what SendGrid does and what you have to build.

What is SendGrid Inbound Parse?

SendGrid Inbound Parse is a webhook that receives incoming email for a domain you control and posts its contents to a URL of your choice. SendGrid grabs the headers, body, and attachments from any message sent to your configured hostname, packages them as multipart form-data, and POSTs that to your endpoint so your application can act on the email.

It is the inbound counterpart to SendGrid's outbound sending. Where the send API pushes mail out, Inbound Parse catches mail coming in and forwards it to your server as structured form fields. What it does not do is interpret the meaning of the message, which is the part most people actually want.

How does the SendGrid Inbound Parse webhook work?

The webhook works by routing email through SendGrid's mail servers and then posting each message to your endpoint. You point an MX record for a hostname at mx.sendgrid.net, so mail addressed to that hostname lands at SendGrid. SendGrid then builds a multipart form-data payload from the email and POSTs it to the URL you registered in the Parse settings.

Your endpoint receives the POST, reads the fields, and responds with a 2xx status code. The 2xx matters: if your server returns anything else, SendGrid treats the delivery as failed and retries it, so a slow or erroring endpoint can produce duplicate processing. There is no built-in signature on the request either, so securing the endpoint, for example with a hard-to-guess URL or your own token check, is on you.

How do I set up the SendGrid Inbound Parse webhook?

Setup is two steps: configure DNS, then register the webhook. First, add an MX record for the hostname you want to receive mail at, for example parse.example.com, pointing to mx.sendgrid.net with a standard priority. Second, in the SendGrid dashboard under Settings, open Inbound Parse, add a host and URL entry, and paste the public URL where SendGrid should POST each email.

A few practical notes save time. Use a dedicated subdomain so you do not disturb your main domain's mail. Your receiving URL has to be publicly reachable and return 2xx quickly, so during development a tunneling tool is handy for testing against a local server. Once DNS propagates, send a test email to any address at that hostname and watch it arrive as a POST.

What does the SendGrid Inbound Parse payload look like?

The payload is a multipart form-data POST with named fields for the email's parts. You get separate values for the sender, recipient, subject, plain-text body, HTML body, the SMTP envelope as JSON, attachment counts, and attachment metadata. A typical incoming order email arrives looking like this:

POST https://yourapp.com/inbound   (multipart/form-data)

from:     "Acme Orders" <[email protected]>
to:       [email protected]
subject:  Order #10482 confirmed
text:     Hi Sam, your order #10482 for $129.00 ships Tuesday.
html:     <table><tr><td>Order</td><td>10482</td></tr>...
envelope: {"to":["[email protected]"],"from":"[email protected]"}
attachments: 1
attachment-info: {"attachment1":{"filename":"invoice.pdf","type":"application/pdf"}}

Notice what you have and what you do not. You have the whole body, but the order number 10482 and the total of 129.00 are still buried inside the text and HTML strings. Getting them into named fields is a parsing job your code has to do.

Is SendGrid Inbound Parse free?

Inbound Parse is included as a feature of a SendGrid account rather than billed as a separate per-message product, and SendGrid offers a free tier you can start on. So the webhook itself does not carry an extra line-item charge for most users. The real cost is engineering: you still build, host, and maintain the endpoint and the parsing logic that turns each POST into usable data.

That is the trade worth weighing. The webhook is cheap to switch on, but every email format you handle, every layout change a sender makes, and every new field you need adds work to the code on your side. For a single, stable email type that may be fine; across many senders it adds up.

What is the SendGrid Inbound Parse size limit?

SendGrid Inbound Parse cannot process messages larger than 30MB, including all attachments. Anything over that limit will not be delivered to your webhook. For most transactional email, an order confirmation, a lead notification, a single invoice PDF, this is plenty of headroom, but bulk attachments or large reports can run into it.

If you expect big attachments, plan for the ceiling: validate sizes upstream where you can, and be aware that an email silently exceeding 30MB will simply not arrive as a POST rather than failing loudly. Building a check for missing-but-expected messages is a sensible safeguard.

Can SendGrid Inbound Parse read attachments?

Inbound Parse delivers attachments to your webhook, but it does not read what is inside them. Files arrive as parts of the multipart POST along with an attachment-info field describing each one's filename and type. A PDF invoice or a CSV comes through intact, yet pulling the line items or rows out of that file is again code you write.

This is a common point of confusion. Receiving the attachment and extracting its contents are different problems. If the data you care about lives inside an attached PDF or spreadsheet, you will need a parser on top of the webhook. Our guide on how to extract data from email attachments walks through the PDF, CSV, and spreadsheet cases.

Why does SendGrid Inbound Parse fail DMARC or spoof check?

Failures here usually come from forwarding mail that was authenticated for a different domain. When a message passes through Inbound Parse and SendGrid's spoof or authentication checks flag it, the original sender's SPF and DMARC alignment often no longer matches the path the mail took, so a legitimate forwarded email can look suspicious. The POST may still arrive, but with authentication fields indicating a failure.

The fix is to read the SPF and authentication values SendGrid includes in the payload and decide how strict to be, rather than rejecting outright. For mail you control and expect, treat these as signals to log, not hard blocks, since strict enforcement on forwarded mail tends to drop messages you actually wanted.

How do I extract specific fields from SendGrid Inbound Parse?

To get specific fields, you parse the text and HTML the webhook delivers, typically with regular expressions, an HTML parser, and an attachment reader for PDFs or spreadsheets. SendGrid gives you the raw body; you write the rules that locate the order number, total, dates, and line items inside it and map them to named keys. There is also a raw MIME option if you prefer to parse the entire message yourself.

That code is the part that grows over time. Every sender formats their emails a little differently, HTML tables break naive text parsing, and a layout change can silently stop a regex from matching. The alternative is to send the email to a service that does field-level extraction for you and returns clean JSON. If you want to skip writing parsers, see how to convert email to JSON and how the email parser API returns named fields you define rather than raw bodies.

What is the best alternative to SendGrid Inbound Parse?

The best alternative is a parser that handles both receiving and extraction, so you get clean fields instead of a raw payload to process. SendGrid Inbound Parse is a strong choice when you want full control and are happy to own the parsing code. When the goal is structured data with little engineering, a dedicated email parser is the better fit because it reads the body and HTML tables and returns the values you named.

MailParse sits in that second camp. You connect a mailbox or forward mail, define the fields you want once, and it returns them as a spreadsheet row or JSON over an API or webhook. See exactly how it works as a SendGrid Inbound Parse alternative that extracts named fields instead of handing you a raw payload to parse. If you are comparing approaches, the best email parser guide lays out what to look for, and developers who automate with workflow tools may also want the n8n email parser walkthrough or the n8n email parser integration page. If your inbound mail runs through AWS instead of SendGrid, the same receive-then-extract split applies to Amazon SES inbound email parsing.

Choosing between building and buying

The honest summary is that SendGrid Inbound Parse solves delivery, not interpretation. If your project needs the raw email at a URL and you have the engineering time to maintain extraction code, it does that job well. If what you actually need is the order number, the invoice total, and the line items as clean fields, the parsing layer is the real work, and it is worth deciding upfront whether to build it or hand it off.

When you would rather receive structured data than raw POSTs, the MailParse email parser API turns incoming mail into named fields and structured JSON without parsing code on your side, and you can route the same output to Excel and CSV when a person needs to work with it. For what that payload actually contains once MIME, encoded headers, and nested parts are decoded, see converting email to JSON. Either way, the goal is the same: stop retyping data that already arrived in an email.