Overview

Integration

User guide

API reference

Webhooks

Sender signatures API

Lets you manage all of your sender signature details for a specific account.

List sender signatures Try →

Gets a list of sender signatures containing brief details associated with your account.

Request headers

Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.

Querystring parameters

count Required
Number of records to return per request. Max 500.
offset Required
Number of records to skip
get

/senders

Example request with curl

curl "https://api.postmarkapp.com/senders?count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Account-Token: account token"

Response

TotalCount integer Indicates how many sender signatures match the search criteria you specified. This can be more than what is fetched by a single call.
SenderSignatures array List of objects that each represent a sender signature.
Domain string Domain associated with sender signature.
EmailAddress array string of objects that each represent a sender signature.
ReplyToEmailAddress string Reply-To email associated with sender signature.
Name string From name of sender signature.
Confirmed boolean Indicates whether or not this sender signature has been confirmed.
ID integer Unique ID of sender signature.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "TotalCount": 2,
  "SenderSignatures": [
    {
      "Domain": "wildbit.com",
      "EmailAddress": "jp@wildbit.com",
      "ReplyToEmailAddress": "info@wildbit.com",
      "Name": "JP Toto",
      "Confirmed": true,
      "ID": 36735
    },
    {
      "Domain": "example.com",
      "EmailAddress": "jp@example.com",
      "ReplyToEmailAddress": "",
      "Name": "JP Toto",
      "Confirmed": true,
      "ID": 81605
    }
  ]
}

Get a sender signature’s details Try →

Gets all the details for a specific sender signature.

Request headers

Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
get

/senders/{signatureid}

Example request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Account-Token: account token"

Response

Domain string Domain associated with sender signature.
EmailAddress string Email address associated with sender signature.
ReplyToEmailAddress string Reply-To email associated with sender signature.
Name string From name of sender signature.
Confirmed boolean Indicates whether or not this sender signature has been confirmed.
SPFVerified boolean SPF DNS text record has been setup correctly at your domain registrar or DNS host.
SPFHost string Host name used for the SPF configuration.
SPFTextValue string Value that must be setup at your domain registrar or DNS host in order for SPF to function correctly.
DKIMVerified boolean DKIM DNS text record has been setup correctly at your domain registrar or DNS host.
WeakDKIM boolean DKIM is using a strength weaker than 1024 bit. If so, it’s possible to request a new DKIM using the RequestNewDKIM function below.
DKIMHost string DNS TXT host being used to validate messages sent in.
DKIMTextValue string DNS TXT value being used to validate messages sent in.
DKIMPendingHost string If a DKIM renewal has been intiated or this DKIM is from a new Sender Signature, this field will show the pending DKIM DNS TXT host which has yet to be setup and confirmed at your registrar or DNS host.
DKIMPendingTextValue string Similar to the DKIMPendingHost field, this will show the DNS TXT value waiting to be confirmed at your registrar or DNS host.
DKIMRevokedHost string Once a new DKIM has been confirmed at your registrar or DNS host, Postmark will revoke the old DKIM host in preparation for removing it permantly from the system.
DKIMRevokedTextValue string Similar to DKIMRevokedHost, this field will show the DNS TXT value that will soon be removed from the Postmark system.
SafeToRemoveRevokedKeyFromDNS boolean Indicates whether you may safely delete the old DKIM DNS TXT records at your registrar or DNS host. The new DKIM is now safely in use.
DKIMUpdateStatus string While DKIM renewal or new DKIM operations are being conducted or setup, this field will indicate Pending. After all DNS TXT records are up to date and any pending renewal operations are finished, it will indicate Verified.
ReturnPathDomain string The custom Return-Path domain for this signature. For more information about this field, please read our support page.
ReturnPathDomainVerified boolean The verification state of the Return-Path domain. Tells you if the Return-Path is actively being used or still needs further action to be used.
ReturnPathDomainCNAMEValue string The CNAME DNS record that Postmark expects to find at the ReturnPathDomain value.
ID integer Unique ID of the Sender Signature.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Domain": "wildbit.com",
  "EmailAddress": "jp@wildbit.com",
  "ReplyToEmailAddress": "info@wildbit.com",
  "Name": "JP Toto",
  "Confirmed": true,
  "SPFVerified": true,
  "SPFHost": "wildbit.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "jan2013.pm._domainkey.wildbit.com",
  "DKIMTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...",
  "DKIMPendingHost": "20131031155228.pm._domainkey.wildbit.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCFn...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pmbounces.wildbit.com",
  "ReturnPathDomainVerified": false,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 36735
}

