Mailgun API defined by OpenAPI Specification (OAS) 3.1.0
Mailgun API (3.0.0)
Download OpenAPI description
Languages
Servers
US Mailgun
https://api.mailgun.net/
EU Mailgun
https://api.eu.mailgun.net/
Domain Tracking
Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.
Operations
Account Webhooks
Webhooks API to manage account-specific webhooks. You can create, retrieve, update, and delete webhooks programmatically. Account-level webhooks are configured independently for US and EU regions. When triggered, webhook URLs are deduplicated by event type, across account and domain levels to prevent redundant webhook sends.
Operations
Bodyapplication/jsonrequired
The start date (default: 1 day before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
The end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
A duration in the format of '1d' '2h'. If duration is provided then it is calculated from the end date and overwrites the start date.
The set of events to include.
| Items Enum Value | Description |
|---|---|
| accepted | logs with event=accepted |
| delivered | logs with event=delivered |
| failed | logs with event=failed |
| opened | logs with event=opened |
| unique_opened | logs with event=opened unique per message-id, recipient combination |
| clicked | logs with event=clicked |
| unique_clicked | logs with event=clicked unique per message-id, recipient combination |
| unsubscribed | logs with event=unsubscribed |
| complained | logs with event=complained |
| rejected | logs with event=rejected |
Optional set of analytics metric events. Will be converted into corresponding events.
| Items Enum Value | Description |
|---|---|
| accepted_incoming | accepted events where flags.is_authenticated is false |
| accepted_outgoing | accepted events where flags.is_authenticated is true |
| accepted | all accepted events |
| delivered_smtp | delivered events where envelope.transport is smtp |
| delivered_http | delivered events where envelope.transport is http |
| delivered_optimized | delivered events where i-delivery-optimizer is set |
| delivered | all delivered events |
| stored | all stored events |
| opened | all opened events |
| clicked | all clicked events |
- US Mailgun
https://api.mailgun.net/v1/analytics/logs
- EU Mailgun
https://api.eu.mailgun.net/v1/analytics/logs
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://api.mailgun.net/v1/analytics/logs \
-H 'Content-Type: application/json' \
-d '{
"start": "Mon, 08 Jul 2024 00:00:00 -0000",
"end": "Fri, 12 Jul 2024 00:00:00 -0000",
"filter": {
"AND": [
{
"attribute": "domain",
"comparator": "=",
"values": [
{
"label": "example.com",
"value": "example.com"
}
]
}
]
},
"include_subaccounts": true,
"pagination": {
"sort": "timestamp:asc",
"token": "cjsijbijewbu78t678tVTYUYU76754fyuiksin865g",
"limit": 50
}
}'Response
application/json
{ "start": "Mon, 08 Jul 2024 00:00:00 -0000", "end": "Fri, 12 Jul 2024 00:00:00 -0000", "items": [ { … } ], "pagination": { "previous": "cjsijbijewbu78t678tVTYUYU76754fyuiksi23h75", "next": "cjsijbijewbu78t678tVTYUYU76754fyuiksin98hh", "first": "cjsijbijewbu78t678tVTYUYU76754fyuiksin865g", "last": "875bunjnWkmis75bjklnsdk0s7jksnjknlknc64aTR", "total": 100 }, "aggregates": {} }
Stats
Mailgun collects many different events and generates event statistics which are available in your Control Panel. This data is also available via our stats API endpoint.
WARNING: This API is deprecated in favor of our Metrics API.
Operations
Events
Mailgun keeps track of every inbound and outbound message event and stores this data for at least 3 days.
WARNING: This API is deprecated in favor of our Logs API.
Operations
Send Alerts
Mailgun allows you to get instant notifications on the sending metrics that matter most, configured specifically for your unique business needs and assets. Route these alerts to the channels your team relies on. Stay on top of sending performance without the need to manually monitor.
Operations
Bounces
Bounces - Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox. Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.
Operations
Allowlist
The allowlist API provides the ability to allowlist specific addresses from being added to bounce list. You can allowlist by domain name (i.e example.com) or by specific address (i.e. alice@example.com). Mailgun doesn’t add an address to bounce list if the address is allowlisted. This API is very useful if you test against your private services and don’t want to constantly clean up bounce lists
Operations