Skip to content
Mailgun Optimize/API Documentation/
/
Add Alert

Alerts (0.0.1)

Our alerting solution is centered around two concepts: events and channels. The occurrence of an event can be configured to trigger an alert. A channel describes the delivery method for an alert. Every configured alert consists of an event type / channel pair. This level of granularity allows alerting to be configured to your exact preference.

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

https://api.mailgun.net/

EU Mailgun

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

Domains

Operations

DMARC Reports

DMARC reporting provides valuable insights into your infrastructure, helping you identify potential issues like senders, misconfigured email servers, or phishing attempts.

Operations

Inbox Placement

Inbox Placement testing allows you to see the likely deliverability of your email campaigns.

Operations

Spam Traps Monitoring

Our spam trap monitoring service surfaces how much of your email is being sent to known spam traps.

Operations

Email Health Score

Operations

IP Blocklist Monitoring

Operations

Domain Blocklist Monitoring

Blocklist Monitoring enables you to keep an eye on your reputation. Monitor your domains against our curated list of blocklist providers to make sure you aren't being blocked.

Operations

Google Postmaster Tools

This API provides access to Google Postmaster data.

Operations

Microsoft SNDS

This API provides access to Microsoft SNDS data.

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"
}