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


 
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.


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


 
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.


 
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.


 
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


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


 
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
{
  • "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"
    },
  • "receiving_dns_records": [
    • {
      }
    ],
  • "sending_dns_records": [
    • {
      }
    ]
}
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": {
    • "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"
    }
}
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
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 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.


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


 
wildcard
boolean
Updates the domain's wildcard status with the given boolean


 
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
{
  • "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"
    },
  • "receiving_dns_records": [
    • {
      }
    ],
  • "sending_dns_records": [
    • {
      }
    ]
}
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": {
    • "created_at": "RFC1123 formatted date",
    • "id": "123456789012345678901234",
    • "name": "example.com",
    • "require_tls": true,
    • "smtp_login": "postmaster@example.com",
    • "spam_action": "disabled",
    • "state": "unverified",
    • "type": "sandbox",
    • "use_automatic_sender_security": true,
    • "web_prefix": "email",
    • "web_scheme": "http",
    • "disabled": {
      }
    },
  • "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 in 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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.