The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Receiving email in an application is more involved than opening an inbox. Your app needs a mail server, DNS routing, MIME parsing, attachment handling, spam filtering, storage, and a reliable way to react when a message arrives. SendGrid’s Inbound Parse Webhook removes much of that infrastructure by accepting email for your domain and forwarding each message to your application as an HTTP request.
This guide covers the full path from DNS setup to production-ready processing. You’ll configure a domain or subdomain for inbound mail, create an Inbound Parse route, receive webhook payloads, extract message fields and attachments, and decide how to store or respond to incoming email safely.
You’ll also see the operational details that matter in real systems: validating requests, handling spam metadata, managing large payloads, testing deliveries, retry behavior, logging, monitoring, and designing webhook handlers that stay secure and reliable as email volume grows.
How SendGrid Handles Incoming Email
SendGrid receives inbound email through its Inbound Parse Webhook, a feature that turns messages sent to your domain into HTTP requests to your application. Instead of connecting to an IMAP inbox or polling a mailbox, your app exposes an endpoint, and SendGrid posts parsed email data to it when a message arrives. This makes inbound mail processing fit naturally into a web application architecture: receive a request, validate it, store what you need, and trigger your own business workflow.
#1 Best Overall
The flow starts with DNS. You delegate a subdomain, such as inbound.example.com or mail.example.com, to SendGrid by creating MX records that point mail delivery for that subdomain to SendGrid’s mail servers. Once those records are active, messages addressed to users at that subdomain can be accepted by SendGrid. For example, an email sent to [email protected] can be routed to your configured webhook URL as a mulart form POST.
When SendGrid receives a message, it performs the SMTP receipt step, parses the message, and sends the result to your endpoint. The payload commonly includes fields such as the sender, recipient, subject, plain-text body, HTML body, headers, envelope data, spam scoring details, and attachment metadata. If attachments are included, SendGrid can send them as uploaded files in the same mulart request. Your application is then responsible for deciding what to persist, what to reject, and what downstream action to perform.
Typical inbound processing flow
- A sender emails an address under the domain or subdomain configured for inbound parsing.
- DNS MX records direct the message to SendGrid.
- SendGrid accepts the message and parses its MIME structure.
- SendGrid sends an HTTP POST request to your webhook endpoint.
- Your application validates, parses, stores, and acts on the incoming message.
This model is useful for support ticket creation, reply handling, document ingestion, application workflows, and user-generated content submitted by email. For instance, a help desk system might map [email protected] to ticket ID 123, append the message body as a comment, upload attachments to object storage, and notify assigned agents. A billing platform might receive invoices at a dedicated address, extract attachments, and queue them for OCR or manual review.
Inbound Parse is not a traditional mailbox. SendGrid does not provide a user inbox for reading and managing these messages after delivery to your webhook. If your endpoint is unavailable, misconfigured, or returns unexpected responses, messages may not be processed the way your application expects. In production, you should treat the webhook endpoint as part of your mail delivery path: keep it fast, resilient, observable, and secure. The strongest implementations acknowledge the request quickly, place the parsed data or raw payload into durable storage or a queue, and process heavier work asynchronously.
Recommended Free Tools
Setting Up DNS and Inbound Parse Routing
Before SendGrid can receive mail for your application, you need to delegate inbound email handling for a domain or subdomain. In most production systems, this is done with a dedicated subdomain such as inbound.example.com, mail.example.com, or parse.example.com. Using a subdomain keeps inbound processing separate from your normal business email on example.com, which reduces the risk of disrupting employee inboxes, support mailboxes, or existing MX records.
SendGrid receives inbound messages through MX records. In your DNS provider, create an MX record for the domain or subdomain you want SendGrid to handle, and point it to SendGrid’s inbound mail server. For a subdomain like inbound.example.com, the record usually looks like this:
| Type | Host | Value | Priority |
|---|---|---|---|
| MX | inbound | mx.sendgrid.net | 10 |
The exact host field depends on your DNS provider. Some providers expect only the subdomain label, such as inbound, while others expect the full hostname, such as inbound.example.com. After saving the record, allow time for DNS propagation. Many changes appear within minutes, but cached DNS responses can take longer depending on the previous TTL value.
Choosing a routing domain
The routing domain you configure in SendGrid must match the domain that receives the MX record. If you set the MX record for inbound.example.com, configure that same hostname in SendGrid’s Inbound Parse settings. Once active, addresses such as [email protected] can be routed to your webhook. Your application can then interpret the recipient address to decide what to do with the message.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems- Use a subdomain for app ingestion: For example, reply.example.com for reply handling or uploads.example.com for document intake.
- Avoid changing root MX records unless intentional: Replacing MX records on example.com can redirect all company email to SendGrid’s parser.
- Plan recipient patterns: Addresses like [email protected] or [email protected] make it easier to map email to records in your database.
- Document ownership: Record which service owns each inbound subdomain so future DNS changes do not break mail routing.
After DNS is in place, create or update the Inbound Parse route in the SendGrid dashboard. In the SendGrid UI, go to Settings, then Inbound Parse, and add a hostname. Enter the receiving hostname, such as inbound.example.com, and provide the destination URL for your application’s webhook endpoint. This URL must be publicly reachable by SendGrid, so local development URLs will not work unless exposed through a tunneling service during testing.
SendGrid can also be configured to send raw MIME content instead of separated fields. For most application workflows, parsed fields are easier to start with because SendGrid extracts common values such as sender, recipient, subject, text body, HTML body, headers, attachments, and spam metadata. Raw MIME is useful when you need full control over message parsing, signature verification, unusual encodings, or exact header preservation.
Once the route is saved, send a test message to an address on the configured hostname, such as [email protected]. If DNS and routing are correct, SendGrid will accept the message and make an HTTP request to your webhook. At this stage, your endpoint should return a fast 2xx response after receiving the payload, even if deeper processing is queued for later. This confirms that the DNS path and SendGrid route are connected before you add more complex parsing, storage, and business rules.
Configuring the Inbound Parse Webhook
After your MX records point incoming mail to SendGrid, the next step is to tell SendGrid where to deliver parsed messages. In the SendGrid dashboard, open Settings, choose Inbound Parse, and add a new host and destination URL. The host should match the receiving domain or subdomain you configured in DNS, such as inbound.example.com. The destination URL is your application endpoint, for example https://api.example.com/webhooks/sendgrid/inbound.
SendGrid sends inbound email to your endpoint as an HTTP POST request using mulart/form-data. Your server must be reachable over the public internet and should respond quickly with a successful 2xx status after accepting the payload. If processing may take longer than a few seconds, store the raw fields or enqueue a background job, then return a response immediately. This prevents retries and keeps mail flow reliable during bursts of incoming messages.
Webhook fields to configure
- Receiving domain: The domain or subdomain that has MX records pointing to SendGrid.
- Destination URL: The HTTPS endpoint in your application that receives parsed email posts.
- Spam check: An optional setting that includes spam scoring fields in the webhook payload.
- Send raw MIME: An option that includes the full original message, useful when you need exact headers, advanced parsing, or archival storage.
The Send raw MIME option changes how much responsibility your application takes on. Without raw MIME, SendGrid extracts common fields such as sender, recipients, subject, text body, HTML body, headers, envelope data, and attachment metadata. With raw MIME enabled, your endpoint also receives the full RFC 822 message, allowing you to parse nested mulart structures, preserve original formatting, verify signatures, or reprocess the message later with a dedicated MIME parser.
Example endpoint behavior
- Accept only POST requests at the inbound email route.
- Parse multipart/form-data fields and files using your framework’s upload middleware.
- Extract core fields such as from, to, subject, text, html, headers, and envelope.
- Persist the message record, including a unique internal ID and received timestamp.
- Queue downstream work, such as ticket creation, reply routing, notification delivery, or attachment scanning.
- Return a 2xx response once the message has been safely accepted.
Use separate webhook URLs for development, staging, and production so test messages cannot accidentally create real customer records. For local development, a tunneling tool can expose your machine over HTTPS while you verify payload structure and routing behavior. In shared environments, include the receiving host or mailbox pattern in your routing rules so messages such as [email protected], [email protected], and [email protected] can be processed by the correct workflow after they arrive.
Parsing Incoming Email Payloads
After SendGrid receives a message for your configured domain or subdomain, it sends the email data to your Inbound Parse Webhook URL as an HTTP POST request. In most integrations, the request uses mulart/form-data, because the payload can include message fields, headers, and file attachments in the same submission. Your endpoint should use a framework or middleware that can parse multipart requests, such as Multer or Busboy in Node.js, Django’s request parsers in Python, or Laravel’s request handling in PHP.
The fields you receive depend on your Inbound Parse settings, especially whether you enabled the raw MIME option. Without raw MIME, SendGrid extracts common email parts into individual fields. With raw MIME enabled, you receive the full original message in an email field and must parse it yourself using a MIME library. For most application workflows, the extracted fields are easier to work with because they let you quickly access the sender, recipients, subject, body content, and spam metadata.
Common payload fields
| Field | Description | Typical use |
|---|---|---|
from |
The sender address, often including a display name. | Identify the customer, user, or external contact. |
to |
The recipient address that matched your inbound route. | Route messages to a mailbox, tenant, project, or ticket queue. |
cc |
Carbon-copy recipients, when present. | Preserve conversation participants. |
subject |
The email subject line. | Create ticket titles, thread labels, or notification summaries. |
text |
The plain-text body. | Store searchable content or generate previews. |
html |
The HTML body. | Render rich email content after sanitization. |
headers |
Original email headers as a string. | Extract Message-ID, In-Reply-To, References, and authentication details. |
attachments |
The number of attached files. | Decide whether to inspect file fields in the multipart request. |
Normalize addresses before using them for routing. Email fields can contain display names, quoted strings, angle brackets, and mulle recipients. Instead of splitting strings manually, use a mail address parser that returns structured values such as name and address. This helps avoid bugs when handling senders like "Support, Inc." <[email protected]>. Store both the normalized address and the original header value when auditability matters.
For threading, inspect the Message-ID, In-Reply-To, and References headers. A support desk, CRM, or collaboration tool can use these values to attach replies to existing conversations. If your product uses reply addresses such as [email protected], parse the local part of the recipient address as another routing signal. A reliable implementation usually combines recipient-based routing with header-based threading, because users may forward, reply-all, or change subject lines.
Recommended processing flow
- Accept the webhook quickly: validate the request, enqueue the parsed payload, and return a
2xxresponse before doing slow work. - Extract core metadata: capture sender, recipients, subject, headers, message identifiers, timestamp, and envelope values if provided.
- Choose a body representation: prefer
textfor indexing and previews, and sanitizehtmlbefore rendering it in a browser. - Resolve routing: map the recipient address or subdomain to the correct account, mailbox, ticket, workspace, or automation rule.
- Persist safely: save the original payload fields you need, but avoid storing unnecessary sensitive data.
HTML email should be treated as untrusted input. Strip scripts, event handlers, remote tracking elements if needed, unsafe URLs, and unsupported tags before showing it to users. Plain text is safer for search and notifications, but it can still contain phishing links, secrets, or personal data, so apply the same access controls and retention rules you use for other user-generated content.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Handling Attachments and Spam Checks
When SendGrid receives an inbound message with files attached, the Inbound Parse Webhook sends those files as part of a mulart/form-data request. Your endpoint should treat attachments as untrusted user input: read the metadata, validate the content, store the file outside your application runtime, and keep only references in your database. SendGrid includes fields such as attachments for the attachment count, plus numbered file parts such as attachment1, attachment2, and so on. Each file part typically includes the original filename, MIME type, and binary content.
A practical storage flow is to stream each attachment directly to object storage, such as Amazon S3, Google Cloud Storage, or Azure Blob Storage, rather than loading the whole file into memory. Generate your own storage key instead of trusting the sender’s filename, then save metadata such as the original filename, detected content type, file size, checksum, message ID, sender, and storage location. This makes later retrieval, auditing, virus scanning, and deletion much easier.
Attachment validation checklist
- Enforce file size limits: reject or quarantine files that exceed your application’s maximum size, even if SendGrid accepted the message.
- Validate file extensions and MIME types: compare the declared MIME type with server-side content detection rather than relying only on the uploaded headers.
- Rename stored files: use generated IDs or hashes to avoid path traversal, duplicate names, and unsafe characters.
- Scan for malware: route files through an antivirus or malware scanning service before making them available to users or internal systems.
- Restrict public access: store attachments privately and serve them through signed URLs or authenticated download endpoints.
SendGrid can also include spam-related fields in the webhook payload when spam checking is enabled for the Inbound Parse route. Common fields include spam_score and spam_report. The score gives your application a numeric signal, while the report provides more detailed filtering information from the spam engine. You can use these values to decide whether to process, quarantine, flag, or reject a message.
| Signal | Suggested handling |
|---|---|
| Low spam score | Process normally, while still applying sender, attachment, and content validation. |
| Moderate spam score | Store the message, mark it as suspicious, and avoid triggering automated workflows until reviewed. |
| High spam score | Quarantine the message, skip user notifications, and block attachment downloads by default. |
Spam checks should not be your only filter. Combine SendGrid’s spam data with your own controls: allowed recipient addresses, blocked sender domains, rate limits per sender, duplicate message detection, and content rules for links or executable files. For workflows such as support tickets, CRM ingestion, or document processing, it is safer to create the inbound record first with a status like pending_review or quarantined, then promote it after scanning and validation finish. This avoids losing forensic data while preventing unsafe content from reaching users or downstream automation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Securing and Validating Webhook Requests
Once your Inbound Parse endpoint is reachable from SendGrid, treat it like any other public ingestion API: assume that anyone can post data to it. The endpoint may receive valid mail events from SendGrid, retries from SendGrid, malformed requests from bots, or intentionally crafted payloads. A secure implementation verifies the request source where possible, authenticates the request, limits what it accepts, and stores only sanitized data.
Require HTTPS and a secret-bearing URL
Always configure the Inbound Parse Webhook URL with HTTPS. Terminate TLS at your load balancer, reverse proxy, or application server, and reject plain HTTP requests. SendGrid does not require you to expose a generic path such as /inbound; use an unguessable route segment or tokenized query string as an additional shared secret, such as /webhooks/sendgrid/inbound/9f4b7c…. This should not be your only control, but it blocks casual scans and accidental posts to the wrong endpoint.
- Use a dedicated endpoint: do not reuse the same route for other webhook providers or form submissions.
- Reject unexpected methods: accept only POST.
- Set body size limits: align limits with your maximum expected email and attachment size.
- Apply rate limits: throttle by IP, route, or tenant to reduce abuse and protect downstream storage.
Validate request shape before processing
Inbound Parse sends form-encoded mulart data, especially when attachments are enabled. Your handler should verify the content type, required fields, and expected field formats before parsing the message into your domain model. At a minimum, confirm that fields such as from, to, subject, envelope, and charsets are present when your workflow depends on them. If you route mail by recipient address, validate the parsed recipient against addresses or aliases you actually provisioned instead of trusting the raw to header.
Do not treat headers, HTML bodies, filenames, or attachment MIME types as trusted. Normalize email addresses, strip control characters from filenames, and generate your own storage keys for attachments. If you render the HTML body in an admin interface, sanitize it first to remove scripts, event handlers, tracking pixels if undesired, and unsafe links. Store the raw payload separately only if you need it for auditing or debugging, and keep it behind stricter access controls.
Free tools Windows power users keep installed
One-click scans. No signup required.
Authenticate and constrain the sender
For stronger authentication, place the webhook behind an API gateway or edge worker that requires a secret header, mutual TLS, basic authentication, or a signed token. If your architecture allows it, restrict traffic to SendGrid’s documented outbound IP ranges, but avoid relying on IP allowlists alone because ranges can change and proxies may obscure the original source. Combining network controls with an application-level secret gives you a safer failure mode.
| Control | What it protects |
|---|---|
| HTTPS | Prevents credentials, message content, and attachments from being exposed in transit. |
| Secret URL or header | Reduces unauthorized posts from clients that do not know the shared secret. |
| Recipient validation | Prevents processing mail for domains, aliases, or tenants you do not own. |
| Sanitization | Limits stored XSS, unsafe filenames, and malicious attachment metadata. |
Return a fast 2xx response only after the request passes basic validation and has been safely queued or persisted. Avoid running slow virus scans, OCR, LLM processing, or ticket enrichment inline; enqueue those jobs and let workers handle them asynchronously. For invalid requests, return 400 for malformed payloads or 401/403 for failed authentication, and log enough context to investigate without recording sensitive message bodies or attachment contents in application logs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Testing, Monitoring, and Production Best Practices
Before routing real customer email through SendGrid’s Inbound Parse Webhook, test the full path from DNS to application storage. Start with a dedicated subdomain such as inbound.example.com or parse-dev.example.com, then send messages from mulle email clients including Gmail, Outlook, Apple Mail, and a command-line SMTP tool. Each client formats MIME content slightly differently, so test plain text, HTML, replies, forwards, quoted threads, inline images, and messages with multiple recipients.
Use a staging webhook endpoint that mirrors production behavior as closely as possible. The endpoint should parse the same mulart form fields, run the same validation checks, upload attachments to the same class of storage, and write records using the same database schema. If you use background jobs in production, use them in staging too; otherwise, webhook timing, retry behavior, and attachment handling may look reliable during testing but fail under real load.
Practical test cases
- Basic delivery: send a simple text-only email and confirm that sender, recipient, subject, text body, and headers are stored correctly.
- HTML content: verify that HTML is sanitized before display and that a safe plain-text fallback is available.
- Attachments: test small files, large files near your limit, unsupported file types, and filenames with spaces or non-ASCII characters.
- Spam handling: send messages with suspicious content and confirm that spam scores and spam reports are logged and acted on consistently.
- Retries: temporarily return a non-2xx response from your webhook and verify how duplicate deliveries are detected and handled.
- Recipient routing: test aliases, plus addressing, catch-all behavior, and unknown mailbox handling.
In production, keep the webhook fast. A good pattern is to authenticate the request, extract metadata, persist the raw payload or normalized message record, enqueue follow-up work, and return a 2xx response quickly. Slow virus scanning, AI classification, CRM updates, ticket creation, and outbound auto-replies should run asynchronously. This reduces the chance of timeouts and makes SendGrid retry behavior easier to manage.
Monitoring should cover both the webhook endpoint and the downstream workflow. Track request counts, non-2xx responses, parsing failures, attachment upload failures, queue depth, job failure rates, storage errors, and processing latency. Add structured logs with a stable message identifier, recipient address, sender address, SendGrid event timestamp, and internal record ID. Avoid logging full message bodies or attachment contents unless your compliance model explicitly allows it.
| Area | What to monitor | Suggested response |
|---|---|---|
| Webhook availability | Spike in 4xx or 5xx responses | Alert the on-call team and inspect recent deploys, auth failures, and network errors. |
| Parsing pipeline | Missing body, headers, or attachment metadata | Store the raw inbound payload for replay and add parser regression tests. |
| Queues | Growing backlog or repeated job failures | Scale workers, pause nonessential jobs, and isolate poison messages. |
| Storage | Failed database writes or object uploads | Retry safely with idempotency keys and surface unresolved failures in an admin view. |
Design for duplicate and delayed delivery. Store an idempotency key derived from stable message data, such as the SendGrid-provided envelope, recipient, timestamp, and message headers where appropriate. If the same inbound email arrives again, update the existing record or ignore the duplicate rather than creating mulle tickets, comments, or auto-replies. Also set clear retention rules for raw MIME, parsed bodies, attachments, and spam reports so your system does not keep sensitive email content longer than needed.
Finally, document operational runbooks for common incidents: DNS misconfiguration, expired webhook credentials, sudden spam floods, attachment storage outages, and malformed MIME messages. Keep a small set of replayable sample payloads for regression testing after parser changes. With realistic tests, targeted monitoring, idempotent processing, and clear retention policies, SendGrid inbound email can run as a dependable production workflow rather than a fragile HTTP callback.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
Do I need to move all email for my domain to SendGrid to use the Inbound Parse Webhook?
No. You can use a subdomain such as inbound.example.com or reply.example.com and point only that subdomain’s MX records to SendGrid. This lets SendGrid receive and parse messages for specific inbound workflows without disrupting normal mailbox hosting for addresses like [email protected].
What should my webhook endpoint return to SendGrid after receiving an inbound email?
Your endpoint should return a fast 2xx HTTP response once the request is accepted. Do not perform slow work such as virus scanning, attachment processing, or CRM updates before responding; instead, enqueue the payload or saved message reference for background processing. If your endpoint returns an error or times out, SendGrid may treat delivery as failed.
How do I handle attachments from SendGrid’s Inbound Parse Webhook?
When attachments are enabled, SendGrid sends the webhook as mulart/form-data with attachment files included as separate parts and metadata in fields such as attachment-info. Store attachments in object storage, record their filenames, content types, and sizes, and scan them before making them available to users. Set strict file size limits and reject or quarantine file types your application does not need.
How can I verify that inbound emails really came from SendGrid?
Use SendGrid’s signed webhook verification if available for your account and implementation, and validate the signature before trusting the payload. You should also serve the endpoint over HTTPS, restrict accepted methods to POST, apply rate limits, and keep the parse URL difficult to guess. Avoid relying only on the sender address, because email headers can be forged.
Can my application reply automatically to an email received through SendGrid?
Yes. After parsing the inbound message, your application can send a response using SendGrid’s Mail Send API, usually addressed to the parsed from or reply-to value. To keep email threads intact, include an appropriate subject, preserve or reference the original message ID when useful, and avoid sending auto-replies to suspected spam, bounces, or mailing lists.
Bottom Line
SendGrid’s Inbound Parse Webhook gives developers a practical way to turn incoming email into application data, as long as the domain, MX records, webhook endpoint, and parsing are set up carefully. Once messages reach your app, validate requests, handle attachments safely, normalize payloads, and store only what you need.
Before going live, test with real email clients, monitor failures, protect against spam and oversized payloads, and build retry-safe processing into your workflow. The next step is to configure a dedicated inbound subdomain, create a secure webhook endpoint, and run end-to-end tests from receipt through storage or automated response.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
