Sender signatures API

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

List sender signatures Try → #

get

/senders

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 API Tokens tab of your Postmark account.

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"

Querystring parameters

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

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	string	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": "postmarkapp.com",
      "EmailAddress": "jp@postmarkapp.com",
      "ReplyToEmailAddress": "info@postmarkapp.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 → #

get

/senders/{signatureid}

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 API Tokens tab of your Postmark account.

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	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.
SPFVerified	boolean	deprecated See our blog post to learn why this field was deprecated.
SPFHost	string	Host name used for the SPF configuration.
SPFTextValue	string	Value that can be optionally setup with your DNS host. See our blog post to learn why this field is no longer necessary.
DKIMVerified	boolean	Specifies whether DKIM has ever been verified for the domain or not. Once DKIM is verified, this response will stay true, even if the record is later removed from DNS.
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	boolean	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 sender signature.
ConfirmationPersonalNote	string	The text of the personal note sent to the recipient.

Example response

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

{
  "Domain": "postmarkapp.com",
  "EmailAddress": "jp@postmarkapp.com",
  "ReplyToEmailAddress": "info@postmarkapp.com",
  "Name": "JP Toto",
  "Confirmed": true,
  "SPFVerified": true,
  "SPFHost": "postmarkapp.com",
  "SPFTextValue": "v=spf1 a mx include:spf.mtasv.net ~all",
  "DKIMVerified": false,
  "WeakDKIM": false,
  "DKIMHost": "jan2013.pm._domainkey.postmarkapp.com",
  "DKIMTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDJ...",
  "DKIMPendingHost": "20131031155228.pm._domainkey.postmarkapp.com",
  "DKIMPendingTextValue": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCFn...",
  "DKIMRevokedHost": "",
  "DKIMRevokedTextValue": "",
  "SafeToRemoveRevokedKeyFromDNS": false,
  "DKIMUpdateStatus": "Pending",
  "ReturnPathDomain": "pm-bounces.postmarkapp.com",
  "ReturnPathDomainVerified": false,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 36735,
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}

Create a signature Try → #

post

/senders

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 API Tokens tab of your Postmark account.

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",
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}'

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.
ConfirmationPersonalNote	string	Optional. A way to provide a note to the recipient of the confirmation email to have context of what Postmark is. Max length of 400 characters.

Example body format

{
  "FromEmail": "john.doe@example.com",
  "Name": "John Doe",
  "ReplyToEmail": "reply@example.com",
  "ReturnPathDomain": "pm-bounces.example.com",
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}

Response

Domain	string	Domain associated with sender signature.
EmailAddress	string	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.
SPFVerified	boolean	deprecated See our blog post to learn why this field was deprecated.
SPFHost	string	Host name used for the SPF configuration.
SPFTextValue	string	Value that can be optionally setup with your DNS host. See our blog post to learn why this field is no longer necessary.
DKIMVerified	boolean	Specifies whether DKIM has ever been verified for the domain or not. Once DKIM is verified, this response will stay true, even if the record is later removed from DNS.
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	boolean	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 sender signature.
ConfirmationPersonalNote	string	The text of the personal note sent to the recipient.

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": "pm-bounces.example.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 1,
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}

Edit a signature Try → #

put

/senders/{signatureid}

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 API Tokens tab of your Postmark account.

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": "pm-bounces.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.
ConfirmationPersonalNote	string	Optional. A way to provide a note to the recipient of the confirmation email to have context of what Postmark is. Max length of 400 characters.

Example body format

{
  "Name": "John Doe",
  "ReplyToEmail": "jane.doe@example.com",
  "ReturnPathDomain": "pm-bounces.example.com",
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}

Response

Domain	string	Domain associated with sender signature.
EmailAddress	string	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.
SPFVerified	boolean	deprecated See our blog post to learn why this field was deprecated.
SPFHost	string	Host name used for the SPF configuration.
SPFTextValue	string	Value that can be optionally setup with your DNS host. See our blog post to learn why this field is no longer necessary.
DKIMVerified	boolean	Specifies whether DKIM has ever been verified for the domain or not. Once DKIM is verified, this response will stay true, even if the record is later removed from DNS.
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	boolean	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 sender signature.
ConfirmationPersonalNote	string	The text of the personal note sent to the recipient.

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": "pm-bounces.example.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 1,
  "ConfirmationPersonalNote": "This is a note visible to the recipient to provide context of what Postmark is."
}

Delete a signature Try → #

delete

/senders/{signatureid}

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 API Tokens tab of your Postmark account.

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 → #

post

/senders/{signatureid}/resend

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 API Tokens tab of your Postmark account.

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 #

post

/senders/{signatureid}/verifyspf

deprecated This method has been deprecated. See our blog post for why we no longer ask for SPF records.

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 API Tokens tab of your Postmark account.

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 can be optionally setup with your DNS host. See our blog post to learn why this field is no longer necessary.
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": "pm-bounces.example.com",
  "ReturnPathDomainVerified": true,
  "ReturnPathDomainCNAMEValue": "pm.mtasv.net",
  "ID": 110396
}

Request a new DKIM Try → #

post

/senders/{signatureid}/requestnewdkim

Deprecated 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 DKIMPendingTextValueand 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 API Tokens tab of your Postmark account.

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."
}

Overview

Integration

User guide

API reference

Webhooks

Sender signatures API

List sender signatures Try → #

/senders

Request headers

Example request with curl

Querystring parameters

Response

Example response

Get a sender signature’s details Try → #

/senders/{signatureid}

Request headers

Example request with curl

Response

Example response

Create a signature Try → #

/senders

Request headers

Example request with curl

Body format

Example body format

Response

Example response

Edit a signature Try → #

/senders/{signatureid}

Request headers

Example request with curl

Body format

Example body format

Response

Example response

Delete a signature Try → #

/senders/{signatureid}

Request headers

Example request with curl

Response

Example response

Resend a confirmation Try → #

/senders/{signatureid}/resend

Request headers

Example request with curl

Response

Example response

Verify an SPF record #

/senders/{signatureid}/verifyspf

Request headers

Example request with curl

Response

Example response

Request a new DKIM Try → #

/senders/{signatureid}/requestnewdkim

Request headers

Example request with curl

Response

Example response