Overview

Integration

User guide

API reference

Webhooks

Managing sender signatures

Why use the sender signature API?

The email address that will appear as the from address is your sender signature. Postmark only allows you to send from email addresses that you’ve confirmed beforehand. The common case is to create one or two sender signatures using the Postmark website and that is sufficient for the life of the account. However, Postmark recognizes that this doesn’t work for all of our users. For example, if you want to send from a large number of addresses or if you want to dynamically create sender signatures, requiring a human to be part of the process isn’t feasible. That’s why we have a RESTful API for our customers to programmatically control sender signatures, under the /senders endpoint. For full details of this endpoint, please refer to the sender signatures API reference.

Creating a sender signature

Creating a sender signature should be pretty simple for those familiar with using APIs. The full API reference contains all the details. Below is a discussion of some important points.

Authentication

Sender signatures belong to an account. This is different from what you might be used to with sending emails, which belong to an individual server in Postmark. To manage your sender signatures, you will need an Account API token. Only accessible by the account owner, you can find this on the Account tab of your Postmark account. This token is used as the value for the X-Postmark-Account-Token HTTP header. This HTTP header should be used as the authentication method for all API requests for the /senders endpoint. If there is a problem with authentication, you will get an HTTP response with a status code of 401 (Unauthorized).

Required fields

There are only two pieces of information required to create a sender signature. FromEmail is the email address that will appear as the From address for emails you send out. It needs to be an email address that goes to a mailbox. Postmark will send a confirmation email that needs to be confirmed before you can use the sender signature. Also, it needs to be a private domain that you have access to. This is for two reasons. First, Postmark sending emails for a domain you don’t control, like Gmail or Yahoo, can be viewed as email spoofing. Yahoo has specifically published policies disallowing third parties to send email from a yahoo.com address. Secondly, you will need to modify DNS entries to add SPF and DKIM support, which are highly recommended to increase email deliverability.

The Name field is also required when creating a sender signature. This is what most email clients will display in the From field. While required to create the signature, it is also overridable on a per request basis. If you create a sender signature for "Nick <support@yourdomain.com>", you can also send email from "Joe <support@yourdomain.com>" without any additional setup on your part.

Response fields

The full list of response fields is located here, but below are the subset of fields that will help you further work with sender signatures.

  • The ID field is used if you want to edit or delete the signature later.
  • The SPFHost and SPFTextValue are the values used to set up SPF for the domain of your sender signature. SPFHost is the domain and SPFTextValue is the value that should be in the DNS TXT record.
  • The DKIMPendingHost and DKIMPendingTextValue are the values used to set up DKIM for the domain of your sender signature. DKIMPendingHost is the full sub-domain that your DKIM key should be placed at and DKIMPendingTextValue is the value that should be in the DNS TXT record. Once DKIM is verified, these values will migrate to DKIMHost and DKIMTextValue.

Fully manage the sender signature

Of course, creating the sender signature is just one part of a full workflow. Using the /senders API endpoint, you can list, edit, or delete your sender signatures. You can even resend your confirmation email, verify SPF, and request new DKIM keys.