User guide

API reference


Sending email with SMTP

Already using SMTP in your application? You can instantly switch your current email delivery. This feature lets you use plain SMTP to send your messages and you only need to point to Postmark's SMTP server.

Why use SMTP instead of the API?

Quite often you have your web application delivering emails using SMTP and a migration to Postmark would require you to change your code. With SMTP access at your disposal, you can simply change a configuration setting in your application and instantly switch delivery to Postmark.

How does it work?

There are two ways that you can send with SMTP, depending on what your SMTP client offers. The only difference between them is the configuration.

An SMTP client is any web app/email client that allows you to configure/input SMTP details such as SMTP server, SMTP username, SMTP password, etc to allow you to send emails.​

Either use the API Token (which acts as both a username and password) and a Header which can be found by clicking on a server, then a message stream and then Settings. If a header is not specified, Postmark will send through the default transactional stream.

If you don't have an option to add a custom header during the SMTP send, you can instead use an SMTP Token. This can also be found by clicking on a server, then a message stream and then Settings. An SMTP Token consists of an Access Key (which acts as a username) and a Secret Key (which acts as a password). The Secret Key should be stored in a safe place since after it has been generated, it's no longer visible. If you need access to this again, you'll need to generate a new SMTP Token for authentication.

SMTP Tokens are unique for each message stream.

 You can separately enable or disable SMTP access for a server via the server's Settings page.

View SMTP configuration details
View SMTP configuration details

After enabling access, you will be able to connect to smtp.postmarkapp.com (for transactional messages) or smtp-broadcasts.postmarkapp.com (for broadcast messages).

Find out why it's important to make sure you're separating transactional from broadcast messages.

Connection details

  • Server - smtp.postmarkapp.com or smtp-broadcasts.postmarkapp.com
  • Ports - 25, 2525, or 587
  • TLS - TLS is available via the STARTTLS SMTP extension. This establishes an encrypted connection to our SMTP server, and all credentials and content are encrypted while they are transmitted to us. We recommend you use TLS if possible.
  • API Token and Header OR SMTP Token.
    • API Token and Header - The Server API Token acts as the username and password. Header - X-PM-MESSAGE-STREAM: {stream-id}. If left blank, Postmark will use the default `outbound` transactional stream.
    • SMTP Token - The Access Key acts as the username and the Secret Key acts as the password.
  • Token Authentication Methods
    • CRAM-MD5 - Protects just the authentication process, however the message content is still sent as plain text if TLS is not enabled.
    • DIGEST-MD5 - Protects just the authentication process, however the message content is still sent as plain text if TLS is not enabled.
    • PLAIN - When not combined with TLS, the username and password are sent in clear text. We do not recommend using this method without enabling TLS. However, some older SMTP clients may not support other authentication methods. Use with caution.
    • LOGIN - Similar to PLAIN method. We also make this available for compatibility with older SMTP clients. Use with caution.

Globally distributed SMTP servers

We maintain endpoints in several AWS Regions around the world. Depending on your location you will be routed to the closest endpoints to your servers for the fastest response times possible, resulting in very low latency.

Differences from the REST API

The REST API is the primary API for the service and the SMTP endpoint is considered a migration route. Using SMTP access avoids big changes to your code base, though this comes at the expense of some features only available or easier to use when sending via API:

  • Many Rest API client libraries offer advanced features such as retrying several times on network errors. That could help in cases where there is a temporary problem connecting to the Postmark servers. 
  • The API also offers batch sending for improved performance when sending many emails. 
  • Another important benefit of the REST API is response codes. The REST API will immediately return a success or error message to your application upon receiving a message. For instance, if a recipient is deactivated due to a hard bounce you will be notified when attempting to send a message. In addition, the response will provide a message-ID for tracking along with error codes to handle problems gracefully. The SMTP endpoint will accept all messages and log bounces for any errors it encounters, which are still accessible using our bounce webhooks or bounce API endpoint.
  • Tags can be used in SMTP messages, similar to the API. In order to use a tag for your message, you must include the tag in an SMTP header named X-PM-Tag. So your SMTP client must have the option to add this header. Most programming languages with SMTP modules include a method by which to add a custom tag to SMTP messages. Only one tag may be used per message. The maximum Tag size is 1000 characters.

Overall, the REST API will have less overhead when your application communicates with Postmark, even though it requires more integration work to get it started.

X-PM-Tag: welcome-email

Tracking opens

There are three ways that you can activate open tracking for your emails:

Tracking links

Link tracking can be enabled using several methods as outlined in the link tracking overview.

Metadata support

Metadata can be added to message sent using SMTP by adding an additional SMTP header. If you add an SMTP header that contains the prefix X-PM-Metadata-, it will be registered as a metadata field. For an example, here are the SMTP headers you would add to the message to register custom metadata values for color and client-id

X-PM-Metadata-color: blue
X-PM-Metadata-client-id: 12345

Read more about Metadata and its limitations.

Troubleshooting SMTP problems #

Due to the nature of the SMTP protocol it is not possible for us to return an error to the SMTP client when we find out something is wrong with the message. To work around that limitation we will log a special type of bounce – SMTPApiError. The bounce description will contain a short message containing an error description. Checking the bounce raw source will display a longer error message along with other details such as the error code. The raw source will also contain the actual SMTP message. You should monitor your bounces periodically or create a bounce webhook that will alert you if SMTP delivery failed.

Why are the Cc or Bcc recipients split off into a separate message from the To recipients?

The Postmark SMTP service may not be compatible with all SMTP clients. If the recipients are not submitted to Postmark in a single transaction, it can cause the recipients to be placed into separate messages. Specifically, this can occur when using a software client such as Gmail or Office 365 to generate the outbound emails.

Why can’t I authenticate with the SMTP server?

Please make sure you are using your transactional message stream's API token as both the SMTP user name and password. Also, verify that you have enabled SMTP access for your server in the message stream's settings page.

Why isn’t my custom Message-ID being sent through Postmark?

First, please note the difference between MessageID (which is generated by Postmark and cannot be changed), and Message-ID, which is the custom value you're able to set via an SMTP header. The Postmark MessageID will always be what is returned in the "MessageID" field in webhook event JSON, so that you can identify the Postmark message for subsequent API calls.

By default, Postmark will replace all Message-ID headers for outbound SMTP messages. However, it can be useful to preserve Message-ID values for some applications that rely on them. To ensure that Postmark does not replace your custom or original Message-ID header, include an additional header called X-PM-KeepID with a value of true. Postmark will then pass on any original Message-ID header for the message.

X-PM-KeepID: true

What else can I try when experiencing issues sending with SMTP?

  • Try using all available Ports (25, 2525, and 587) in your SMTP settings. Sometimes a Port can get congested and cause temporary issues, or be blocked by a specific ISP.
  • Ensure you're using your Server API token as both your Username and Password, and not your Account API Token.
  • Check your firewall and network to ensure they're not blocking any of our SMTP Endpoints.

Troubleshooting encodings & character sets

Postmark does its best to support all possible encodings, character sets, and email clients. Occasionally there are combinations of clients and character sets that will not process correctly through Postmark. For instance, Mozilla Thunderbird sends ISO-8859-2 character sets using a Content-Transfer-Encoding of “8bit” which does not add a proper BOM signature. As a result, some special characters may not be processed correctly through Postmark. We recommend using Quoted-Printable as it's widely compatible with mail processing systems.