Create a signature Try →

Request headers

Content-Type required
application/json
Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
post

/senders

Example request with curl

curl "https://api.postmarkapp.com/senders" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token" \
  -d "{FromEmail: 'john.doe@example.com', Name: 'John Doe', ReplyToEmail: 'reply@example.com'}"

Body format

FromEmail string Required
From email associated with sender signature.
Name string Required
From name associated with sender signature
ReplyToEmail string Override for reply-to address.
ReturnPathDomain string A custom value for the Return-Path domain. It is an optional field, but it must be a subdomain of your From Email domain and must have a CNAME record that points to pm.mtasv.net. For more information about this field, please read our support page.

Example body format

{
  "FromEmail": "john.doe@example.com",
  "Name": "John Doe",
  "ReplyToEmail": "reply@example.com",
  "ReturnPathDomain": "pmbounces.example.com"
}
						

Response

Domain string Domain associated with sender signature.
EmailAddress string Email address associated with sender signature.
ReplyToEmailAddress string Reply-To email associated with sender signature.
Name string From name of sender signature.
Confirmed boolean Indicates whether or not this sender signature has been confirmed.
SPFVerified boolean SPF DNS text record has been setup correctly at your domain registrar or DNS host.
SPFHost string Host name used for the SPF configuration.
SPFTextValue string Value that must be setup at your domain registrar or DNS host in order for SPF to function correctly.
DKIMVerified boolean DKIM DNS text record has been setup correctly at your domain registrar or DNS host.
WeakDKIM boolean DKIM is using a strength weaker than 1024 bit. If so, it’s possible to request a new DKIM using the RequestNewDKIM function below.
DKIMHost string DNS TXT host being used to validate messages sent in.
DKIMTextValue string DNS TXT value being used to validate messages sent in.
DKIMPendingHost string If a DKIM renewal has been intiated or this DKIM is from a new Sender Signature, this field will show the pending DKIM DNS TXT host which has yet to be setup and confirmed at your registrar or DNS host.
DKIMPendingTextValue string Similar to the DKIMPendingHost field, this will show the DNS TXT value waiting to be confirmed at your registrar or DNS host.
DKIMRevokedHost string Once a new DKIM has been confirmed at your registrar or DNS host, Postmark will revoke the old DKIM host in preparation for removing it permantly from the system.
DKIMRevokedTextValue string Similar to DKIMRevokedHost, this field will show the DNS TXT value that will soon be removed from the Postmark system.
SafeToRemoveRevokedKeyFromDNS boolean Indicates whether you may safely delete the old DKIM DNS TXT records at your registrar or DNS host. The new DKIM is now safely in use.
DKIMUpdateStatus string While DKIM renewal or new DKIM operations are being conducted or setup, this field will indicate Pending. After all DNS TXT records are up to date and any pending renewal operations are finished, it will indicate Verified.
ReturnPathDomain string The custom Return-Path domain for this signature. For more information about this field, please read our support page.
ReturnPathDomainVerified boolean The verification state of the Return-Path domain. Tells you if the Return-Path is actively being used or still needs further action to be used.
ReturnPathDomainCNAMEValue string The CNAME DNS record that Postmark expects to find at the ReturnPathDomain value.
ID integer Unique ID of the Sender Signature.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Domain": "example.com",
  "EmailAddress": "john.doe@example.com",
  "ReplyToEmailAddress": "reply@example.com",
  "Name": "John Doe",
  "Confirmed": false,
  "SPFVerified": false,
  "SPFHost": "example.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "",
  "DKIMTextValue": "",
  "DKIMPendingHost": "20140220130148.pm._domainkey.example.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCQ35xZciGB0g...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pmbounces.wildbit.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 1
}

Edit a signature Try →

Request headers

Content-Type required
application/json
Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
put

/senders/{signatureid}

