Objective
To explain how Twilio SendGrid handles delivery failures when sending data to your Inbound Parse webhook URL and to clarify the specific HTTP response codes required for successful processing.
Product
Twilio SendGrid
Question
How does SendGrid retry failed POST requests to my Inbound Parse URL, and will the sender be notified if my server fails to receive the email?
Answer
When SendGrid receives an email for your domain, it attempts to POST that data to your configured URL. The way our system handles this depends entirely on the HTTP status code your server returns.
Retry Behavior by Status Code
The Inbound Parse system classifies your server's response into three categories:
| Server Response | Action Taken | Result |
|---|---|---|
| 2xx (e.g., 200, 204) | Success | SendGrid considers the email delivered and removes it from the queue. |
| 5xx (e.g., 500, 503) | Retry | SendGrid assumes a temporary server error and will keep trying to send the data for up to 72 hours. |
| 4xx, 3xx, or DNS Error | Drop | SendGrid considers the request a permanent failure. The email is dropped immediately, and no retries are attempted. |
The 72-Hour Retry Schedule (for 5xx errors)
If your server returns a 5xx error, SendGrid automatically queues the message for retry. The frequency of these attempts starts rapidly and slows down over time:
- First hour: Retries occur every 5 to 10 minutes.
- Hours 2 through 72: Retries occur approximately every 3 hours.
- After 72 hours: If a 2xx status is never received, the email is dropped from the queue.
Important: No "Failed Delivery" Notifications
It is important to note that the Inbound Parse Webhook is a one-way data push.
- No notification to the Sender: If your server fails to receive the POST request (either via a 4xx error or after the 72-hour retry window), the original sender of the email will not receive a bounce or "undelivered" notification.
- No notification to the Account: There is currently no dashboard notification within the SendGrid UI to alert you that an inbound POST has failed. We recommend monitoring your own server logs to track incoming webhook traffic.
Procedure
To ensure your application processes Inbound Parse data reliably:
- Always Return 2xx Promptly: Configure your endpoint to return an HTTP 200 OK as soon as the data is received, even if your internal processing takes longer.
- Avoid 4xx Errors: Ensure your URL is public and does not return 401 Unauthorized or 403 Forbidden, as these will cause the email to be lost instantly.
- Monitor Your Endpoint: Check your web server logs regularly for 5xx errors to identify downtime before the 72-hour retry window expires.