Postmark Outbound

Postmark Inbound

Message Retrieval

Stats API

Account API

Triggers API

Send Email with SMTP

You want to try Postmark out, but your application uses SMTP to send email? You can instantly switch your current email delivery without having to modify the application. This feature lets you use plain SMTP to send your messages and, to use it, you need to only change your configuration to point to the Postmark SMTP server.

Why do I need it?

Why have two API’s that seem to do the same thing? Well, we consider the REST API to be the most important one, and the SMTP access to be simply a way to ease migration from a regular SMTP server to Postmark. Quite often you have your web application delivering emails using SMTP and a migration to Postmark would require you to change your code. That comes with learning how to use one of the existing client libraries or, if you are unlucky, building one yourself. While our pre-built client libraries try to provide an interface that mimics SMTP client libraries or integrate seamlessly with existing email libraries, some coding and testing may still be required in order to integrate Postmark. 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 settings screen allows you to enable or disable SMTP access for a server. After enabling access, you will be able to connect to using your server API token as both a user name and password.

After enabling SMTP access, all SMTP email for your server will get collected and then routed to the Postmark mail queue. An incoming SMTP message is parsed to extract the originator, the recipients, the subject and other mail headers. It is then assembled as a normal Postmark message similar to the one needed by the REST API. When extracting the message body, we look for both “plain” messages and multipart (MIME) email. Looking at the message or MIME part Content-Type header we will automatically extract the text and HTML bodies if available. We do that by looking for content with the text/plain content type for plain text and text/html for HTML respectively. If we do not find at least one of those content type, we will not deliver the message.

If you can't use port 25 due to firewall issues, we offer an alternate port of 2525.

Connection details

The SMTP listener endpoint is available at at port 25 and 2525 (to get around firewall issues). We support both plain text authentication and CRAM-MD5. We recommend the latter as it is a lot more secure. CRAM-MD5 encrypts just the authentication process, but then the message content is still sent as plain text. You can encrypt the entire connection using TLS via the standard STARTTLS SMTP extension. STARTTLS is supported by the vast majority of mailers and some of them, like Ruby's ActionMailer automatically switch to encrypted communication when they detect that the server supports it.

Differences from the REST API

As mentioned above, the REST API is the primary API for the service and the SMTP endpoint is considered a migration route. The whole point of using SMTP access is to avoid changing your code. Once you are down to modifying code it is best to use the REST API.

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. That is why we recommend high-volume senders switch to the REST API eventually.

Another important difference between the two API’s is the way errors get handled. The REST API will immediately return an error if you provide illegal input data. The SMTP endpoint will accept all messages and log bounces for any errors it encounters.

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.

	X-PM-Tag: welcome-email

Open Tracking

You can enable open tracking for individual HTML messages or for all HTML messages with a particular Tag. For a single message, add the header X-PM-TrackOpens to your email and set it to true. If you set it to false Postmark will not add tracking to that email.

To track all opens for a specific Tag (for instance all of your Welcome emails), use our triggers endpoint. See Managing Triggers.

	X-PM-TrackOpens: true

Troubleshooting delivery 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 error code. The raw source will also contain the actual SMTP message. You are advised to monitor your bounces periodically or set up a bounce web hook that will alert you if SMTP delivery failed.

What should I do if my message is legitimate, but still was rejected?

Please contact support providing details on the error you are getting — best by pasting the entire bounce source containing both the error message and the message source.

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 in the Server settings screen.

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 mail clients. Occasionally there are combinations of clients and character sets that will not process correctly through Postmark, however. For example, 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.