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

Get only 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

Get only 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

include_subaccounts
boolean

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

Responses
200

A 200 response

Response Schema: application/json
total_count
required
integer <int32>

Total number of domains

required
Array of objects

List of domains

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.


 
require_tls
boolean
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_verification
boolean
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_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
Response message


 
required
github.com-mailgun-domains-client-golang-Domain (object) or null
Details of the newly created domain


 
required
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for receiving emails


 
required
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for sending emails


 
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
github.com-mailgun-domains-client-golang-Domain (object) or null
Domain details


 
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for receiving emails


 
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for sending emails


 
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 domain
put/v4/domains/{name}
Update domain 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
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.


 
require_tls
boolean
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_verification
boolean
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.


 
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
This updates the web prefix used for a domain's tracking features.  Must be a valid atom. Nothing will be updated if omitted. 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.


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


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Success message


 
required
github.com-mailgun-domains-client-golang-Domain (object) or null
Domain object


 
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for receiving emails


 
Array of github.com-mailgun-domains-client-golang-Record (object) or null
 List of DNS records required for sending emails


 
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
Response message


 
required
github.com-mailgun-domains-client-golang-Domain (object) or null
Domain record information


 
required
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for sending emails


 
required
Array of github.com-mailgun-domains-client-golang-Record (object) or null
List of DNS records required for receiving emails


 
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": "Mon, 02 Jan 2006 15:04:05 MST",
    • "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
Response message


 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "Domain will be deleted in the background"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.