Skip to content
/
Create a domain

Create a domain

Request

Creates a domain for sending emails

Security
basicAuth
Bodymultipart/form-datarequired
archive_tostring

If set to a URL, then each successfully delivered message will be submitted in an HTTP POST request to the URL. The Content-Type of the POST requests is application/mime and the request body is exactly what the recipient SMTP server received.

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

Allows domain to accept inbound messages received on subdomains that have MX records pointed to Mailgun. Default is 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.

webhooks_redact_piiboolean

If set to true, Personally Identifiable Information (PII) will be redacted from the payload of any webhook posted for this domain

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://api.mailgun.net/v4/domains \
  -H 'Content-Type: multipart/form-data' \
  -F archive_to=string \
  -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 webhooks_redact_pii=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
Any of:

Details of the newly created domain

receiving_dns_recordsArray of anyrequired

List of DNS records required for receiving emails

sending_dns_recordsArray of anyrequired

List of DNS records required for sending emails

Response
{
  "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": [
    { … }
  ]
}