Domains

Messages

Send email two ways via our REST API:

Send emails using MIME format using a MIME building library
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

Get domains

Request

Get the list of domains. Can be filtered by state or authority. Sorting is optional. The list is paginated and limited to 1000 items per page.

Security

basicAuth

Query

limitinteger

Max count of items. Max: 1000. Default: 100

skipinteger

Get the list of items starting at the nth element. Default: 0

statestring

Get only domains with a specific state. Can be either active, unverified or disabled.

sortstring

Valid sort options are name which defaults to asc order, name:asc, or name:desc. If sorting is not specified domains are returned in reverse creation date order.

authoritystring

Get only domains with a specific authority. If state is specified then only state filtering will be proceed

searchstring

Search domains by the given partial or complete name. Does not support wildcards

include_subaccountsboolean

Search on every domain that belongs to any subaccounts under this account. Default to false.

curl -i -X GET \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v4/domains?limit=0&skip=0&state=string&sort=string&authority=string&search=string&include_subaccounts=true'

Responses

A 200 response

Bodyapplication/json

total_countinteger(int32)required

Total number of domains

itemsArray of objects(github.com-mailgun-domains-client-golang-Domain)required

List of domains

items[].created_atstringrequired

Timestamp indicating when the domain was created in RFC1123 format

items[].idstringrequired

Unique identifier of the domain

items[].is_disabledbooleanrequired

Indicates whether the domain is currently disabled

items[].namestringrequired

Fully qualified domain name registered with Mailgun

items[].require_tlsbooleanrequired

If true Mailgun will only send messages over a TLS connection

items[].skip_verificationbooleanrequired

If true Mailgun will not verify the certificate and hostname when setting up a TLS connection

items[].smtp_loginstringrequired

SMTP login username for the domain

items[].smtp_passwordstring

Optional SMTP password for the domain used for SMTP authentication

items[].spam_actionstringrequired

Action to take when a message is flagged as spam. Options are disabled

items[].subaccount_idstring

The subaccount ID the domain belongs to. This field is only present if the domain is associated with a subaccount

items[].statestringrequired

Current verification status of the domain

items[].typestringrequired

Classification of the domain. Possible values are custom or sandbox

items[].tracking_hoststring

Custom tracking host for the domain used for tracking opens and clicks if configured

items[].use_automatic_sender_securitybooleanrequired

If true Mailgun manages DKIM key generation and DNS record configuration automatically

items[].web_prefixstringrequired

Subdomain prefix used for open and click tracking

items[].web_schemestringrequired

Protocol scheme used for tracking

items[].wildcardbooleanrequired

Indicates if the domain is a wildcard domain and can receive emails for any subdomain

items[].disabledgithub.com-mailgun-domains-client-golang-Disabled (object) or null

Optional field containing additional details about the domain's disabled status if applicable

Any of:

Optional field containing additional details about the domain's disabled status if applicable

items[].encrypt_incoming_messagebooleanrequired

If true incoming messages to this domain will be encrypted

items[].message_ttlinteger(int32)

Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan

Response

application/json

{
  "total_count": 1,
  "items": [
    { … }
  ]
}

Create a domain

Request

Creates a domain for sending emails

Security

basicAuth

Bodymultipart/form-datarequired

dkim_host_namestring

Set the DKIM host name for the domain that is being created. Note, the value must be a valid domain name, and can be the domain name being created, a subdomain of the domain being created, or the root domain. This parameter cannot be used in conjunction with force_dkim_authority or force_root_dkim_host.

dkim_key_sizestring

The size of the new domain's DKIM key. Shall be either 1024 or 2048.

dkim_selectorstring

Explicitly set the value of the DKIM selector for the domain being created. If the domain key does not already exist, one will be created. The selector must be a valid atom per RFC2822. e.g valid value foobar, invalid value foo.bar

https://datatracker.ietf.org/doc/html/rfc2822#section-3.2.4

encrypt_incoming_messageboolean

Enable encrypting incoming messages for the given domain. This cannot be altered via API after being set for security purposes. Reach out to Support to disable if necessary. Default to false

force_dkim_authorityboolean

If set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account. If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account. Default to false.

force_root_dkim_hostboolean

If set to true, the root domain will be the DKIM Host for the domain being created even if the root domain itself is not registered with Mailgun. The domain being created will still need to pass domain verification with valid spf records for the domain and valid DKIM record for the root domain. This does not effect the smtp mail-from host for the domain being created. The mail-from host will remain the domain name being created, not the root domain.

wildcardboolean

Determines whether the domain will accept email for sub-domains when sending messages. Default to false.

namestringrequired

The name of the new domain

pool_idstring

Requested IP Pool to be assigned to the domain at creation.

ipsstring

An optional, comma-separated list of IP addresses to be assigned to this domain. If not specified, all dedicated IP addresses on the account will be assigned. If the request cannot be fulfilled (e.g. a requested IP is not assigned to the account, etc), a 400 will be returned.

