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
Bodyrequired
- application/json
- none
A start date (default: 7 days before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
An 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' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
Attributes of the metric data such as 'subaccount'. See dimensions
| Items Enum Value | Description |
|---|---|
| bot | The automated system that engaged with the email, e.g. apple, gmail |
| country | Country from which the email was sent, e.g. US, FR, MX |
| ip_pool | IP pool used to send the email |
| recipient_domain | Recipient domain, e.g. gmail.com |
| recipient_provider | Email service provider of the recipient, e.g. Gmail, Outlook US, Apple |
| ip | IP address used to send the email |
| domain | Domain used to send the email, e.g. example.com |
| tag | Custom tag attached to the message |
| device | Type of device used to send the email, e.g. mobile, desktop |
| subaccount | Subaccount identifier |
Name of the metrics to receive the stats for such as 'processed_count'. See metrics
| Items Enum Value | Description |
|---|---|
| accepted_incoming_count | Mailgun accepted the API request to forward, and the message has been put in your queue. These accepted events only cover routes, forwards, and mailing lists. Mailing lists will record a single accepted incoming event, with emails sent to recipients recording their own accepted outgoing events. |
| accepted_outgoing_count | Mailgun accepted the API request to send, and the message was put in your queue. Batch sends will result in one additional accepted outgoing event to record the initial batch request. Accepted events are not associated to IP addresses. The “processed” metric can be used in place of accepted to view data by IP. |
| accepted_count | A sum of incoming and outgoing accepted events. This includes all accepted emails to be sent as well as routes, forwards, mailing lists, and batch events. To only view accepted events on emails sent to recipients, use the Accepted Outgoing metric. Accepted events are not associated to IP addresses. The “processed” metric can be used in place of accepted to view similar data by IP. |
| delivered_smtp_count | The count of delivered events for emails sent to recipient addresses. |
| delivered_http_count | The count of delivered events for routes and forwards. |
| delivered_optimized_count | Emails delivered with Send Time Optimization. |
| delivered_count | Mailgun sent the email and it was accepted by the recipient email server. |
| processed_count | Messages processed after being accepted. Processed messages are billed to your account at the end of the month. |
| sent_count | A count of all sent messages. This includes delivered and failed messages, but does not include suppressed messages. |
| opened_count | The email recipient opened the email and enabled image viewing. Tracking must be turned on. |
- US Mailgun
https://api.mailgun.net/v1/analytics/metrics
- EU Mailgun
https://api.eu.mailgun.net/v1/analytics/metrics
- 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/metrics \
-H 'Content-Type: application/json' \
-d '{
"start": "Mon, 13 Nov 2023 20:56:50 -0600",
"end": "Wed, 20 Dec 2023 20:56:50 -0600",
"resolution": "month",
"duration": "1m",
"dimensions": [
"time"
],
"metrics": [
"accepted_count",
"delivered_count",
"clicked_rate",
"opened_rate"
],
"filter": {
"AND": [
{
"attribute": "domain",
"comparator": "=",
"values": [
{
"label": "example.com",
"value": "example.com"
}
]
}
]
},
"include_subaccounts": true,
"include_aggregates": true
}'Response
application/json
{ "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "pagination": { "sort": "timestamp:asc", "skip": 1, "limit": 10, "total": 1000 }, "items": [ { … }, { … } ], "aggregates": { "metrics": {} } }
Bodyrequired
- application/json
- none
A start date (default: 7 days before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
An 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' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
Attributes of the metric data such as 'subaccount'. See dimensions
| Items Enum Value | Description |
|---|---|
| subaccount | Subaccount identifier |
| time | The time that your events occurred |
Name of the metrics to receive the stats for such as 'processed_count'.
| Items Enum Value | Description |
|---|---|
| email_validation_count | Total number of email validations performed |
| email_validation_public_count | Number of email validations performed using the public API |
| email_validation_valid_count | Number of email validations that returned a valid result |
| email_validation_single_count | Number of single email validations performed |
| email_validation_bulk_count | Number of bulk email validations performed |
| email_validation_list_count | Number of email list validations performed |
| email_validation_mailgun_count | Number of email validations performed using Mailgun's validation service |
| email_validation_mailjet_count | Number of email validations performed using Mailjet's validation service |
| email_preview_count | Total number of email previews generated |
| email_preview_failed_count | Number of failed email preview generation attempts |
- US Mailgun
https://api.mailgun.net/v1/analytics/usage/metrics
- EU Mailgun
https://api.eu.mailgun.net/v1/analytics/usage/metrics
- 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/usage/metrics \
-H 'Content-Type: application/json' \
-d '{
"start": "Mon, 13 Nov 2023 20:56:50 -0600",
"end": "Wed, 20 Dec 2023 20:56:50 -0600",
"resolution": "month",
"duration": "1m",
"dimensions": [
"time"
],
"metrics": [
"accessibility_count",
"accessibility_failed_count",
"archived_count",
"domain_blocklist_monitoring_count",
"email_preview_count",
"email_preview_failed_count",
"email_validation_bulk_count",
"email_validation_count",
"email_validation_list_count",
"email_validation_mailgun_count",
"email_validation_mailjet_count",
"email_validation_public_count",
"email_validation_single_count",
"email_validation_valid_count",
"image_validation_count",
"image_validation_failed_count",
"ip_blocklist_monitoring_count",
"link_validation_count",
"link_validation_failed_count",
"processed_count",
"seed_test_count"
],
"filter": {
"AND": [
{
"attribute": "subaccount",
"comparator": "=",
"values": [
{
"label": "12345",
"value": "12345"
}
]
}
]
},
"include_subaccounts": true,
"include_aggregates": true
}'Response
application/json
{ "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "pagination": { "sort": "timestamp:asc", "skip": 1, "limit": 10, "total": 1000 }, "items": [ { … }, { … } ], "aggregates": { "metrics": {} } }
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
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