Postmark

Overview

Integration

User guide

API reference

Webhooks

Sending with SMTP

Aleady 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?

Just as the REST API uses a server’s API token to authenticate the client, SMTP access is also configured per server. The server credentials page allows you to enable or disable SMTP access for a server.

Enable Postmark SMTP access

After enabling access, you will be able to connect to smtp.postmarkapp.com using your server API token as both a user name and password. Our SMTP servers are now able to accept your messages and they will be routed to the Postmark mail queue.

Connection details

  • Server - smtp.postmarkapp.com
  • Ports - 25, 2525, or 587
  • Username/Password - Server API token
  • Authentication
    • Plain text
    • CRAM-MD5 - Encrypts just the authentication process, however the message content is still sent as plaint text.
    • TLS - Encrypts the entire connection via the standard STARTTLS SMTP extension.

Globally distributed SMTP servers

The SMTP servers that accept messages are globally distributed around the world. Since SMTP can be a chatty and slow protocol, we created multiple data centers in San Jose, Chicago, Virginia, Amsterdam and Singapore. Depending on your location you will be routed to the closest server for the fastest response times possible. For instance, if your application servers are in London, your messages will be automatically routed to our Amsterdam facility, resulting very low latency and faster performance for your application.

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.

Many client libraries for the REST API 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 features such as batch sending for improved performance when sending many emails. Overall, the REST API will have less overhead when your application conmmunicates with Postmark.

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 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 support in SMTP

Tags can be used in SMTP messges, 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. 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.

X-PM-Tag: welcome-email

Tracking opens

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

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 can’t I authenticate with the SMTP server?

Please make sure you are using your server API token as both the SMTP user name and password. Also verify that you have enabled SMTP access for your server on the server credentials page.

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

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

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.