require_tlsboolean

If set to true, this requires messages for the domain only be sent over a TLS connection. If a TLS connection cannot be established, Mailgun will not deliver the message.

If set to false, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection.

The default value is false.

skip_verificationboolean

If set to true, the certificate and hostname will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery of a message.

If set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established.

The default value is false.

spam_actionstring

Disabled, block or tag. Default to disabled. If disabled, no spam filtering will occur for inbound messages.

If block, inbound spam messages will not be delivered.

If tag, inbound messages will be tagged with a spam header. See Spam Filter.

smtp_passwordstring

Password for SMTP authentication

use_automatic_sender_securityboolean

Enable Automatic Sender Security. This requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Defaults to false.

web_prefixstring

Sets your open, click and unsubscribe URLs domain name prefix. Links rewritten or added by Mailgun in your emails will look like <web_scheme>://<web_prefix>.<domain_name>/... Default to email

web_schemestring

Sets your open, click and unsubscribe URLs to use http or https. Value either http or https. Defaults to http. In order for https to work, you must have a valid cert created for your domain. See Domain Tracking for TLS cert generation.

message_ttlinteger

Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan.

curl -i -X POST \
  -u <username>:<password> \
  https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v4/domains \
  -H 'Content-Type: multipart/form-data' \
  -F dkim_host_name=string \
  -F dkim_key_size=string \
  -F dkim_selector=string \
  -F encrypt_incoming_message=true \
  -F force_dkim_authority=true \
  -F force_root_dkim_host=true \
  -F wildcard=true \
  -F name=string \
  -F pool_id=string \
  -F ips=string \
  -F require_tls=true \
  -F skip_verification=true \
  -F spam_action=string \
  -F smtp_password=string \
  -F use_automatic_sender_security=true \
  -F web_prefix=string \
  -F web_scheme=string \
  -F message_ttl=0

Responses

A 200 response

Bodyapplication/json

messagestringrequired

Response message

domaingithub.com-mailgun-domains-client-golang-Domain (object) or nullrequired

Details of the newly created domain

Any of:

Details of the newly created domain

domain.created_atstringrequired

Timestamp indicating when the domain was created in RFC1123 format

domain.idstringrequired

Unique identifier of the domain

domain.is_disabledbooleanrequired

Indicates whether the domain is currently disabled

domain.namestringrequired

Fully qualified domain name registered with Mailgun

domain.require_tlsbooleanrequired

If true Mailgun will only send messages over a TLS connection

domain.skip_verificationbooleanrequired

If true Mailgun will not verify the certificate and hostname when setting up a TLS connection

domain.smtp_loginstringrequired

SMTP login username for the domain

domain.smtp_passwordstring

Optional SMTP password for the domain used for SMTP authentication

domain.spam_actionstringrequired

Action to take when a message is flagged as spam. Options are disabled

domain.subaccount_idstring

The subaccount ID the domain belongs to. This field is only present if the domain is associated with a subaccount

domain.statestringrequired

Current verification status of the domain

domain.typestringrequired

Classification of the domain. Possible values are custom or sandbox

domain.tracking_hoststring

Custom tracking host for the domain used for tracking opens and clicks if configured

domain.use_automatic_sender_securitybooleanrequired

If true Mailgun manages DKIM key generation and DNS record configuration automatically

domain.web_prefixstringrequired

Subdomain prefix used for open and click tracking

domain.web_schemestringrequired

Protocol scheme used for tracking

domain.wildcardbooleanrequired

Indicates if the domain is a wildcard domain and can receive emails for any subdomain

domain.disabledgithub.com-mailgun-domains-client-golang-Disabled (object) or null

Optional field containing additional details about the domain's disabled status if applicable

Any of:

Optional field containing additional details about the domain's disabled status if applicable

domain.encrypt_incoming_messagebooleanrequired

If true incoming messages to this domain will be encrypted

domain.message_ttlinteger(int32)

Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan

receiving_dns_recordsArray of github.com-mailgun-domains-client-golang-Record (object) or nullrequired

List of DNS records required for receiving emails

Any of:

receiving_dns_records[].is_activebooleanrequired

Indicates whether the DNS record is currently active

receiving_dns_records[].cachedArray of stringsrequired

List of Mailguns cached values for the DNS record

receiving_dns_records[].namestring

Name of the DNS record if applicable

receiving_dns_records[].prioritystring

Priority value for MX DNS records

receiving_dns_records[].record_typestringrequired

Type of DNS record such as MX TXT or CNAME

receiving_dns_records[].validstringrequired

Indicates whether the DNS record is valid

receiving_dns_records[].valuestringrequired

Expected value of the DNS record

sending_dns_recordsArray of github.com-mailgun-domains-client-golang-Record (object) or nullrequired

List of DNS records required for sending emails

Any of:

sending_dns_records[].is_activebooleanrequired

Indicates whether the DNS record is currently active

sending_dns_records[].cachedArray of stringsrequired

List of Mailguns cached values for the DNS record

