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

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

dkim_key_size
string

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

smtp_password
string

Password for SMTP authentication

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.

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.

wildcard
boolean

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

web_scheme
string

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

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.

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

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": [
    • {
      }
    ],
  • "message": "Domain DNS records have been created",
  • "sending_dns_records": [
    • {
      }
    ],
  • "domain": {
    • "createdat": "Thu, 13 Oct 2011 18:02:00 GMT",
    • "id": "123456789012345678901234",
    • "name": "example.com",
    • "type": "sandbox",
    • "wildcard": false,
    • "skipverification": false,
    • "state": "active",
    • "webprefix": "email",
    • "isdisabled": false,
    • "requiretls": true,
    • "smtppassword": "",
    • "spamaction": "disabled",
    • "webscheme": "http",
    • "smtplogin": "postmaster@example.com"
    }
}

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": {
    • "spamaction": "disabled",
    • "isdisabled": false,
    • "skipverification": false,
    • "smtplogin": "postmaster@example.com",
    • "smtppassword": "",
    • "wildcard": false,
    • "name": "example.com",
    • "requiretls": true,
    • "createdat": "Thu, 13 Oct 2011 18:02:00 GMT",
    • "webscheme": "http",
    • "type": "sandbox",
    • "webprefix": "email",
    • "id": "123456789012345678901234",
    • "state": "active"
    }
}

Update a domain

put/v4/domains/{name}

Update domains configuration like smtp, spam, 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
web_scheme
string

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

smtp_password
string

Updates the domain's SMTP credentials with the given string

wildcard
boolean

Updates the domain's wildcard status with the given boolean

spam_action
string

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

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": {
    • "requiretls": true,
    • "skipverification": false,
    • "spamaction": "disabled",
    • "webprefix": "email",
    • "id": "123456789012345678901234",
    • "isdisabled": false,
    • "wildcard": false,
    • "smtplogin": "postmaster@example.com",
    • "type": "sandbox",
    • "createdat": "Thu, 13 Oct 2011 18:02:00 GMT",
    • "smtppassword": "",
    • "webscheme": "http",
    • "name": "example.com",
    • "state": "active"
    }
}

Set verification state

put/v4/domains/{name}/verify

Verify domain DNS records and refresh them from the cache. (includes A, CNAME, SPF, DKIM and MX records)

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

Request samples
Response samples
application/json
{
  • "message": "Domain DNS records have been updated",
  • "receiving_dns_records": [
    • {
      }
    ],
  • "domain": {
    • "skipverification": false,
    • "spamaction": "disabled",
    • "wildcard": false,
    • "name": "example.com",
    • "requiretls": true,
    • "webscheme": "http",
    • "id": "123456789012345678901234",
    • "type": "sandbox",
    • "state": "unverified",
    • "webprefix": "email",
    • "disabled": {
      },
    • "createdat": "RFC1123 formatted date",
    • "smtplogin": "postmaster@example.com",
    • "isdisabled": false,
    • "smtppassword": ""
    },
  • "sending_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)

put/v3/domains/{name}/message_ttl

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 hostname

put/v3/domains/{name}/mailfrom_host

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 prefix

put/v3/domains/{name}/web_prefix

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