Example request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token" \
  -d "{Name: 'Jane Doe', ReplyToEmail: 'jane.doe@example.com', ReturnPathDomain: 'pmbounces.example.com'}"

Body format

Name string Required
From name associated with sender signature.
ReplyToEmail string Override for reply-to address.
ReturnPathDomain string A custom value for the Return-Path domain. It is an optional field, but it must be a subdomain of your From Email domain and must have a CNAME record that points to pm.mtasv.net. For more information about this field, please read our support page.

Example body format

{
  "Name": "John Doe",
  "ReplyToEmail": "jane.doe@example.com",
  "ReturnPathDomain": "pmbounces.example.com"
}
						

Response

Domain string Domain associated with sender signature.
EmailAddress string Email address associated with sender signature.
ReplyToEmailAddress string Reply-To email associated with sender signature.
Name string From name of sender signature.
Confirmed boolean Indicates whether or not this sender signature has been confirmed.
SPFVerified boolean SPF DNS text record has been setup correctly at your domain registrar or DNS host.
SPFHost string Host name used for the SPF configuration.
SPFTextValue string Value that must be setup at your domain registrar or DNS host in order for SPF to function correctly.
DKIMVerified boolean DKIM DNS text record has been setup correctly at your domain registrar or DNS host.
WeakDKIM boolean DKIM is using a strength weaker than 1024 bit. If so, it’s possible to request a new DKIM using the RequestNewDKIM function below.
DKIMHost string DNS TXT host being used to validate messages sent in.
DKIMTextValue string DNS TXT value being used to validate messages sent in.
DKIMPendingHost string If a DKIM renewal has been intiated or this DKIM is from a new Sender Signature, this field will show the pending DKIM DNS TXT host which has yet to be setup and confirmed at your registrar or DNS host.
DKIMPendingTextValue string Similar to the DKIMPendingHost field, this will show the DNS TXT value waiting to be confirmed at your registrar or DNS host.
DKIMRevokedHost string Once a new DKIM has been confirmed at your registrar or DNS host, Postmark will revoke the old DKIM host in preparation for removing it permantly from the system.
DKIMRevokedTextValue string Similar to DKIMRevokedHost, this field will show the DNS TXT value that will soon be removed from the Postmark system.
SafeToRemoveRevokedKeyFromDNS boolean Indicates whether you may safely delete the old DKIM DNS TXT records at your registrar or DNS host. The new DKIM is now safely in use.
DKIMUpdateStatus string While DKIM renewal or new DKIM operations are being conducted or setup, this field will indicate Pending. After all DNS TXT records are up to date and any pending renewal operations are finished, it will indicate Verified.
ReturnPathDomain string The custom Return-Path domain for this signature. For more information about this field, please read our support page.
ReturnPathDomainVerified boolean The verification state of the Return-Path domain. Tells you if the Return-Path is actively being used or still needs further action to be used.
ReturnPathDomainCNAMEValue string The CNAME DNS record that Postmark expects to find at the ReturnPathDomain value.
ID integer Unique ID of the Sender Signature.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Domain": "example.com",
  "EmailAddress": "john.doe@example.com",
  "ReplyToEmailAddress": "jane.doe@example.com",
  "Name": "Jane Doe",
  "Confirmed": false,
  "SPFVerified": false,
  "SPFHost": "crazydomain.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "",
  "DKIMTextValue": "",
  "DKIMPendingHost": "20140220130148.pm._domainkey.crazydomain.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCQ35xZciGB0g...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pmbounces.example.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 1
}

Delete a signature Try →

Request headers

Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
delete

/senders/{signatureid}

Example Request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}" \
  -X DELETE \
  -H "Accept: application/json" \
  -H "X-Postmark-Account-Token: account token"

Response

ErrorCode integer API Error Codes
Message string Response message

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ErrorCode": 0,
  "Message": "Signature someone@example.com removed."
}

Resend a confirmation Try →

Request headers

Content-Type required
application/json
Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
post

/senders/{signatureid}/resend

Example request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}/resend" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token"

Response

ErrorCode integer API Error Codes
Message string Response message

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ErrorCode": 0,
  "Message": "Confirmation email for Sender Signature john.doe@example.com was re-sent."
}

