Domain Keys

An authentication standard used to prevent email spoofing.

List domain keys

get/v1/dkim/keys

List domain keys, and optionally filter by signing domain or selector.

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

Encoded paging information, provided via 'next', 'previous' links

limit
required
integer

Limits the number of items returned in a request

selector
string

Filter by selector

signing_domain
string

Filter by signing domain

Responses
200

A 200 response

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

A 401 response

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

Create a domain key

post/v1/dkim/keys

Create a domain key. Note that once private keys are created or imported they are never exported. Alternatively, you can import an existing PEM file containing a RSA private key in PKCS #1, ASn.1 DER format. Note, the pem can be passed as a file attachment or as a form-string parameter.

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

Signing domain to be used for the new domain key

selector
required
string

Selector to be used for the new domain key

pem
string

Private key PEM file

bits
integer

Key size, can be 1024 or 2048

Responses
200

A 200 response

Response Schema: application/json
signing_domain
required
string
selector
required
string
object
401

A 401 response

Request samples
Response samples
application/json
{
  • "signing_domain": "example.com",
  • "selector": "s1",
  • "dns_record": {
    • "priority": "",
    • "type": "TXT",
    • "valid": "unknown",
    • "value": "k=rsa; p=<public_key>",
    • "active": false,
    • "cached": [ ],
    • "name": "s1._domainkey.example.com"
    }
}

Delete a domain key

delete/v1/dkim/keys

Domain keys are not recoverable after deletion so use with care

SecuritybasicAuth
Request
query Parameters
signing_domain
required
string

Signing Domain

selector
required
string

Selector

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

401

A 401 response

404

A 404 response

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

Activate a domain key

put/v4/domains/{authority_name}/keys/{selector}/activate

Activate a key to be used to DKIM sign emails with. Note: dns records must be valid for a domain key to be activated

SecuritybasicAuth
Request
path Parameters
authority_name
required
string

The domain authority name you want to activate. Must be a valid domain

selector
required
string

The selector you want to activate for the domain key. Must be a valid dot atom

Responses
200

A 200 response

Response Schema: application/json
message
required
string
authority
required
string
selector
required
string
active
required
boolean
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "selector": "selector",
  • "message": "domain key activated",
  • "active": true,
  • "authority": "authority.domain.tld"
}

List domain keys

get/v4/domains/{authority_name}/keys

List all domain keys for your domain, including active/inactive and valid/invalid ones.

SecuritybasicAuth
Request
path Parameters
authority_name
required
string

The domain authority name you want to list the domain keys for. Must be a valid domain

Responses
200

A 200 response

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

A 401 response

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

Deactivate a domain key

put/v4/domains/{authority_name}/keys/{selector}/deactivate

Deactivating for a specified authority and/or selector means a key won't be used for signing email anymore, even if they are valid.

SecuritybasicAuth
Request
path Parameters
authority_name
required
string

The domain authority name you want to deactivate. Must be a valid domain

selector
required
string

The selector you want to deactivate for the domain key. Must be a valid dot atom

Responses
200

A 200 response

Response Schema: application/json
message
required
string
authority
required
string
selector
required
string
active
required
boolean
401

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "active": true,
  • "message": "domain key deactivated",
  • "authority": "authority.domain.tld",
  • "selector": "selector"
}

Update DKIM authority

put/v3/domains/{name}/dkim_authority

You can delegate the domain authority to an other domain. Domain's authority is set to itself by default.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want get sending queues from

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

Change the DKIM authority for a domain. 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.

Responses
200

A 200 response

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

A 401 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "changed": true,
  • "message": "string",
  • "sending_dns_records": [
    • {
      }
    ]
}

Update a DKIM selector

put/v3/domains/{name}/dkim_selector

Selector is the unique identifier of your key. It has to be different from other keys selector.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain you want get sending queues from

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

Update the dkim selector for a domain. If omitted no change is committed.

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 DKIM authority changed"
}