Domain Keys

An authentication standard used to prevent email spoofing.

List keys for all domains

get/v1/dkim/keys

List domain keys, and optionally filter by signing domain or selector. The page & limit data is only required when paging through the data.

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

signing_domain
string

Filter by signing domain

selector
string

Filter by selector

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


 
bits
integer
Key size, can be 1024 or 2048


 
pem
string
Private key PEM file


 
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": {
    • "cached": [ ],
    • "name": "s1._domainkey.example.com",
    • "record_type": "TXT",
    • "valid": "unknown",
    • "value": "k=rsa; p=<public_key>"
    }
}
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
{
  • "message": "domain key activated",
  • "authority": "authority.domain.tld",
  • "selector": "selector",
  • "active": true
}
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
{
  • "message": "domain key deactivated",
  • "authority": "authority.domain.tld",
  • "selector": "selector",
  • "active": true
}
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 domain name


 
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
{
  • "message": "string",
  • "sending_dns_records": [
    • {
      }
    ],
  • "changed": true
}
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 domain name


 
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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.