Bounce Handling
There are two concepts to keep in mind when thinking about bounce handling:
bounces, which are retained within AlumnIQ and used as a buffer damper on future marketing sends for a period of weeks (0-3 depending on customer's ability to process/clean/refresh email addresses in response to a bounce event). Once that damper window closes we'll not exclude that email address from future sends (until it happens again...)
and
suppressions, which are retained within Mailgun (our outbound mail service provider). Suppressions "latch" when the receiving mail server kicks back a notification of non deliverability and do not clear automatically. Mailgun suppressions will prevent deliveries to the suppressed email addresses until the suppressions are purged.
Because having two resources to look at in order to handle bounce data is inconvenient, we've unified the bounce data behind a single API resource:
/mail/all-bounces?rangeBegin=yyyy-mm-dd
rangebegin is required, rangeend is optional. If no rangeend is provided, the end is well past our collective retirement dates (even though, obviously, we can't include future bounces).
A sample response is included in the API dashboard: https://{your_host_name}/api/v1/#unifiedBounceCollectionapi_31F91D382A6B438B0B8FF1B63EA74218
The type property indicates the source of the bounce - bounceevent is a hard bounce, and a suppression is...that. You'll see that the code and message strings attached to each vary in structure and will generally require some degree of interpretation. We do not include soft bounces in this feed, as they are transient and will always resolve to either a delivery or a hard bounce - hence no immediate action could or should be taken by you with them.
Hard bounces in most situations have a messageId and/or xid attached. Suppressions will never have either one. Both will always have an emailaddress and a timestamp when the bounce/suppression was recorded (adjusted to central time in your case).
You'll notice that all suppressions are returned regardless of rangeBegin - this is deliberate, as suppressions are latched until purged -- including them is a reminder that Mailgun will still block delivery until the purge happens. How do you do that? Read on!
Once you get the data
Apply your internal methodology for strikes, deactivating as needed. Once you've processed the data to your satisfaction, revisit the AlumnIQ mail reporting area (Mail > Reporting) in admin and purge the suppressions.
Suppressions provide valuable air cover for your sender reputation. The more times you attempt to deliver to a known-bad account (from their perspective), the more dim their view of your data hygiene and best practices compliance is. If you're handling bounces daily your suppressions should be very small in size and scope (though I'm sure we'll see more in the first couple sends than future ones).
How often?
Pull daily. Process daily. Purge weekly. Doing any/all of these more frequently would be a bonus, but admittedly is asking too much.
Where else can we see this data?
You can poke the API resource manually under System > Reports and get a very rough CSV equivalent. This is really meant for diagnostics and not regular/routine use.
I want more than bounces (or I only care about bounces on a specific message)!
You can have it! We make that available under the /mail/message-activity resource - opens, clicks, bounces, spam - on a ranged or message specific basis. This is a fun area for future study if curious.
Future
After discussing this internally, if you can commit to each other to process bounces in a very timely fashion, we're not opposed to exposing the Mailgun purge function as another API resource that you could hit immediately after fetching the all-bounces data.
Coda
Remember this suppression feature is in your best interest, even if slightly inconvenient. Repeated attempts to send to a known-bad email address will put you in a spam jail that's really hard to get back out of. Good data hygiene will benefit your communications folks immensely!
Last updated