Based on a few tests I ran, it does not appear SendGrid will ever send a notification to the sender, nor is there any easy way to ascertain whether SendGrid has dropped any inbound emails.
Although the documentation wording is slightly ambiguous, my understanding based on testing (which aligns with the documentation wording) is this:
- Server returns 2xx: email is deemed accepted, no further attempts made.
- Server returns 5xx: server has error, attempts made until 2xx is returned (see below for timing of subsequent attempts), or 72 hours lapses
- Server returns any other response, or DNS records do not exist: email is deemed failed, no further attempts made.
My conclusions are based on a number of tests I ran over the course of a week, from which I ascertained the following:
Case 1. Parse server returns 400 or 403 error
The email is dropped after one attempt.
No further attempts are made to POST the email.
No notification is sent to the sender or to the SendGrid account.
(Test method: Configure SendGrid to a URL that returns one of the above error codes. Checked server logs over 1 week, and noted only one attempt was made.)
Case 2. The parse hook URL does not have a DNS record
The email is dropped, presumably after one attempt.
No notification is sent to the sender or to the SendGrid account.
(Test method: configure the hook URL to a subdomain that does not have any DNS records. Run DNS search and try opening the hook URL to confirm the DNS records do not point anywhere. Send an email. Then, after 12 hours, add an appropriate record to the subdomain to point it to a script. Checked server logs and confirmed no attempts were made to POST the email. A subsequent email attempt successfully POSTed.)
Case 3. Parse server returns 500 error
SendGrid attempts to POST to the hook URL at the following intervals:
+0 +5m +10m +15m +20m
+25m +35m +50m +1h20m +2h20m
...then every 3 hours
The last attempt occurs +71h20m
The 20 min offset is a bit unusual, but it falls on the hour, so it may be because the message is queued to attempt POSTing on the hour.
No further attempts are made to POST the email after 72 hours.
No notification is sent to the sender or the SendGrid account.
Statistics
The documentation refers to the availability of statistics, however, I have found the numbers to be inaccurate.
For example, during my testing, I had a number of emails go through the API, including some that were intended to be successful (and did indeed POST to my server) and a few that were intended to fail (as part of the above testing), however, the numbers returned did not align.
Takeaways
Care should be exercised in the following scenarios:
- Server downtime: this would ultimately depend on how the server is configured. If the server returns a 5xx response code, SendGrid will keep trying to POST the email. I also tried to test a timeout scenario, however, SendGrid seems to be very patient (e.g. I made my script pause for 10 minutes, SendGrid kept the connection for 10 minutes, though interestingly, due to the second attempt occurring after 5 mins, the email POSTed twice).
- Server misconfiguration that returns 4xx error codes. SendGrid will drop the email.
It should also be noted if an email is dropped, there doesn't appear to be any reliable method of finding this out.