Verify an SPF record Try →

This method has been deprecated. Please use the new Domains API for updated SPF methods.

Will query DNS for your domain and attempt to verify the SPF record contains the information for Postmark's servers.

Request headers

Content-Type required
application/json
Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
post

/senders/{signatureid}/verifyspf

Example request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}/verifyspf" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token"
						

Response

The SPFVerified field that is returned will indicate whether or not SPF validation was successful.

Domain string Domain associated with sender signature.
EmailAddress string Email address associated with sender signature.
ReplyToEmailAddress string Reply-To email associated with sender signature.
Name string From name of sender signature.
Confirmed boolean Indicates whether or not this sender signature has been confirmed.
SPFVerified boolean SPF DNS text record has been setup correctly at your domain registrar or DNS host.
SPFHost string Host name used for the SPF configuration.
SPFTextValue string Value that must be setup at your domain registrar or DNS host in order for SPF to function correctly.
DKIMVerified boolean DKIM DNS text record has been setup correctly at your domain registrar or DNS host.
WeakDKIM boolean DKIM is using a strength weaker than 1024 bit. If so, it’s possible to request a new DKIM using the RequestNewDKIM function below.
DKIMHost string DNS TXT host being used to validate messages sent in.
DKIMTextValue string DNS TXT value being used to validate messages sent in.
DKIMPendingHost string If a DKIM renewal has been intiated or this DKIM is from a new Sender Signature, this field will show the pending DKIM DNS TXT host which has yet to be setup and confirmed at your registrar or DNS host.
DKIMPendingTextValue string Similar to the DKIMPendingHost field, this will show the DNS TXT value waiting to be confirmed at your registrar or DNS host.
DKIMRevokedHost string Once a new DKIM has been confirmed at your registrar or DNS host, Postmark will revoke the old DKIM host in preparation for removing it permantly from the system.
DKIMRevokedTextValue string Similar to DKIMRevokedHost, this field will show the DNS TXT value that will soon be removed from the Postmark system.
SafeToRemoveRevokedKeyFromDNS boolean Indicates whether you may safely delete the old DKIM DNS TXT records at your registrar or DNS host. The new DKIM is now safely in use.
DKIMUpdateStatus string While DKIM renewal or new DKIM operations are being conducted or setup, this field will indicate Pending. After all DNS TXT records are up to date and any pending renewal operations are finished, it will indicate Verified.
ReturnPathDomain string The custom Return-Path domain for this signature. For more information about this field, please read our support page.
ReturnPathDomainVerified boolean The verification state of the Return-Path domain. Tells you if the Return-Path is actively being used or still needs further action to be used.
ReturnPathDomainCNAMEValue string The CNAME DNS record that Postmark expects to find at the ReturnPathDomain value.
ID integer Unique ID of the Sender Signature.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Domain": "example.com",
  "EmailAddress": "john.doe@example.com",
  "ReplyToEmailAddress": "",
  "Name": "John Doe",
  "Confirmed": false,
  "SPFVerified": false,
  "SPFHost": "example.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "",
  "DKIMTextValue": "",
  "DKIMPendingHost": "20140220130148.pm._domainkey.example.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCQ35xZciGB0gMm3876S...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pmbounces.example.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 110396
}

Request a new DKIM Try →

This method has been deprecated. Please use the new Domains API for updated DKIM methods.

Creates a new DKIM key to be created. Until the DNS entries are confirmed, the new values will be in the DKIMPendingHost and DKIMPendingTextValue fields. After the new DKIM value is verified in DNS, the pending values will migrate to DKIMTextValue and DKIMPendingTextValue and Postmark will begin to sign emails with the new DKIM key.

Request headers

Content-Type required
application/json
Accept required
application/json
X-Postmark-Account-Token required
This request requires account level privileges. Only accessible by the account owner, this token can be found on the Account tab of your Postmark account.
post

/senders/{signatureid}/requestnewdkim

Example request with curl

curl "https://api.postmarkapp.com/senders/{signatureid}/requestnewdkim" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token"

Response

ErrorCode integer API Error Codes
Message string Response message

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ErrorCode": 505,
  "Message": "This DKIM is already being renewed."
}