Domains

Domains API manages domains, domain keys and DNS verification.

Get domains

get/v4/domains

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.

SecuritybasicAuth
Request
query Parameters
limit
integer

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

skip
integer

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

state
string

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

sort
string

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.

authority
string

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

search
string

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

Responses
200

A 200 response

Response Schema: application/json
total_count
required
integer <int32>
required
Array of objects
401

A 401 response

Request samples
Response samples
application/json
{
  • "total_count": 1,
  • "items": [
    • {
      }
    ]
}

Create a domain

post/v4/domains

Creates a domain for sending emails

SecuritybasicAuth
Request
Request Body schema: multipart/form-data
required
name
required
string

The name of the new domain

web_scheme
string

Sets your open, click and unsubscribe URLs to use http or https. Shall be either http or https. Default to http.

dkim_host_name
string

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_size
string

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

dkim_selector
string

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_message
boolean

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_authority
boolean

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_host
boolean

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.

wildcard
boolean

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

smtp_password
string

Password for SMTP authentication

use_automatic_sender_security
boolean

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

web_prefix
string

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

spam_action
string

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.

ips
string

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.

pool_id
string

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

Responses
200

A 200 response

Response Schema: application/json
message
required
string
required
object
required
Array of objects
required
Array of objects
401

A 401 response

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

Get domain details

get/v4/domains/{name}

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

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to fetch

query Parameters
h:extended
boolean

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

h:with_dns
boolean

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

Responses
200

A 200 response

Response Schema: application/json
required
object
Array of objects
Array of objects
401

A 401 response

404

A 404 response

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

Update a domain

put/v4/domains/{name}

Update domains configuration like smtp credentials, enable/disable automatic sender security, spam actions, wildcard, or tracking web scheme.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to update

Request Body schema: multipart/form-data
required
wildcard
boolean

Updates the domain's wildcard status with the given boolean

mailfrom_host
string

The hostname to update to. Must be in lower case

message_ttl
integer

Duration of the message retrieval TTL in seconds.

smtp_password
string

Updates the domain's SMTP credentials with the given string

spam_action
string

Updates the domain's spam action. Valid values are 'disabled', 'tag', and 'block'

use_automatic_sender_security
boolean

Enable or disable Automatic Sender Security. If enabled, requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Domain must be reverified after changing this field. Defaults to false

web_scheme
string

Updates the domain's web scheme. Either 'http' or 'https'

web_prefix
string

Web prefix to be used for tracking. Must be a valid atom. Nothing will be updated if omitted

Responses
200

A 200 response

Response Schema: application/json
message
required
string
required
object
Array of objects
Array of objects
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "receiving_dns_records": [
    • {
      }
    ],
  • "sending_dns_records": [
    • {
      }
    ],
  • "domain": {
    • "type": "sandbox",
    • "smtp_login": "postmaster@example.com",
    • "spam_action": "disabled",
    • "name": "example.com",
    • "require_tls": true,
    • "web_prefix": "email",
    • "web_scheme": "http",
    • "id": "123456789012345678901234",
    • "state": "active",
    • "use_automatic_sender_security": true,
    • "created_at": "Thu, 13 Oct 2011 18:02:00 GMT"
    }
}

Verify Domain

put/v4/domains/{name}/verify

Verify the domains DNS records (includes A, CNAME, SPF, DKIM and MX records) to ensure the domain is ready and able to send

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to verify

Responses
200

A 200 response

Response Schema: application/json
message
required
string
required
object
required
Array of objects
required
Array of objects
401

A 401 response

404

A 404 response

429

A 429 response

Request samples
Response samples
application/json
{
  • "message": "Domain DNS records have been updated",
  • "domain": {
    • "use_automatic_sender_security": true,
    • "id": "123456789012345678901234",
    • "spam_action": "disabled",
    • "type": "sandbox",
    • "web_prefix": "email",
    • "disabled": {
      },
    • "name": "example.com",
    • "require_tls": true,
    • "smtp_login": "postmaster@example.com",
    • "state": "unverified",
    • "web_scheme": "http",
    • "created_at": "RFC1123 formatted date"
    },
  • "sending_dns_records": [
    • {
      }
    ],
  • "receiving_dns_records": [
    • {
      }
    ]
}

Delete a domain

delete/v3/domains/{name}

The domain must not be disabled or used as an authority for an other domain. Sandbox domain can't be deleted.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain to delete

Responses
200

A 200 response

Response Schema: application/json
message
required
string
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Domain will be deleted on the background"
}

Update the message TTL (time to live)Deprecated

put/v3/domains/{name}/message_ttl

Deprecated: please use PUT /v4/domains/{name} instead.Set both incoming and outgoing message retrieval TTL. The max TTL depends on your plan

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to update

Request Body schema: multipart/form-data
required
message_ttl
integer

Duration of the message retrieval TTL in seconds.

Responses
200

A 200 response

Response Schema: application/json
required
object
required
object
400

A 400 response

401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Domain message TTL settings updated."
}

Update the mailfrom hostnameDeprecated

put/v3/domains/{name}/mailfrom_host

Deprecated: please use PUT /v4/domains/{name} instead.Update the MAILFROM hostname used by default for emails sent using the domain.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to update

Request Body schema: multipart/form-data
required
mailfrom_host
string

The hostname to update to. Must be in lower case

Responses
200

A 200 response

Response Schema: application/json
message
required
string
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "success"
}

Update domains web prefixDeprecated

put/v3/domains/{name}/web_prefix

Deprecated: please use PUT /v4/domains/{name} instead.This updates the web prefix used for a domain's tracking features. This impacts click, open, and unsubscribe tracking features. Note: Updating the web prefix for a domain will require also updating the domain's DNS to include the CNAME record to match.For example, if you set the web prefix to zed for the domain my-domain.com, the corresponding CNAME zed.my-domain.com will need to be created in your domain's dns zone.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want to update

Request Body schema: multipart/form-data
required
web_prefix
string

Web prefix to be used for tracking. Must be a valid atom. Nothing will be updated if omitted

Responses
200

A 200 response

Response Schema: application/json
message
required
string
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Domain web prefix updated"
}