Postmark
Postmark API

Manage sending domains and their DKIM and Return-Path verification. Requires an account token.


List domains

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

Lists the sending domains on the account. Requires an account token.

List domains › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500.

offset
​integer · min: 0 · required

Number of records to skip.

List domains › Responses

A page of domains.

Paged list of domains.
TotalCount
​integer · required

Number of domains on the account.

Example: 2
​DomainSummary[] · required

Domains for the requested page.

Example: [{"Name":"example.com","SPFVerified":true,"DKIMVerified":true,"WeakDKIM":false,"ReturnPathDomainVerified":true,"ID":36735}]

Create a domain

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

Adds a sending domain to the account. Public email domains are not allowed (error code 503). Requires an account token.

Create a domain › Request Body

Domain to add.
Name
​string · maxLength: 255 · required

Domain name to add.

Example: example.com
ReturnPathDomain
​string

Custom Return-Path subdomain of the domain, with a CNAME pointing to pm.mtasv.net.

Example: pm-bounces.example.com

Create a domain › Responses

The created domain with the DNS records to configure.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Get a domain's details

GET
https://api.postmarkapp.com
/domains/{domainId}

Returns a domain with its DKIM and Return-Path verification details. Requires an account token.

Get a domain's details › path Parameters

domainId
​integer · required

Unique ID of the domain.

Get a domain's details › Responses

The domain.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Edit a domain

PUT
https://api.postmarkapp.com
/domains/{domainId}

Updates a domain's custom Return-Path. Requires an account token.

Edit a domain › path Parameters

domainId
​integer · required

Unique ID of the domain.

Edit a domain › Request Body

Domain settings to change. Field of `EditDomainRequest`.
ReturnPathDomain
​string

New custom Return-Path subdomain.

Example: pm-bounces.example.com

Edit a domain › Responses

The updated domain.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Delete a domain

DELETE
https://api.postmarkapp.com
/domains/{domainId}

Removes a domain from the account. Requires an account token.

Delete a domain › path Parameters

domainId
​integer · required

Unique ID of the domain.

Delete a domain › Responses

The domain was deleted.

Generic response returned by operations that only report a result code and message.
ErrorCode
​integer · required

Postmark API error code. 0 means the request succeeded. See the API error code table in the API description.

Example: 0
Message
​string · required

Human-readable result of the request.

Example: OK

Verify DKIM status

PUT
https://api.postmarkapp.com
/domains/{domainId}/VerifyDKIM

Checks DNS for the domain's DKIM record and updates its verification state. Check DKIMVerified in the response. Requires an account token.

Verify DKIM status › path Parameters

domainId
​integer · required

Unique ID of the domain.

Verify DKIM status › Responses

The domain with its refreshed DKIM state.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Verify Return-Path status

PUT
https://api.postmarkapp.com
/domains/{domainId}/VerifyReturnPath

Checks DNS for the domain's custom Return-Path CNAME and updates its verification state. Check ReturnPathDomainVerified in the response. Requires an account token.

Verify Return-Path status › path Parameters

domainId
​integer · required

Unique ID of the domain.

Verify Return-Path status › Responses

The domain with its refreshed Return-Path state.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Rotate DKIM keys

POST
https://api.postmarkapp.com
/domains/{domainId}/rotatedkim

Starts DKIM key rotation: a new key appears in the DKIMPending* fields until its DNS record is confirmed, then Postmark starts signing with it. Fails with error code 505 if a rotation is already in progress. Requires an account token.

Rotate DKIM keys › path Parameters

domainId
​integer · required

Unique ID of the domain.

Rotate DKIM keys › Responses

The domain with the pending DKIM key.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net

Verify a domain SPF record

POST
https://api.postmarkapp.com
/domains/{domainId}/verifyspf

Checks DNS for an SPF record that includes Postmark's servers. Postmark no longer requires SPF records, so this check is optional. Requires an account token.

Verify a domain SPF record › path Parameters

domainId
​integer · required

Unique ID of the domain.

Verify a domain SPF record › Responses

The domain with its refreshed SPF state.

A sending domain with its DNS verification details.
ID
​integer

Unique ID of the domain. Field of Domain.

Example: 36735
Name
​string

Domain name.

Example: example.com
SPFHost
​string

Host name for the optional SPF configuration.

Example: example.com
SPFTextValue
​string

Optional SPF TXT value.

Example: v=spf1 a mx include:spf.mtasv.net ~all
DKIMVerified
​boolean

Whether DKIM has ever been verified. Stays true even if the record is later removed from DNS.

Example: true
WeakDKIM
​boolean

true if the DKIM key is weaker than 1024 bit; rotate the key to upgrade it.

Example: false
DKIMHost
​string

DNS TXT host currently used to validate DKIM.

Example: 20260101000000pm._domainkey.example.com
DKIMTextValue
​string

DNS TXT value currently used to validate DKIM.

Example: k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...
DKIMPendingHost
​string

Pending DKIM TXT host not yet confirmed in DNS (after rotation or for a new domain).

Example:
DKIMPendingTextValue
​string

Pending DKIM TXT value not yet confirmed in DNS.

Example:
DKIMRevokedHost
​string

Revoked DKIM TXT host that will be removed.

Example:
DKIMRevokedTextValue
​string

Revoked DKIM TXT value that will be removed.

Example:
SafeToRemoveRevokedKeyFromDNS
​boolean

true when the old DKIM records can be safely deleted from DNS.

Example: false
DKIMUpdateStatus
​string

Pending while a new DKIM key is being set up or rotated, Verified once DNS is up to date.

Example: Verified
ReturnPathDomain
​string

Custom Return-Path domain.

Example: pm-bounces.example.com
ReturnPathDomainVerified
​boolean

Whether the Return-Path CNAME is verified and in use.

Example: true
ReturnPathDomainCNAMEValue
​string

CNAME value Postmark expects at the Return-Path domain.

Example: pm.mtasv.net