How do I manage domains using the API?

If you send from many domains or consistently have new domains you need to be able to send from, the Domains API is a huge time saver and something you will want to be making use of. Using the Domains API you can programmatically create domains in your Postmark account, see the DNS record information for verifying them for sending, and rotate a domain’s DKIM key. In this article we will go over some of the common uses of the Domains API so that you can start taking advantage of its powerful features.

Creating and Verifying a Domain

Using the Create a domain API call you can quickly get a new domain added to your Postmark account.

Method: POST

Endpoint: https://api.postmarkapp.com/domains/

Example Body:

{
  "Name": "domain.com",
  "ReturnPathDomain": "pm-bounces.domain.com"
}

Using the method, body, and endpoint shown above, you can create a new domain for sending from your Postmark account. Before being able to use it, you will first need to verify the domain using a DKIM record. The body returned from the Create a Domain call will include the new domain’s details and look like this:

{
  "Name": "domain.com",
  "SPFVerified": true,
  "SPFHost": "domain.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "",
  "DKIMTextValue": "",
  "DKIMPendingHost": "20131031155228pm._domainkey.domain.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCFn...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pm-bounces.domain.com",
  "ReturnPathDomainVerified": false,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 36737
}

Using the returned domain details for DKIM verification

The “DKIMPendingHost” and “DKIMPendingTextValue” can be used for retrieving and adding the DKIM record needed to verify the domain to the domain’s DNS. From this example above, the TXT record to add is 20131031155228pm._domainkeydomain.com with the value shown in the“DKIMPendingTextValue” field.

Using the returned domain details for Return-Path verification

The “ReturnPathDomain” and “ReturnPathDomainCNAMEValue” provide you with the information you need for setting up a custom return-path for the domain. Using those two fields in the above JSON tells me to place a CNAME record in the DNS for the domain at pm-bounces.domain.com with the value pm.mtasv.net.

If you have API access to the DNS records for the domain, you can use the above information to place the records for DKIM and Return-Path into the DNS programmatically, instead of having to log into the DNS provider’s UI each time you need to add DNS records for Return-Path and DKIM.

Rotating DKIM records

It is a best practice to occasionally rotate your DKIM key. With the Domains API, it is possible to set up a DKIM key rotation schedule and have new DKIM keys automatically generated periodically.

Method: POST

Endpoint: https://api.postmarkapp.com/domains/{domainid}/rotatedkim

No body is needed for this API call. It will return a body like the following:

{
  "Name": "domain.com",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "jan2013pm._domainkey.domain.com",<
  "DKIMTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...",
  "DKIMPendingHost": "20131031155228pm._domainkey.domain.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCFn...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ID": 36735
}

The "DKIMPendingHost" and "DKIMPendingTextValue" once again can be used to know what to use for the Hostname/Value for the new DKIM record. Your old DKIM record will still be used until we verify the new TXT record for DKIM is in the domain’s DNS.

The "SafeToRemoveRevokedKeyFromDNS" field tells you when it is safe to delete the old DKIM record from the domain’s DNS. You can set up your rotate DKIM key function to periodically check the domain’s details for whether it is safe to delete the old DKIM record from the domain’s DNS or not.

Deleting a Domain

If you send on behalf of your customers, you may need to remove their domain from Postmark in the unfortunate event they no longer need to use your service. You can make this an automatic part of the process of closing their account using the Delete a Domain API call.

Method: DELETE

Endpoint: https://api.postmarkapp.com/domains/{domainid}

No body is needed for this API call. It will return a body like the following:

{
  "ErrorCode": 0,
  "Message": "Domain domain removed."
}

Head over to the Postmark API Explorer to give some of these API calls a try right from your browser. Get in touch with us if any questions come up!