Skip to content
/
List Mailgun API keys

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

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. 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

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

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

List Mailgun API keys

Request

List Mailgun API keys

Security
basicAuth
Query
domain_namestring

Domain name filter for domain keys

kindstring

Key kind filter

Enum ValueDescription
domain

Filter for domain keys

user

Filter for user keys

web

Filter for web keys

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/keys?domain_name=string&kind=domain'

Responses

A 200 response

Bodyapplication/json
total_countinteger(int32)required

The number of keys returned in 'items'

itemsArray of objects(github.com-mailgun-cerberus-keys-KeyInfoResp)required
items[].​idstringrequired

The ID for the key

items[].​descriptionstringrequired

The description provided for the key upon its creation

items[].​kindstringrequired

The type of the key which determines how it can be used

Enum ValueDescription
domain

Domain-specific API key for keys with 'sending' role

user

API key tied to a user role for RBAC limitations

web

Web session API key generated for user login sessions

items[].​rolestringrequired

The role of the key which determines its scope in CRUD operations that have role-based access control

Enum ValueDescription
admin

Provides admin-level permissions on an API key

basic

Provides basic aka analyst-level permissions on an API key

sending

Provides domain-scoped permissions on an API key for use only with 'domain' kind key

developer

Provides developer-level permissions on an API key

items[].​created_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$required

When the key was created in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
items[].​updated_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$required

When the key was last updated in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
items[].​expires_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

When the key will expire in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
items[].​disabled_reasonstring

The reason for the key's disablement if applicable

items[].​is_disabledbooleanrequired

Whether or not the key is disabled from use

items[].​domain_namestring or nullrequired
One of:

The sending domain associated with the key required for 'domain' kind keys

string

The sending domain associated with the key required for 'domain' kind keys

items[].​requestorstring or nullrequired
One of:

An email address associated with the key

string

An email address associated with the key

items[].​user_namestring or nullrequired
One of:

The API key user's name

string

The API key user's name

Response
application/json
{
  "total_count": 1,
  "items": [
    { … }
  ]
}

Create Mailgun API key

Request

Create Mailgun API key

Security
basicAuth
Bodymultipart/form-datarequired
domain_namestring

Web domain to associate with the key, for keys of 'domain' kind

kindstring

Type of API key ('domain', 'user', or 'web'). Defaults to 'user' if not provided. Note: web keys are not subject to IP allowlisting and have a default/maximum validity period of 1 day.

Enum ValueDescription
domain

Create API key of type 'domain'

user

Create API key of type 'user'

web

Create API key of type 'web'

descriptionstring

Key description

expirationinteger

Key lifetime in seconds, must be greater than 0 if set

rolestringrequired

Key role ('admin', 'basic' [use in place of analyst], 'sending' [use with keys of domain kind], or 'developer')

Enum ValueDescription
admin

Provides admin-level permissions on an API key

basic

Provides basic aka analyst-level permissions on an API key

sending

Provides domain-scoped permissions on an API key for use only with 'domain' kind key

developer

Provides developer-level permissions on an API key

user_idstring

API Key user's string user ID; should be provided for all keys of 'web' kind

user_namestring

API Key user's name

emailstring

API Key user's email address; should be provided for all keys of 'web' kind

curl -i -X POST \
  -u <username>:<password> \
  https://api.mailgun.net/v1/keys \
  -H 'Content-Type: multipart/form-data' \
  -F domain_name=string \
  -F kind=domain \
  -F description=string \
  -F expiration=0 \
  -F role=admin \
  -F user_id=string \
  -F user_name=string \
  -F email=string

Responses

A 200 response

Bodyapplication/json
messagestringrequired

Response message

keyobject(github.com-mailgun-cerberus-keys-KeyInfoSecretResp)required
key.​idstringrequired

The ID for the key

key.​descriptionstringrequired

The description provided for the key upon its creation

key.​kindstringrequired

The type of the key which determines how it can be used

Enum ValueDescription
domain

Domain-specific API key for keys with 'sending' role

user

API key tied to a user role for RBAC limitations

web

Web session API key generated for user login sessions

key.​rolestringrequired

The role of the key which determines its scope in CRUD operations that have role-based access control

Enum ValueDescription
admin

Provides admin-level permissions on an API key

basic

Provides basic aka analyst-level permissions on an API key

sending

Provides domain-scoped permissions on an API key for use only with 'domain' kind key

developer

Provides developer-level permissions on an API key

key.​created_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$required

When the key was created in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
key.​updated_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$required

When the key was last updated in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
key.​expires_atstring^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

When the key will expire in ISO 8601 date-time format without timezone offset (UTC time)

Example: "2026-01-23T10:16:00"
key.​disabled_reasonstring

The reason for the key's disablement if applicable

key.​is_disabledbooleanrequired

Whether or not the key is disabled from use

key.​domain_namestring or nullrequired
One of:

The sending domain associated with the key required for 'domain' kind keys

string

The sending domain associated with the key required for 'domain' kind keys

key.​requestorstring or nullrequired
One of:

An email address associated with the key

string

An email address associated with the key

key.​user_namestring or nullrequired
One of:

The API key user's name

string

The API key user's name

key.​secretstring(password)required

The full API key secret in plain text returned only once upon key creation

Response
application/json
{
  "message": "great success",
  "key": {
    "id": "f2153fd0-f1277777",
    "description": "api key",
    "kind": "domain",
    "role": "sending",
    "created_at": "2006-01-02T15:04:05",
    "updated_at": "2006-01-02T15:04:05",
    "requestor": null,
    "user_name": null,
    "domain_name": "example.com",
    "is_disabled": false,
    "secret": "api-key-be-careful"
  }
}

Delete Mailgun API key

Request

Delete Mailgun API key

Security
basicAuth
Path
key_idstringrequired

The Key ID generated by Mailgun on key creation

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/keys/{key_id}'

Responses

A 200 response

Bodyapplication/json
messagestringrequired

Response message

Response
application/json
{
  "message": "key deleted"
}

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