Skip to content
/
List statistics, ordered...

Mailgun API (3.0.0)

Mailgun API defined by OpenAPI Specification (OAS) 3.1.0

Download OpenAPI description
mailgun.json
mailgun.yaml
Languages
Servers
US Mailgun

https://api.mailgun.net/

EU Mailgun

https://api.eu.mailgun.net/

Messages

Send email two ways via our REST API:

  1. Send emails using MIME format using a MIME building library
  2. Submit the individual parts (Text, html, attachments, etc.)

Reminder: You can also send email via SMTP with Mailgun. Please reference the user manual.

Operations

Domains

Domains API manages domains, domain keys and DNS verification.

Operations

Domain Keys

An authentication standard used to prevent email spoofing.

Operations

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

DKIM Security

Automatic Sender Security DKIM Key APIs. To enable this feature please see 'Update a domain' API docs.

Operations

Webhooks

Webhooks API manages domain's webhooks. You can create, access and delete webhooks programmatically.

Operations

Metrics

Mailgun collects many different events and generates event metrics which are available in your Control Panel. This data is also available via our analytics metrics API endpoint.

Operations

Logs

Mailgun keeps track of every inbound and outbound message event and stores this log data. This data can be queried and filtered to provide insights into the health of your email infrastructure.

Operations

Bounce Classification

Operations

List statistic v2

Request

Items that have no bounces and no delays(classified_failures_count==0) are not returned.

Security
basicAuth
Bodyapplication/jsonrequired
startobject

A start timestamp (default: 7 days before current time). Must be in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format

endobject

An end timestamp (default: current time). Must be in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format

resolutionobject
durationstring

A duration in the format of '48h' '60m' '30s'. If duration is provided then it is calculated from the end date and overwrites the start date.

dimensionsArray of strings(github.com-mailgun-bounce-classification-internal-api-Dimension)

Dimensions.

Items Enum ValueDescription
entity-name

Recipient Provider/Spam Filter, e.g. Gmail, Other US, Spamcop, etc.

domain.name

Sender domain name, e.g. example.com

envelope.sending-ip

Sending IP address

account.name

Subaccount name

envelope.i-ip-pool-name

IP Pool name

tags

Tags. Not compatible with tag dimension.

tag

Tag. Not compatible with tags dimension.

recipient-domain

Recipient domain, e.g. gmail.com

group-id

Group ID

criticality

Criticality, e.g. CRITICAL or NON-CRITICAL

metricsArray of strings

Metrics to return. See example.

filterobject

Filters to apply to the query.

include_subaccountsboolean

Include stats from all subaccounts.

paginationobject

Attributes used for pagination and sorting.

curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v2/bounce-classification/metrics \
  -H 'Content-Type: application/json' \
  -d '{
    "start": "Sun, 01 Jan 2006 22:04:05 UTC",
    "end": "Mon, 02 Jan 2006 22:04:05 UTC",
    "resolution": "day",
    "duration": "24h0m0s",
    "dimensions": [
      "entity-name",
      "domain.name"
    ],
    "metrics": [
      "critical_bounce_count",
      "non_critical_bounce_count",
      "critical_delay_count",
      "non_critical_delay_count",
      "delivered_smtp_count",
      "classified_failures_count",
      "critical_bounce_rate",
      "non_critical_bounce_rate",
      "critical_delay_rate",
      "non_critical_delay_rate"
    ],
    "filter": {
      "AND": [
        {
          "attribute": "domain.name",
          "comparator": "=",
          "values": [
            {
              "value": "example.com"
            }
          ]
        }
      ]
    },
    "include_subaccounts": true,
    "pagination": {
      "sort": "entity-name:asc",
      "limit": 10
    }
  }'

Responses

A 200 response

Bodyapplication/json
startstringrequired

A start timestamp in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format

endstringrequired

An end timestamp in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format

resolutionobjectrequired

'resolution' from the request

durationstring

'duration' from the request

dimensionsArray of strings(github.com-mailgun-bounce-classification-internal-api-Dimension)

'dimensions' from the request

Items Enum ValueDescription
entity-name

Recipient Provider/Spam Filter, e.g. Gmail, Other US, Spamcop, etc.

domain.name

Sender domain name, e.g. example.com

envelope.sending-ip

Sending IP address

account.name

Subaccount name

envelope.i-ip-pool-name

IP Pool name

tags

Tags. Not compatible with tag dimension.

tag

Tag. Not compatible with tags dimension.

recipient-domain

Recipient domain, e.g. gmail.com

group-id

Group ID

criticality

Criticality, e.g. CRITICAL or NON-CRITICAL

paginationobject(github.com-mailgun-bounce-classification-internal-api-PaginationResp)required
pagination.​sortstringrequired

'sort' from the request

pagination.​skipinteger(int64)required

'skip' from the request

pagination.​limitinteger(int64)required

'limit' from the request

pagination.​totalinteger(int64)required

The total number of items in the query result set.

itemsArray of github.com-mailgun-bounce-classification-entities-MetricsItem (object) or nullrequired
Any of:
items[].​account.idstring or null
items[].​account.namestring or null
items[].​entity-namestring or null
items[].​recipient-providerstring or null
items[].​recipient-domainstring or null
items[].​domain.namestring or null
items[].​envelope.i-ip-pool-idstring or null
items[].​envelope.i-ip-pool-namestring or null
items[].​envelope.sending-ipstring or null
items[].​timestampstring or null
items[].​tagsstring or null

Concatenated tags

items[].​tagstring or null
items[].​criticalitystring or null
items[].​severitystring or null
items[].​categorystring or null
items[].​group-idstring or null
items[].​sample-textstring or null
items[].​explanationstring or null
items[].​metricsobjectrequired