sending_dns_records[].namestring

Name of the DNS record if applicable

sending_dns_records[].prioritystring

Priority value for MX DNS records

sending_dns_records[].record_typestringrequired

Type of DNS record such as MX TXT or CNAME

sending_dns_records[].validstringrequired

Indicates whether the DNS record is valid

sending_dns_records[].valuestringrequired

Expected value of the DNS record

Response

application/json

{
  "message": "Domain DNS records have been created",
  "domain": {
    "created_at": "Thu, 13 Oct 2011 18:02:00 GMT",
    "id": "123456789012345678901234",
    "name": "example.com",
    "require_tls": true,
    "smtp_login": "postmaster@example.com",
    "spam_action": "disabled",
    "state": "active",
    "type": "sandbox",
    "use_automatic_sender_security": true,
    "web_prefix": "email",
    "web_scheme": "http",
    "encrypt_incoming_message": true,
    "message_ttl": 86400
  },
  "receiving_dns_records": [
    { … }
  ],
  "sending_dns_records": [
    { … }
  ]
}

Get domain details

Request

Fetches json representation of a domain that includes details about the domain's state and settings.

Security

basicAuth

Path

namestringrequired

The name of the domain you want to fetch

Query

h:extendedboolean

Default to false. If set to true, domain payload will include dkim_host, mailfrom_host and pod

h:with_dnsboolean

Default to true, domain payload will include sending and receiving dns records payload

curl -i -X GET \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v4/domains/{name}?h%3Aextended=true&h%3Awith_dns=true'

Responses

A 200 response

Bodyapplication/json

domaingithub.com-mailgun-domains-client-golang-Domain (object) or nullrequired

Domain details

Any of:

Domain details

domain.created_atstringrequired

Timestamp indicating when the domain was created in RFC1123 format

domain.idstringrequired

Unique identifier of the domain

domain.is_disabledbooleanrequired

Indicates whether the domain is currently disabled

domain.namestringrequired

Fully qualified domain name registered with Mailgun

domain.require_tlsbooleanrequired

If true Mailgun will only send messages over a TLS connection

domain.skip_verificationbooleanrequired

If true Mailgun will not verify the certificate and hostname when setting up a TLS connection

domain.smtp_loginstringrequired

SMTP login username for the domain

domain.smtp_passwordstring

Optional SMTP password for the domain used for SMTP authentication

domain.spam_actionstringrequired

Action to take when a message is flagged as spam. Options are disabled

domain.subaccount_idstring

The subaccount ID the domain belongs to. This field is only present if the domain is associated with a subaccount

domain.statestringrequired

Current verification status of the domain

domain.typestringrequired

Classification of the domain. Possible values are custom or sandbox

domain.tracking_hoststring

Custom tracking host for the domain used for tracking opens and clicks if configured

domain.use_automatic_sender_securitybooleanrequired

If true Mailgun manages DKIM key generation and DNS record configuration automatically

domain.web_prefixstringrequired

Subdomain prefix used for open and click tracking

domain.web_schemestringrequired

Protocol scheme used for tracking

domain.wildcardbooleanrequired

Indicates if the domain is a wildcard domain and can receive emails for any subdomain

domain.disabledgithub.com-mailgun-domains-client-golang-Disabled (object) or null

Optional field containing additional details about the domain's disabled status if applicable

Any of:

Optional field containing additional details about the domain's disabled status if applicable

domain.encrypt_incoming_messagebooleanrequired

If true incoming messages to this domain will be encrypted

domain.message_ttlinteger(int32)

Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan

receiving_dns_recordsArray of github.com-mailgun-domains-client-golang-Record (object) or null

List of DNS records required for receiving emails

sending_dns_recordsArray of github.com-mailgun-domains-client-golang-Record (object) or null

List of DNS records required for sending emails

Response

application/json

{
  "domain": {
    "created_at": "Thu, 13 Oct 2011 18:02:00 GMT",
    "id": "123456789012345678901234",
    "name": "example.com",
    "require_tls": true,
    "smtp_login": "postmaster@example.com",
    "spam_action": "disabled",
    "state": "active",
    "type": "sandbox",
    "use_automatic_sender_security": true,
    "web_prefix": "email",
    "web_scheme": "http"
  }
}

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

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

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. Health checks are performed on domains and assigned to the appropriate Dynamic Pool.

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

Mailgun API (0.0.0)

Messages

Domains

Get domains

Request

Responses

Was this helpful?

Create a domain

Request

Responses

Was this helpful?

Get domain details

Request

Responses

Was this helpful?

Domain Keys

Domain Tracking

DKIM Security

Webhooks

Metrics

Logs

Tags New

Stats

Tags

Events

Unsubscribe

Complaints

Bounces

Allowlist

Routes

Mailing Lists

Templates

IP Pools

Dynamic IP Pools

IPs

IP Address Warmup

Subaccounts

Custom Message Limit

Account Management

Keys

Credentials

IP Allowlist

Users