Skip to content
Mailgun Email API/
/Alerts

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

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

Domain Webhooks

Webhooks API to manage domain-specific webhooks. You can create, retrieve, update, and delete webhooks programmatically. When triggered, webhook URLs are deduplicated by event type, across account and domain levels to prevent redundant webhook sends.

Operations

Metrics

The Mailgun Metrics API provides programmatic access to detailed analytics data about your email sending activity. This API allows you to query, filter, and analyze email performance metrics to gain insights into deliverability, engagement, and overall sending health.

Operations

Logs

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

Operations

Bounce Classification

Operations

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

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

Alerts

Operations

List events

Request

The current list of events that you can chose to receive alerts for.

Security
basicAuth
curl -i -X GET \
  -u <username>:<password> \
  https://api.mailgun.net/v1/alerts/events

Responses

A 200 response

Bodyapplication/json
eventsArray of stringsrequired
Response
application/json
{
  "events": [
    "ip_listed",
    "ip_delisted"
  ]
}

Add Alert

Request

Use this endpoint to add new alert settings record. This service facilitates notifications (Webhook, Slack, or Email) for both Mailgun Optimize and Send Alert threshold breaches.

Webhooks

This section covers details around consuming alerts via webhooks. If you are familiar with Mailgun Send webhooks (which provide status updates on individual email deliveries), there is a lot of overlapping similarity, however, there are also a few minor nuances to account for.

Securing Webhooks

HMAC is used to verify the integrity as well as the authenticity of received webhooks. To verify the origin of a webhook:

  1. Encode the webhook’s entire POST request body with the HMAC algorithm (using your webhook signing key and SHA256 digest mode)
  2. Compare the resulting hexdigest to the signature provided in the POST request’s X-Sign header.

NOTE: If you’re consuming Mailgun Send webhooks, please note that your Mailgun Send webhook signing key differs from your Alerts webhook signing key. Your Alerts webhook signing keys, used for both Optimize and Send Alert products, are available within the Mailgun Alerts UI.

Webhook URL Validation

When adding or updating a webhook URL for alerts, we will ensure the endpoint is reachable by sending a GET request to the provided URL. If a 200 response is not returned from your endpoint, the request will be rejected and your alert setting will not be saved. We intentionally chose to send a GET request instead of a POST when validating URLs so that your webhook endpoint does not have to account for test requests.

Additionally, when a POST request is sent to your webhook URL, if a 2xx is not returned, we will attempt retries via an exponential backoff strategy for up to ~8 hours. If the max retry count is reached, the alert will be disabled and the related alert settings record’s disabled_at field will be populated.

Security
basicAuth
Bodyapplication/jsonrequired
event_typestringrequired

The type of event for which you would like to receive alerts.

channelstringrequired

The delivery method for the alert.

Enum ValueDescription
email

email

webhook

webhook

slack

Slack

settingsobjectrequired

The details pertaining to the specified channel. Please note that the contents of this object differ per channel type.

settings.​urlstring

For webhook channel.

settings.​emailsArray of strings

For email channel

settings.​channel_idsArray of strings

For slack channel

settings.​disabled_channel_idsobject

List of disabled Slack channels.

curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v1/alerts/settings/events \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "ip_listed",
    "channel": "webhook",
    "settings": {
      "url": "https://yourwebhookurl.com"
    }
  }'

Responses

A 200 response

Bodyapplication/json
idstring(uuid)

The unique identifier for the alert settings record.

event_typestringrequired

The event type that is alerted on. Check GET /v1/alerts/events for possible values.

channelstringrequired

The delivery channel for the alert.

Enum ValueDescription
email

email

webhook

webhook

slack

Slack

settingsobjectrequired

This object contains channel-specific settings.

settings.​urlstring

For webhook channel.

settings.​emailsArray of strings

For email channel

settings.​channel_idsArray of strings

For slack channel

settings.​disabled_channel_idsobject

List of disabled Slack channels.

disabled_atstring or null(date-time)

When present, the timestamp indicating when a webhook endpoint was disabled.

Response
application/json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "event_type": "ip_listed",
  "channel": "webhook",
  "settings": {
    "url": "https://yourwebhookurl.com"
  }
}

Update Alert

Request

Use this endpoint to update an existing alert setting record.

NOTE: When updating a webhook alert, we will ensure the endpoint is reachable by sending a GET request to the provided URL. If a 200 response is not returned, a 400 will be returned and the alert setting update will be rejected.

Security
basicAuth
Path
idstringrequired

The settings ID.

Bodyapplication/jsonrequired
event_typestringrequired

The type of event for which you would like to receive alerts.

channelstringrequired

The delivery method for the alert.

Enum ValueDescription
email

email

webhook

webhook

slack

Slack

settingsobjectrequired

The details pertaining to the specified channel. Please note that the contents of this object differ per channel type.

settings.​urlstring

For webhook channel.

settings.​emailsArray of strings

For email channel

settings.​channel_idsArray of strings

For slack channel

settings.​disabled_channel_idsobject

List of disabled Slack channels.

curl -i -X PUT \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/alerts/settings/events/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "ip_delisted",
    "channel": "email",
    "settings": {
      "emails": [
        "recipient-a@example.com",
        "recipient-b@example.com"
      ]
    }
  }'

Responses

A 200 response

Bodyapplication/json
messagestringrequired

Response message

Response
application/json
{
  "message": "settings updated"
}

Limits

Mailgun allows you to set limits on your subaccounts to help you manage usage and costs. You can create, update, retrieve, and delete limits for various pre-send features such as email previews and email validations.

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

Account Templates

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

Operations

Domain Templates

This API allows you to store predefined templates at the domain level 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