Mailgun Delivery Export
🎯 Functional documentation
The Mailgun report scheduled provider periodically exports whether the emails that Mailgun
sent for a domain were delivered, and why not, to a CSV file and uploads that file to a configured file transfer
provider (e.g. SFTP). It is the delivery reporting of the emails that the
Mailgun email provider sends, so MAIL_DOMAIN holds the same domain
as the email provider it reports on, and API_KEY a Mailgun key that is allowed to read the event logs of the account that domain belongs to. The events
are read from the Mailgun Logs API,
which replaces the deprecated Events API.
The file holds one row per message and recipient with the
current status: Mailgun reports every step of a message as a separate event (accepted, then delivered or failed), and
the export combines those into the latest one. Only the events that tell whether a message was delivered are read
(accepted, rejected, delivered and failed), so an open or a click never replaces the delivery as the status.
The export window starts at the start of the day of the RELATIVE_DATE setting, configured as a
relative datetime, and ends at the start of
the current day, both in UTC. Without RELATIVE_DATE, Mailgun returns the events of the last day. A message that was accepted just before an export is only reported as delivered in a following one, so
use a window that overlaps the previous export, for example > -2d on a daily schedule, and keep the row with the
latest updatedAt per id and to on the receiving side. Mailgun keeps its events for a limited period that depends
on the Mailgun plan, so the export should run at least daily.
The CSV file contains the following columns:
| Column | Description |
|---|---|
id | Identifier of the message, which is the identifier Mailgun returned when the email was accepted |
from | Sender of the email |
to | Recipient of the email |
subject | Email subject |
status | Current status: accepted (still on its way), delivered, failed or rejected (refused by Mailgun) |
reason | Why the message failed, e.g. bounce, suppress-bounce or generic |
failure-code | SMTP code of the receiving mail server, e.g. 550, for a failed message |
failure-description | Answer of the receiving mail server, e.g. that the mailbox does not exist, for a failed message |
createdAt | Moment Mailgun accepted the message, in UTC |
updatedAt | Moment of the current status, in UTC |
severity | For a failed message: temporary when Mailgun still retries it, permanent when it gave up |
⚙️ Configuration
Implementation class
MailgunReportScheduledProvider