Counts and rates

items[].​metrics.​critical_bounce_countinteger(int64)required
items[].​metrics.​non_critical_bounce_countinteger(int64)required
items[].​metrics.​critical_delay_countinteger(int64)required
items[].​metrics.​non_critical_delay_countinteger(int64)required
items[].​metrics.​classified_failures_countinteger(int64)required

Total bounces and delays

items[].​metrics.​delivered_smtp_countinteger or null(int64)required

null for Spam Filters

items[].​metrics.​critical_bounce_rateinteger or null(int64)required

Percentages; null for Spam Filters

items[].​metrics.​non_critical_bounce_rateinteger or null(int64)required

Percentages; null for Spam Filters

items[].​metrics.​critical_delay_rateinteger or null(int64)required

Percentages; null for Spam Filters

items[].​metrics.​non_critical_delay_rateinteger or null(int64)required

Percentages; null for Spam Filters

Response
application/json
{
  "start": "Sun, 01 Jan 2006 22:04:05 +0000",
  "end": "Mon, 02 Jan 2006 22:04:05 +0000",
  "resolution": "day",
  "duration": "24h0m0s",
  "dimensions": [
    "entity-name",
    "domain.name"
  ],
  "pagination": {
    "sort": "entity-name:asc",
    "limit": 10,
    "total": 1
  },
  "items": [
    { … }
  ]
}

List statistics, ordered by total bouncesDeprecated

Request

Deprecated: use POST /v2/bounce-classification/metrics instead

Security
basicAuth
Query
groupstring

Group response by fields: subaccount.id, domain.name, entity-id, rule-id

limitinteger

Limits the number of items returned in a response

include_subaccountsboolean

Include subaccounts

Default false
curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/bounce-classification/stats?group=string&limit=0&include_subaccounts=false'

Responses

A 200 response

Bodyapplication/json
itemsArray of github.com-mailgun-bounce-classification-entities-Stat (object) or nullrequired
Any of:
items[].​subaccountgithub.com-mailgun-bounce-classification-entities-Subaccount (object) or null
Any of:
items[].​domaingithub.com-mailgun-bounce-classification-entities-Domain (object) or null
Any of:
items[].​rule-idstring
items[].​entity-idstring
items[].​short-explanationstring
items[].​bouncedobject(github.com-mailgun-bounce-classification-entities-BouncedStat)required
items[].​bounced.​totalinteger(int32)required
_durationstringrequired
Response
application/json
{
  "items": [
    { … }
  ],
  "_duration": "0s"
}

List domains statistic per accountDeprecated

Request

Deprecated: use POST /v2/bounce-classification/metrics

Security
basicAuth
Query
limitinteger

Limits the number of items returned in a response

skipinteger

Skips N items in a response

querystring

Query filter, e.g.: 'domain.name:example.com'

include_subaccountsboolean

Include subaccounts

Default false
curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/bounce-classification/domains?limit=0&skip=0&query=string&include_subaccounts=false'

Responses

A 200 response

Bodyapplication/json
itemsArray of github.com-mailgun-bounce-classification-entities-AccountStat (object) or nullrequired
Any of:
items[].​domainobject(github.com-mailgun-bounce-classification-entities-Domain)required
items[].​domain.​namestringrequired
items[].​bouncedobject(github.com-mailgun-bounce-classification-entities-BouncedStat)required
items[].​bounced.​totalinteger(int32)required
totalinteger or null(int32)
reqobject
Response
application/json
{
  "items": [
    { … }
  ],
  "total": 1
}

Tags New

Mailgun allows you to tag your email with unique identifiers. Tags are visible via our analytics tags API endpoint.

Operations

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

Tags

Mailgun lets you tag each outgoing message with a custom value. When you access stats on your messages, they will be aggregated by these tags.

WARNING: This API is deprecated in favor of our new Tags 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

Unsubscribe

Unsubscribe list stores email addresses of recipients who unsubscribed from your mailings by clicking a Mailgun generated unsubscribe link.

Operations

Complaints

Email addresses of recipients who marked your messages as a spam (for ESPs that support FBL).

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

Routes

Define a list of routes to handle incoming emails. When a message matches a route expression, Mailgun can forward it on to your application via HTTP or another email address, or store the message temporarily (3 days) for subsequent retrieval.

Operations

Mailing Lists

Programatically create mailing lists.

Operations

Templates

This API allows you to store predefined templates and use them to send messages using the Sending API.

Operations

IP Pools

IP Pools allow you to group your dedicated IPs into customized "pools" to help manage your sending reputation for different mail sending streams.

Operations

Dynamic IP Pools

Dynamic IP Pools allow you to group your dedicated IPs into customized "pools" based on sender reputation. Domains enrolled in Dynamic IP Pools will be assigned to a pool based on the result of periodic health checks.

Operations

IPs

The IP API endpoint allows you to access information regarding the IPs allocated to your Mailgun account that are used for outbound sending.

Operations

IP Address Warmup

Operations

Subaccounts

Mailgun supports the creation, modification, and deletion of subaccounts. A subaccount is a child account of a parent account. The parent account can have multiple subaccounts. The subaccounts are created and managed by the parent account.

Operations

Custom Message Limit

The custom message limit imposes a hard limit on how many messages your account can send during a calendar month.

Operations

Account Management

Perform account-level CRUD operations.

Operations

Keys

The Keys API lets you view and manage api keys.

Operations

Credentials

The Credentials API lets you view and manage SMTP credentials.

Operations

IP Allowlist

The IP Allowlist API lets you view and manage allowlisted IP addresses to which api key and SMTP credential usage is restricted.

Operations

Users

Mailgun API supports viewing user entities.

Operations