Email is not going anywhere. As much as we continue to add more and more communication methods to talk to each other every day, email remains a powerful medium to reach and connect with people. When it comes to businesses, there are two major types of emails. The first is transactional email, and the second is broadcast email (bulk/marketing). Broadcast emails are comprised primarily of messages sent outside of the core application user experience - things like a Terms of Service update, sale announcements or other promotional offers. They are usually sent to multiple recipients at once.
Meanwhile, transactional messages are things that support someone's interaction with and use of web-based software. They are typically unique since they are sent to a single recipient and of high-priority such as receipts, password reset emails, or sign-up confirmations. Because of the fact that recipients expect these emails, they tend to see much higher open rates and engagement when compared to broadcast emails. That context also makes transactional emails different in terms of the content customers want and expect from them.
You should think of application email as just another interface to your software, and it should receive all of the attention that you’d give to designing any other customer interaction.
As important as application email is to your business, it can be extremely difficult to set up and manage — especially if you want to make sure none of your emails go to customers’ spam folders. That’s why we built Postmark: to take the pain out of application email so that you can focus on your business.
At Postmark, we support and adhere to the highest-level of sending standards across the industry. That's why we run separate but parallel sending environments: Postmark users are able to classify their email based on how it's sent out using a feature called Message Streams. This lets us route email that's sent to multiple recipients at the same time separately from other types of email. We’re so confident about this claim that we expose our delivery and “Time To Inbox” statistics on our status page for everyone to see.
In this step-by-step manual we'll walk you through how to get up and running quickly and get the most value out of Postmark. We’ll cover all the major topics to make the most of our platform:
What parts of the Postmark platform are most relevant to how you will use email.
How to implement email sending from your app, including the decisions you need to make before you get started.
How to implement inbound processing so you can receive email responses and route them to the right place.
How to understand and improve your emails, and troubleshoot any issues that may come up.
What to do if you get stuck.
This manual will give you the information you need to make the right decisions about how you integrate email with your product. Postmark exists to make this as easy as possible, so if you have any questions or feedback on how we can make the service even better, please let us know. We’re listening.
What’s the best way for you to integrate with Postmark?#
Switch & forget with SMTP or integrate with our API
Email is a crucial tool for most companies, but the exact needs can differ from one app to the next. Postmark works well with various types of businesses who need to send transactional and broadcast messages, but how to set it up and get up and running can look different based on your specific needs. Whether you're an agency with clients who send their own messages, or running your own web application, Postmark can meet your needs.
We’ll cover the most common usages and features of Postmark that apply to each. Once you figure out which of these scenarios fits your needs the best, you can use our customized table of contents to review only the sections of this manual that are relevant to you.
Some businesses need reliable email delivery, but do not need to closely monitor those messages day to day. Postmark meets this need by offering SMTP integration. If you're already using SMTP in your application, switching over to Postmark is an almost instant change. SMTP is enabled by default so all you have to do is add the required credentials to your application to start sending.
If your business does not require all the bells and whistles of a sophisticated email delivery platform, this is the best option for you. One flick of a switch and you can rest easy knowing your emails are getting delivered to where they’re needed. For many Postmark customers, the original setup can be the only time they log in to their account. Once sending, you can return your focus to growing your business and let Postmark handle the email for you.
Other businesses require deep insight into the performance of their messages, and Postmark fits the bill nicely here as well. Our robust API allows developers to integrate Postmark directly into their application, retrieve and display relevant information where required, and be on top of the effectiveness of their transactional messages.
Postmark’s rich feature set will serve you well. Both SMTP and the API give you access to features like event tracking (delivery, opens, link clicks, client usage) and high-level aggregate data allow you to understand whether your messages are having the desired effect. However, the API lets you use advanced features such as batch sending, templates, response codes for successes/errors, and retrying sending an email several times if there are network errors.
And we’re not just fast at delivering emails: we excel at giving you great support. Our customer success team is always ready to jump in when needed and provide you with the help you need in the event of a question.
Need to receive email as well? Postmark’s support for inbound email is the best in the industry. We’ll get into all the details for outbound sending and inbound processing later in this manual.
For some businesses, you manage the email needs of your own clients. Design agencies are a great example of this. How can Postmark help you in this scenario?
First, your Postmark account is organized by “server” and "message stream". We recommend giving each of your clients their own server and within that server, you can create up to 10 message streams. This allows you to separate your clients in an organised way so that you can view email activity for each client separately and quickly pull statistics from our API per client. We'll also go over in a little more detail later on in this manual why we also encourage you to create message streams for all the different types of messages one client may be sending.
Second, with domain verification, setting up new clients and getting them sending is a breeze. Add a couple of DNS records and you can enable sending for an entire domain, including all its addresses. This means that, if your clients would like to, they can send email from their domains, not yours. You can read more about the different options for sending on behalf of your clients. It’s worth noting that you can also add domains and verify them via our API. For more on this, see our help doc How do I verify a domain?
Last, Postmark also includes templates to get you sending even faster. If you have clients with similar needs, our HTML and plain text templates can save you hours of coding. Fully responsive, well tested, and integrated right into your account, sending password resets, invoices, and many other common notification messages is a quick process. And you can modify templates to fit your client right in the Postmark web interface, previews included.
Last, but certainly not least, Postmark also works well for hobbyists and side projects. Thanks to our API and clear documentation, getting Postmark integrated with a new project is a couple of easy steps. You can remove email from the checklist and keep your focus on building your MVP.
And if the side project starts to get some traction, Postmark can grow with you. You can start with the basics, but the powerful aspects of a rich, reliable email delivery platform are there for you once you need it.
The best news? New customers can take advantage of our free developer plan, which provides you with 100 free emails per month. Testing out your new idea shouldn’t cost an arm and leg… and Postmark can help you off the ground without spending a cent.
Interested in how setting up an account and getting it running smoothly is different for each of these options? The checklist below should give you an idea of the different steps needed to fully set up Postmark based on your needs. Some of these steps are optional, and of course nothing prevents you from doing all of it, so just see this as a rough guideline to get you started.
Switch & Forget
Robust Platform
Multiple Customers
Side Projects
Sign up for an account
✔️
✔️
✔️
✔️
Decide if you need to send email (transactional/broadcasts), receive email (inbound), or both [see chapter 3]
✔️
✔️
✔️
✔️
Decide if you’re going to use SMTP or the API [see chapter 4]
Are you planning to send or receive emails, or both?
There are two parts to outbound email - transactional and broadcasts and you’ll notice we talk about them a lot in this manual, alongside inbound email. The difference is simple: Outbound is email you send from your app to your customers. Inbound allows you to process email your customers send to your app, and perform a variety of actions on it.
Chances are that if you’re evaluating Postmark, you’re doing it to integrate with our outbound services. You have an app that needs to send emails like sign-up confirmations, password resets, product updates, newsletters, etc. You came to the right place — that’s what we’re here for.
But we also want to make sure you know about our Inbound service because it makes interaction with your customers so much more seamless.
We have an entire section on Inbound later in the manual, but in short, Inbound processing allows you or your customers to send emails to Postmark, which we then process and deliver to you via a webhook in nicely formatted JSON.
This is useful if you’d like people to send or reply to your outbound emails, which can then be processed by and posted back to your application in lots of different ways.
If you have an app that involves customer interaction — such as comments or support tickets — Inbound could be really useful to you. A sample Inbound workflow could look something like this:
A user posts a comment on your site or app.
An email notification with the comment included is sent through Postmark to anyone subscribed to that item.
The users who received the comment notification clicks reply in their email client, and sends a message to a unique email address that forwards to Postmark Inbound.
The email is parsed by Postmark Inbound into a JSON document.
The JSON document is sent to a webhook URL for your web application.
The email reply shows up as a comment inside the app, as a reply to the original message.
Of course, you don’t have to use Inbound processing with your app, and it won’t be applicable to everyone. But it can be a powerful addition to your email workflow that makes your customers’ lives so much easier, since they wouldn’t have to leave their email inboxes to interact with your app.
With that as background, let’s get started with how to set up Outbound sending from your app.
Now that we’ve covered the different scenarios for which you might want to use Postmark, it’s time to get into some details. If you’re going to send email from your app, there are a few steps you need to take.
Step 1: Decide whether you want to use our API or SMTP
Step 2: Set up the address(es) or domain(s) you plan to send from
Step 3: Set up message streams for the different types of email you'll be sending
Step 4: Send a test email
Step 5: Integrate with your app
Step 6: Get the most out of sending with webhooks, sandbox testing, and templates
Let’s get started…
Step 1: Decide whether you should use API or SMTP #
The first decision you need to make before you start integrating with Postmark is whether to use SMTP or our REST API. Both approaches will get your email delivered, but there are pros and cons to using each method. Here’s a table to help you decide which approach is right for you.
Pros
Cons
API
Get access to the complete feature set that Postmark has to offer
Less overhead when your application communicates with Postmark
Response codes with MessageID for tracking and error codes if there was a problem with the API call
Official and Community Libraries for integration
Requires non-trivial code changes to your site/application
Code must be updated in the event our API is changed
SMTP
Avoid big changes to existing code
Easy to migrate — simply change a configuration setting in your application/site and instantly switch delivery to Postmark
Doesn’t have some advanced features (such as batch sending, templates, response codes for successes/errors, and retrying sending an email several times if there are network errors)
Once you’ve decided what the right approach is for your situation, it’s time to get sending.
Step 2: Set up the address(es) you plan to send from #
Once you’ve created your account, we’ll automatically create your first Server. Servers help you organize your emails by project, client, or environment. In that way, servers are like folders on your computer. Message streams help you to separate everything even more by allowing you to create streams for all the different types of messages you're sending.
Each Server has its own API Token used for sending emails and making Server-level API calls. Each Server also comes with its own open and link tracking settings and inbound email address used for inbound processing, which we will discuss later in the manual.
Within each Server, you can separate your Transactional and Broadcast traffic using Message Streams. Transactional Message Streams are for messages that are usually unique and triggered by a user action like a welcome email, password reset, or receipts. Broadcast Message Streams are for bulk messages that are sent to multiple recipients at once like announcements, newsletters, or other application emails.
You are now ready to set up the addresses you plan to send from. There are two ways to do this:
Add a Sender Signature to send from specific email addresses
Verify an entire domain for sending
We use Sender Signatures and Domain Verification to ensure you own the mailboxes you want to send from, as this helps prevent spam and abuse. These safeguards are one of the ways we maintain a great reputation with ISPs and are able to get your emails to the inbox reliably and quickly. You can have as many Sender Signatures and Verified Domains as you need, there is no limit.
Note that when you first create your account you’ll be asked to create a Sender Signature with a specific email first, and you’ll be able to verify the entire domain later on. This keeps things simple as you get going. Once you’ve set this up, you can proceed to sending your first email, or optionally, verify the domain. Later, you can add more servers, proceed with Domain Verification, or add more Sender Signatures via the web or the Postmark API.
If you are going through the initial setup process, you will be prompted to create a Sender Signature after creating your account. Once you’ve gone through the initial setup process, you can click on Sender Signatures in the app navigation and then Add Domain or Signature to create a new Sender Signature.
Select Add Sender Signature and fill in the details for From email address, From name (optional), Reply To email address (optional), and Personal Note (optional).
The Personal note is a field to
provide context to the recipient of what the confirmation email is for.
This field is helpful if you're sending on behalf of a customer that
might not know you're using Postmark for email, and is available via our
API or UI when adding a Sender Signature.
Once you add a Sender Signature, a confirmation email will be sent automatically from Postmark to the email address you added. The Sender Signature confirmation emails will look like the example below:
Once you activate a Sender Signature, you should also set up authentication for the domain, which will improve your email delivery, as well as automatically verify your domain. If you proceed with Domain Verification, you will not need to add any more Sender Signatures for that domain since the entire domain will be authorized for sending through Postmark. This will also eliminate any further confirmation emails from needing to be sent.
Domain Verification will allow you to send from any email address on a particular domain. For example, once you have verified mydomain.com as a domain, you can send emails using the Postmark platform with any @mydomain.com email address. This feature is especially useful if you send from a large amount of email addresses in a single domain or send email on behalf of your customers.
Add Domain Verification for a new domain
Log into Postmark and navigate to the Sender Signatures tab. Click Add Domain or Signature.
Next, click Add Domain
Type in the domain you are adding, and then click Verify Domain.
You will then see generated DKIM and Return-Path records for this domain. Keep in mind that only the DKIM record needs to be added to your DNS in order to verify the domain you just added to your Postmark account.
Add the DKIM record as type TXT to your DNS, with the Host and Value that was generated. Once the DKIM record is added, it can take up to 48 hours for the DNS changes to propagate, so it can be a little while before DKIM shows as verified in Postmark. Click the Verify button in the DKIM row to run a manual check for it. Once DKIM is verified, you can immediately begin sending from any email address on the domain. You will also see a green checkmark next to the domain in your Sender Signatures tab.
Add Domain Verification for an existing Sender Signature
If you have already verified DKIM for a Sender Signature and the DKIM record is unique for your account (the domain and DKIM record is not shared across multiple Postmark accounts), the domain will be verified automatically. If you don’t have that set up already, it’s easy to do so.
Navigate to your Sender Signatures tab. Under the domain you are adding Domain Verification for, click ‘DNS Settings’ or 'Add a DKIM DNS record'.
Add the DKIM record shown as type TXT to your DNS, with the Host and Value that was generated. Once the DKIM record is added, it can take up to 48 hours for the DNS changes to propagate, so it can be a little while before DKIM shows as verified in Postmark. Once you have verified DKIM for the domain, you are all set to begin sending from any email address on the domain.
A note on DMARC
When you’re on the Authentication page, you might notice the section at the bottom labeled “Set up DMARC.” This is an optional step to set up DMARC on your domain. DMARC (Domain-based Message Authentication, Reporting & Conformance) is a standard that prevents spammers from using your domain to send email without your permission — also known as spoofing.
Spammers can forge the “From” address on messages so the spam appears to come from a user in your domain. A good example of this is PayPal spoofing, where a spammer sends an email to you pretending to be PayPal in an effort to obtain your account information. DMARC ensures these emails get blocked before you even see them in your inbox. In addition, DMARC gives you great visibility and reports into who is sending email on behalf of your domain, ensuring only legitimate email is received.
We discuss DMARC and how to set it up in detail later on in the manual, but if you’d like to find out more about it now, while you’re already busy with your DNS entries, you can skip ahead to that section.
Let's jump into why message streams are important and how you can create and use them. We'd encourage you to make message streams for all the different types of messages you're sending. This will give you a much better understanding into how each type of message is performing since all the stats and alerts for each message stream are separate.
This is also a useful approach in regards to recipients unsubscribing. If a recipient would like to unsubscribe from your newsletters stream, for example, this won't affect their ability to receive something like a Terms of Service update from another stream.
Another point I'd like to touch on is the importance of using a subdomain for your broadcast messages. We recommend that you send your high engagement transactional emails from the root domain and then use a subdomain for all marketing and bulk email. This follows best practices for separating email reputation as recommended by inbox providers like Gmail.
This way, your transactional messages won't be impacted by the deliverability and engagement of your bulk type messages, and vice versa. By not keeping these reputations separate, any low or negative engagement from a bulk send could affect the deliverability of those vital transactional messages.
Now that you have a confirmed Sender Signature (and possibly a verified domain) to send from, let’s move on to sending your first email! There are several methods that can be used to send through Postmark. Let’s go through some of the options for sending a test email.
Postmark API Explorer
Using the Postmark API Explorer you can quickly enter in your Server API Token and construct a valid JSON body for executing your first API call to send an email from within your web browser. The API Explorer shows you the request and response format, so it’s a great resource for testing out any calls to our APIs.
Postman
Postman is a free tool for testing out API calls from a UI. You can create API calls, save them to collections, and view API responses. You can download a Postman collection containing an example API call to send an email here. You can then import this collection, add in your Server API Token, From, and To email address to send your first email through the Postmark API using Postman.
cURL
If cURL is available on your machine, you can send a test email using this command in Terminal:
Just add in your Postmark Server API Token for the X-Postmark-Server-Token header, a verified email address you can send from for the From field, and a recipient email address where you can receive the test email for the To field.
Now that you’ve sent a test email, you’re ready to integrate Postmark with your app. This is where things get a little technical and beyond the scope of this manual. For in-depth details and documentation, head over to our developer docs for instructions on Sending with API and Sending with SMTP. We also have a bunch of official libraries and community libraries to make the integration process as easy as possible.
Step 6: Get the most out of sending with Sandbox mode, webhooks, templates, metadata, and DMARC policies (Optional)#
Once you’ve set up your app the most important part is done — you are now reliably sending emails to your customers from your app. But Postmark’s power doesn’t end there. There are a lot more features — especially if you use the API — that can help you send better email and serve your customers better.
Sandbox mode allows you to safely test out different parts of Postmark without accidentally sending email to real recipients. This helps you integrate Postmark with your CI processes, learn how our API works, experiment with webhooks, and more—all in a safe space that’s designed for testing and experimentation.
Along with Sandbox mode, Postmark allows you to generate fake bounces. This will let you see how a bounce appears in Postmark’s UI, test our Bounces API and Bounces webhooks, all without having to email test@example.com and worry that your sending reputation may be affected. We go over both of these features in more detail.
Postmark provides webhooks for bounces, inbound messages, clicks, and open tracking events in the form of HTTP POSTs of well formatted JSON to the URL(s) you specify in your Postmark Server’s settings. Using these webhooks you can receive notifications and data in real-time, as the triggering events occur, without having to make any calls to our API to check for a new event.
There are many ways you can make use of our webhooks, such as:
Receive real-time notifications when a bounce or spam complaint occurs
Notify senders after receiving a hard bounce or spam complaint
Let your customers know when their email address is bouncing
Receive and process inbound emails
Receive a notification when an email is delivered and/or opened, including open tracking data (GeoLocation, IP Address, Operating System, Email client, etc…)
Receive a notification when a link is clicked
The following are some examples of how webhooks can be used to help you get the most out of the Postmark platform.
Bounce & Spam Complaint Notifications
Using our Bounce webhook you can receive POSTs to your webhook URL for bounces every time a bounce event occurs. The JSON format for bounce and spam complaint notifications is:
{
"RecordType": "Bounce",
"MessageStream": "outbound",
"ID": 4323372036854775807,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Test",
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"ServerID": 23,
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "Test bounce details",
"Email": "john@example.com",
"From": "sender@example.com",
"BouncedAt": "2019-11-05T16:33:54.9070259Z",
"DumpAvailable": true,
"Inactive": true,
"CanActivate": true,
"Subject": "Test subject",
"Content": "<Full dump of bounce>"
}
Using the received JSON, you can quickly locate the email that triggered the notification (using the MessageID JSON key), check if the recipient can be reactivated (using the CanActivate key), and find out additional details around why the email bounced (using the Description and Detailskeys). We include the From field so you can quickly find out who the sender was and alert them a bounce occurred. What data interests you and how you use it is depends on your use case, but Postmark can help you get what you need.
One popular application of the bounce webhook is to send an email alert every time you receive a bounce. Once a new bounce notification arrives at your bounce webhook URL, you can construct an email with the data to send to the email address(es) of parties who want to be aware of bounces. To generate the notification email(s), you can use our Email API or SMTP for sending. Odds are if you are already sending using Postmark, you can leverage your existing integration to also send email alerts when bounces occur.
The bounce notification can also be used to mark a user or email address in your application as bouncing and provide your users with a way to reactivate the address manually using our Bounce API. Want to only receive an email if the bounce is a hard bounce? Check the Type key for a value of “HardBounce”.
The Rebound JavaScript snippet (once installed on your website) will tap into the Postmark API to check for hard bounces and prompt your customers to update their email address if they've experienced deliverability issues in the past.
Delivery Tracking
Once Postmark receives back a successful response from a receiving mail server, the email is considered delivered. Note that this means the receiving mail server accepted the email but may perform additional processing on it before delivering it to the final recipient. Postmark does not have access to the additional events that occur after the receiving mail server possesses the email, since those are internal to the receiving email server.
Delivery webhooks let you receive an event when this occurs for an email you sent that includes the receiving mail server’s response and details. Receiving delivery notifications in real time lets you update your application and/or database to show the events and let your user’s know the email was successfully delivered.
The ServerId field tells you which Server in Postmark the email was sent from. Using theMessageID, you can grab the email’s details (subject, sender, HTML body, etc…) with the Messages API. With the Recipient field you can tell who the email was sent to. If you added a Tag to the email when you sent it, you can get that back with the Tag field. DeliveredAt gives you the timestamp of when we received confirmation from the receiving mail server that they accepted the email. Details provides you with the response message from the receiving mail server.
Some common use cases of the delivery webhook include:
Feeding delivery events into a variety of internal systems to trigger additional actions on your end (such as update user information in your CRM)
Provide delivery events directly to your customers through a custom UI
Aggregate delivery events to calculate when there are delivery slowdowns and set thresholds to take action (such as switching to a backup service)
The open tracking webhook will push messages to you when an email is opened and contains information such as the location, email client, and OS environment of the person who opened the email. Open tracking will need to be enabled for the email or server and can only be applied to HTML emails. We have a section later in this manual all about Open Tracking.
You can choose to only receive notifications when an email is opened for the first time or every time an email is opened by enabling or disabling the setting “Post only on first open” in the webhook section of your Stream in Postmark.
Open tracking notifications will be pushed to your URL in the following format:
You can use the data for your opens to determine which type of mail clients and operating systems your recipients use most, and tailor your emails to best suit those environments. You can also use these notifications to alert your users when important emails are opened or display the open date and time for them in a CRM or support case management application.
For more detail on how to make Webhooks work in your app, including testing and security measures, have a look at our blog post, Putting webhooks to work.
The click tracking webhook will push messages to you when a link in an email is clicked. Click tracking webhook events contain information such as the location of the recipient when they clicked the email, what URL was clicked, whether the clicked link was in the Text or HTML part of the email, email client, and OS environment of the person who clicked the link. Link tracking will need to be enabled for the email or server and can be applied to both Text and HTML email parts.
Click tracking notifications will be pushed to your URL in the following format:
The spam complaint webhook will push messages to you when an email you send is manually marked as spam by a recipient. Use this webhook to be aware of a spam complaint registered by a recipient of yours. You should not be getting many spam complaints, so this is a good webhook to use to make sure you get alerted if one of your recipients believes an email you sent is spam. A common use case would be to automatically alert your sender that an email they sent was marked as spam, so they can bar that address from any further sending outside of Postmark.
Spam complaint notifications will be pushed to your URL in the following format:
The Subscription Change webhook is triggered when an email address is added or removed from a Message Stream's Suppression list. These event notifications are specific to the following subscription changes: Hard bounces, spam complaints, and manual suppressions.
This webhook can be useful to keep track of Suppressions, especially if you need to sync them to your own list. Additionally, you can use this webhook instead of the bounce and spam complaints webhooks to receive notifications of inactive addresses.
Subscription Change notifications will be pushed to your URL in the following format:
If you are using or planning on using the API for sending, templates allow for you to repeatedly use an HTML/CSS layout while only having to pass up the dynamic data (user name, company name, etc…) for the email in your API call. Templates are great for welcome emails, password resets, notifications - essentially any transactional email type that you will send multiple times. Sending using a template is only available when sending with our API so if you are using SMTP instead, this section will not apply to you.
Templates are unique to each Postmark Server. This means if you are separating your customers or use cases by server, templates will also be naturally separated with the same criteria. You can also duplicate a single template to another Postmark server in your account or keep all templates in sync between servers using the templates push feature.
Let’s walk through the process of choosing and customizing a starter template.
Using a starter template
Choose the template you’d like to use
Navigate into one of your Postmark Servers, and click on Templates. For this example, we're going to walk you though using our Welcome starter template. Welcome emails are often sent by sites/applications immediately after someone signs up and a good application for using Templates.
Preview your template
Since Postmark's templates can involve sending dynamic data, we've made it easier for you to preview your template with Postmark's test variable editor. Start by editing the JSON variables and the preview will update automatically.
Please note that any changes you make to the test variables will reset each time you exit the editor page. Test variables are not saved with a template since they're solely for test purposes.
Edit your template
If you need to make any changes to your template click on the Edit tab. Here you'll be able to edit the HTML and Text versions of your email.
You might notice that Postmark's starter templates include the CSS in a style block in the head of the email, instead of inline with the content like most email clients prefer. This is because Postmark will automatically inline those styles when the email is delivered. This makes it easier for you to edit while still bringing all the benefits and reliability of inlining.
We're also using our very own templating syntax called Mustachio. This originally has its roots with Mustache, but includes a few advanced features that make the language even more powerful. Check out the Mustachio Wiki for a quick how-to on syntax usage.
Send a test email
Once everything looks good you'll want to see how your template renders in an actual email client. Click 'Send a test email' to send a test email using your current test variables, to an email address of your choice.
You can even send test emails to other services like Litmus, or Email on Acid, which let you preview your template in every major email client. We've done the work to ensure that our starter templates look beautiful out-of-the-box, but if you modify these templates you should send a test email to make sure everything still looks great.
Integration into your app
Click on API Snippets and you can grab some code to get started.
Instead of using an if/else like syntax, the way you choose what to render is based on whether a value is present in a model, or absent ("truthy" or "falsey"). So, let's take a simple case and show how you can both render content when a value is present, and when it is absent:
(Make special note of the {{ . }} syntax to reference name and {{ ../job_title }} to "move up" a level in the scope.)
Now, let's have a look at what the output is for a few different models:
Here's an example where name is present:
Model:
{ "name" : "Alice", "job_title" : "CEO"}
Result:
Dear Alice
Here's an example where name is absent:
Model:
{ "job_title" : "CEO"}
Result:
Dear CEO
name may also be false or null and will produce the same result as when absent:
Model:
{ "name" : null, "job_title" : "CEO"}
Result:
Dear CEO
Including HTML in variables
For safety, Mustachio automatically HTML encodes the values that it interpolates. You may come across a situation where you need to pass HTML into the rendered content via the Template Model.There are two syntax options for when you need to include HTML passed into a variable.
{{& variable_name }}
or
{{{ variable_name }}}
Both of these will allow for passing HTML into the template, bypassing the default behavior.
If you're using one of our official API libraries, they will include the ability to send emails using a Template.
Using our Postmark API Explorer, you can send your first email using a template directly from your web browser here. Just enter in the variables and your Server API Token to send your first email using a template.
If you would like to send with a template using cURL, you can use this command:
Replace server token with your server API token from the server that the template you want to use belongs to. You will also need to replace 1234 with the Template ID, which can be found in the top right of the template in the Postmark UI. You can also use the template's alias instead of the Template ID, if you have set an alias for the template.
The important field that is specific to using a template is the TemplateModel field. This field is where you can pass in data to populate the variables you placed in your template. For an example, here is some JSON for sending with the Invoice template we start you with, that shows populating the TemplateModel:
This API call results in the following email when received by the recipient:
Sending batches of emails that use templates
You can send up to 500 templated emails with a single API call using the batch API endpoint. The JSON body to be used differs slightly when using the batch endpoint, which is shown below.
Attachments are included with templated sends in the same way as non-templated sends. Add the attachment information, including base64 bytes, to the "Attachments" field in the JSON body. The "Attachments" field must always be an array, even when only one attachment is included.
Each outbound Postmark message can be up to 10 MB in size. If a large attachment needs to be included, we recommend using a CDN to host the file, and providing a link to download the large file instead of attaching it directly to the message.
Keeping your templates in sync across multiple servers
Postmark has a couple features to help you easily copy templates from one server to another, allowing you to keep templates in sync across development, staging, and production servers.
Duplicating a single template to another server
Open the template you want to duplicate. Next to the Save button, click the dropdown arrow and then select Duplicate. Enter the template name and select the server you want to copy the template to, then click Duplicate. You can then open the copied template or return to the original template.
Push all templates from one server to another using the UI
Open the server containing the templates you want to push to another server and head to the Templates page.
Click the Push to another server button.
Select the destination server you want to push the template(s) to.
You will then see a list of the templates heading to the destination server, along with whether they will be created for the first time (+ icon) or will update an existing template (pencil icon).
Click the Preview button if you want to preview the changes.
Click Push now to complete the push of the templates to the destination server.
Push all templates from one server to another using the API Use this option for programmatically keeping your templates in sync across multiple environments or giving your users a way to sync template changes from your own UI.
Layouts let you generate reusable code for Templates in Postmark. Layouts are perfect for wrapping your email Templates with reusable CSS styles, headers, and footers.
Previously, if your Templates shared common CSS elements, or headers and footers, the code for each Template needed to be managed independently. With Layouts, your receipts, welcome emails, and password reset can share common elements. Each individual Template only contains the content of the email, while the reusable content is shared with the chosen Layout.
Using Layouts
To give you a head start, Postmark comes with a few starter Layouts. The adventurous can also code their own Layout from scratch.
Adding a Layout
Navigate to one of your Postmark Servers, and select Templates.
Choose Layouts then Add layout.
Postmark will show our built-in starter layouts. For this example, we’ll choose Basic.
After selecting the layout, it’s added. You’re now ready to create a beautiful Layout for your Templates.
Editing Layouts
After adding your layout, it’s a snap to edit it using Postmark’s editor. In the editor, you can add or edit the HTML and CSS, then see a live preview. Like Postmark’s starter Templates, the starter Layouts include CSS in a style block in the head of the email, instead of inline with the content like most email clients prefer. Postmark will automatically inline those styles when the email is delivered. This makes it easier for you to edit while still bringing all the benefits and reliability of inlining.
To indicate where your template content will go, use the content placeholder:
{{{ @content }}}
A single content placeholder is required to save a layout. By default, the content placeholder is added to the starter Layouts.
Associating Templates with a Layout
New or existing Templates can use Layouts. Add a Layout to a new Template:
When adding the new Template, there’s an option to use the Template with an existing Layout. Or you can add a Layout when creating the Template.
Use a Layout with an existing Template:
When viewing an existing Template within Postmark’s editor, there is an option to associate the Template with a Layout.
Add a new layout will automatically add a basic layout to the template and associates it to your Template.
After selecting a Layout, choosing Preview will show the Template content as it will appear with the Layout. This lets you see how your Template will look when sending an email. If you have multiple Layouts, you can also switchbetween Layouts to see how the Template content would appear in different Layouts.
Want to edit a Layout quickly? While viewing the different Layouts you can select a Layout to open in a new window, and edit it. Refreshing theTemplate page will let you see any Layout changes when previewing.
Templates inherit a Layout’s variables
When sending email using a Template, the variables from the Layout are available when using the template model API parameter.
For example, if product_name is a variable from the Layout, when sending a message with the API, the Template can pass product_name in its Template model.
How to view which Templates are using a Layout
Navigate to one of your Postmark Servers, and select Templates.
Choose Layouts.
When viewing the Layouts, its listed which Templates are using it.
MailMason is a toolset for building and maintaining transactional email Templates. With MailMason you can use Grunt tasks, Handlebars, and SASS to streamline building a consistent set of transactional email templates using layouts and partials to reduce redundancy and create both the HTML and plain text versions of your transactional emails in one fell swoop. Head over to the MailMason Wiki for help getting started.
MailMason includes the following example Templates to help you get started:
Example A base template designed only to showcase the available elements in the emails and to make it easy to test all of the styles from a single email.
Welcome A traditional welcome email when someone new creates an account on your service.
User Invitation A modified version of the welcome email that's designed when one of your existing users invites a new user, who may not be familiar with your product, to join the product and collaborate.
When you need to add custom information to your emails that you don't want seen by your recipients, Postmark's custom metadata feature has you covered. Metadata can be added to emails sent using both the Postmark API and SMTP services. The metadata you add to an email is returned in webhook events, Messages API calls, and shown in the UI. When searching for messages with the Messages API, you can even filter based on metadata values.
Message details metadata example
For more information, including the limits of the metadata feature, see the Custom metadata FAQ.
DMARC (Domain-based Message Authentication, Reporting & Conformance) is a standard that prevents spammers from using your domain to send email without your permission — also known as spoofing. Spammers can forge the From address on messages so the spam appears to come from a user in your domain. A good example of this is PayPal spoofing, where a spammer sends an email to you pretending to be PayPal in an effort to obtain your account information. DMARC ensures these emails get blocked before you even see them in your inbox. In addition, DMARC gives you great visibility and reports into who is sending email on behalf of your domain, ensuring only legitimate email is received.
How does DMARC work?
DMARC utilizes SPF and DKIM authentication to tell receivers whether the email is legitimate or not. In order to pass DMARC alignment, the email must pass either DKIM or SPF, but not both. If the email sent does not pass DMARC it will be rejected, quarantined, or still delivered, depending on the policy you set with your DMARC record. Emails that pass DMARC alignment will always be accepted by receiving mail servers.
The requirement for passing SPF with DMARC is also more strict. You may have a correct SPF record that passes SPF checks but does not pass DMARC. This is because DMARC requires that the From email address domain matches the Return-Path header’s domain. If you are using an email service that uses its own return-path, the email will not pass SPF for DMARC alignment. Postmark allows for you set a custom return-path to meet this requirement for DMARC alignment. For other email services you use, you will want to check if they also have this custom return-path option available.
DMARC record syntax
DMARC records are TXT DNS records, like SPF and DKIM. Here is an example DMARC record:
Let’s look at these values above in more detail. There are additional properties you can add to your DMARC record but we are just going to examine the most commonly used. For more information on what you can add to your DMARC record, check out the DMARC specification here.
Tag
Value
Notes
v=
DMARC1 (Must be upper-case here)
Required. When the record is looked up this tells us what version of DMARC the policy is using.
p=
nonerejectquarantine
Required. Possible options are none, reject, and quarantine. None means that there is no policy for rejecting emails that fail DMARC alignment. They are still to be delivered as normal, even if they fail alignment. Reject tells the receiver to discard the email if it does not pass DMARC alignment. Quarantine tells the receiver the email should be quarantined and have additional spam checks ran on it or be marked as spam in the recipient’s inbox.
pct=
0 - 100
Optional. This can be a value of 0 - 100 and defines what percentage of emails the policy should be applied to. If you do not set a value here it will default to 100.
rua=
email@domain.com
Optional. The rua= field is populated with the email address you would like to receive aggregate reports at. If you generate a DMARC record using our DMARC reporting tool, we will populate this field with a value where we will receive the reports at. We then convert the XML we receive into a human readable format and send the reports weekly to you at the email address you used when signing up for the DMARC reports.
Creating your DMARC record
When a DMARC policy is in place for a domain, email providers will send reports in XML to the email address(es) in the rua or ruf tags present in the DMARC record. These reports are not easily read and understood so we built a free tool to help you decipher the results. Head over to https://dmarcdigests.com/ to create a DMARC record to add to your DNS. Not only will this provide you with a syntactically correct DMARC record for setting your DMARC policy, we will also generate human readable reports of your DMARC results and send them to you weekly.
If you do not want to use DMARC Digests, you can create your own record using the syntax and format discussed above. Once you have your DMARC record created, add the record to your DNS as a TXT record with host _dmarc.
Add a DMARC Policy for Your Domain
With DMARC, the best practice is to implement it in two stages, Observation and Implementation. You do not want to immediately set your DMARC policy to reject or quarantine or you risk your customers missing vital emails that fail DMARC alignment. Getting all of your email sources passing either DKIM or SPF can take some time.
Observation:
Create a DMARC record to start monitoring results, with the policy set to none (p=none).
Analyze DMARC reports to identify passing, failing or missing sources. Postmark’s DMARC reporting tool is very useful for this step.
Convert all known email sources to have DMARC aligned with DKIM and SPF. This step requires that you add DKIM and SPF authentication to all of your email sources that are legitimate.
Implementation:
Once ready, start to quarantine email sources that do not align with DMARC (p=quarantine).
Once you are confident that you will not cause legitimate emails to be rejected, set your policy to reject so that illegitimate emails are rejected by receiving mail servers.
For more information on DMARC, be sure to check out our guide.
Although you're not able to import and manage your email lists inside of Postmark, we do have some tools in place for helping to manage unsubscribes and suppression lists.
Starting with unsubscribes, let's take a look at when unsubscribe links should be used and how they work.
Every message sent through a broadcast Message Stream in Postmark is required to have an unsubscribe link and you can do this by adding a placeholder:
{{{ pm:unsubscribe }}}
This will then be replaced with a Postmark unsubscribe link. Transactional messages do not require an unsubscribe link, though there will work there too.
Usubscribe link preview
The default text for the unsubscribe link is "Unsubscribe", though this can be changed when you treat the placeholder as an unsubscribe link:
<a href="{{{ pm:unsubscribe }}}">Unsubscribe from this list</a>
Now that the placeholder is a hyperlink, you have more flexibility in terms of styling. You could, for example, change the font and colour so that it matches the branding of your email.
Keep in mind that if you’re sending a broadcast message which doesn’t include an unsubscribe link, we’ll automatically add it for you at the end of the message. If you'd like to not use Postmark's unsubscribes links, please get in touch to tell us more about how you're managing unsubscribes.
If a recipient clicks the unsubscribe link, they'll be taken to a confirmation page that let's them know they've successfully been unsubscribed and they have an option there to subscribe again if they change their mind
Unsubscribe confirmation page
They will only be unsubscribed from the message stream from which the message was sent. This is why we encourage you to create many message streams - one for each of the different types of messages you're sending. This way, an unsubscribe from your newsletter emails won't impact you being able to send those vital password resets, for example.
Back to the confirmation page we were just going over - your recipients will see your message stream name there so it's important to use one that clearly reflects the types of messages that are being sent. You can change that, along with adding a description in your stream's settings
Stream settings
Once a recipient unsubscribes, they'll be added to your Suppression's list which we'll talk about in the next section.
Suppressions give you the ability to manage all of your suppressed recipients under one roof for a particular message stream.
Recipients can be automatically suppressed for three reasons: due to a hard bounce, a spam complaint, or an unsubscribe.
You're able to reactivate hard bounces and unsubscribed recipients within your account. If a recipient that made a spam complaint would like to start getting your messages again, just let us know and we'll be able to lend a hand there!
Another handy option is the ability to manually add recipients to the suppression's list. If there are addresses you want to avoid sending to such as a test address, or any address which you know are no longer active, you can simply add them to your suppression's list. You can add up to 50 in one go there.
Suppressions overview
From your suppression's list, you can click on an email address and from there you can see which particular message resulted in the bounce/complaint/unsubscribe, along with more detailed information in the case of bounces.
Bounce example
One important thing to note here is that this more detailed information is only available for 45 days by default (but retention can be customized from 7 to 365 days), since that’s how long Postmark stores that for in your activity.
Syncing suppressions with your list outside of Postmark #
If you'd like to sync your suppressions to a list you maintain or
receive notifications of unsubscribes, there are two options:
Postmark's Subscription Change webhook will notify you whenever an address is added to your Stream's Suppressions.
Inbound processing allows users to interact directly with your app from their email inboxes. The most common application of Inbound processing is to relay messages between two or more users in your application. This is useful for things like direct messages, forum comments and replies, support tickets, etc.
As a more advanced scenario, you can also use inbound processing combined with inbound domain forwarding to receive emails sent to a domain or sub-domain that is not actually configured to host email addresses. For example, you can configure a domain called billing.yourappname.com that receives replies from your users at your inbound webhook without having to have a hosted email address on that domain. If you add this same domain to your Sender Signatures/Domains, you then also have the ability to create email addresses for your users that they can use for both sending and receiving. You could programmatically generate email addresses for your users that you use to keep track of which user emails belong to.
Now that you have an idea of the uses for inbound processing, let’s move onto implementing it in your application.
In order to receive emails with Postmark you need to use our Inbound webhook. Each Postmark Server comes with an associated inbound message stream, which has an inbound email address that you can use to receive emails as JSON. The inbound email address will be in the format of a GUID@inbound.postmarkapp.com, such as 482d8814b3864b2c8ba7f7679fc116bf@inbound.postmarkapp.com.
You can access your inbound email address in the Setup Instructions and Settings pages of the server's inbound message stream. When an email is sent to your inbound email address, it will be received as JSON at your inbound webhook URL:
At first glance it looks like there are a lot of fields there to parse but they are all very useful and have a purpose. Using the MailboxHash key, you can keep track of which inbound messages belong to which email thread or conversation, and relay the emails between two or more recipients. When emails are sent to InboundAddress+hash@postmarkapp.com, we extract the hash part of the email address out so it can be used to keep track of the email and associated emails. Assign a unique value for the MailboxHash key and use it to determine the routing of the received email. You can then send the email content where it should be received by your user(s).
Each inbound message stream can have one inbound webhook URL. Setting the inbound webhook URL for a stream tells Postmark where to send the JSON for emails received at the inbound email address for that stream or the stream's inbound forwarding domain.
When logged into Postmark, select the inbound message stream and go to the Settings page. The Webhook field is where you input your webhook URL.
Setting the inbound webhook url
Once you enter a URL for receiving inbound webhooks you can use the Check button to confirm that your URL is working as expected. When you check the URL we will send an example inbound webhook to your URL and let you know if we get back a 200 HTTP response code (success) or an unsuccessful response from your URL.
To make sure that no one can access your webhook endpoint without authorization we suggest protecting it with HTTP basic authentication. You can include the credentials in the webhook URL by prepending username:password@ to the hostname in the URL:
https://username:password@domain.com/hook
Note that HTTP basic authentication is insecure over unencrypted HTTP. You should only use the Postmark inbound webhooks over HTTPS.
Postmark parses the incoming emails and delivers them to your webhook as JSON documents. In case your application needs raw email content (RFC 822) make sure to check the box labeled Include raw email content in JSON payload before saving the changes. With this option on, the JSON document will have an additional field named RawEmail with the raw content of the email.
If you have access to Terminal (Mac/Linux) or Command Prompt (Windows) with cURL, you can test your inbound webhook URL locally with the following command:
Using cURL lets you test your inbound webhook URL before it is hosted and available through the internet. Be sure to replace portNumber with the port your application is running on locally before trying to use the above command to send a test inbound webhook to your application.
Once you have configured your inbound webhook URL and have your application available through the internet, test its ability to correctly process inbound emails by sending an email to your inbound email address. Send multiple emails with different formats (plain text, HTML, attachments, etc…) to ensure that your application is handling all scenarios correctly.
When your inbound webhook URL returns a non-200 status code, we will schedule the JSON POST for a retry. A total of 10 retries will be made, with growing intervals from 1 minute to 6 hours. If all of the retries have failed, your Inbound page will show the message as Inbound Error.
If you have access to DNS records for your domain, inbound domain forwarding allows you to receive emails to your inbound webhook URL that are sent to your domain or sub-domain. Note that once you set up inbound domain forwarding for a domain or sub-domain, the emails will be processed by Postmark and no longer received through your previous method, if present.
1. Set an MX Record
Choose a domain that you would like to listen on for incoming email to be processed by Postmark. We recommend using a separate subdomain, like inbound.yourdomain.com. In your DNS configuration, create an MX record that points toinbound.postmarkapp.com, and give it a value of 10.
You may also use a “wildcard” inbound domain such as *.yourdomain.com, which will cause all messages addressed to any subdomain of yourdomain.com to be routed to your inbound endpoint. For example, if you register *.yourdomain.com with Postmark and your DNS host, you may then use an inbound address such as user@client1.yourdomain.com and it will be routed to your inbound endpoint.
2. Set the domain
Inbound domains are unique across Postmark and are specific to an inbound message stream. You can configure the Inbound Domain in the server's inbound message stream's Settings page.
Alternatively, you can use the Server API to set the Inbound Domain on your server.
3. Enable SMTP
Enable SMTP in the server’s transactional message stream's Settings page, if it is not enabled already. This setting is enabled by default.
Enable SMTP for inbound domain forwarding
4. Send emails
You are now able to send emails to any address for @inbound.yourdomain.com and they will be processed.
In order to use webhooks, you have to publicly expose URLs that either you or a provider host. It is important to ensure that these exposed URLs cannot receive malicious POSTs. To prevent unauthorized or malicious messages at your URL(s), there are a few steps you can take.
Postmark lists our IPs we use to send webhook event data here. Check incoming HTTP requests for the request’s IP address and if it does not match an IP address we list, reject the request.
You should also use HTTP basic authentication over HTTPS/TLS as described above.
Another security step is to validate the data received, depending on the URL and webhook type. Check the body of the incoming request to ensure it matches the JSON schema of our webhooks, and does not include additional data. This will also prevent receiving webhooks at the wrong URL, for example receiving a bounce at your inbound URL if a Postmark server is incorrectly configured.
An additional step you can take is to specifically only allow the HTTP POST method to be used with your URL. You can prevent GET, PUT, and DELETE HTTP requests from being processed and whitelist only the POST method.
While inbound processing may at first seem technically daunting to implement, you do not have to go it alone when developing your code to receive inbound webhook events. There are several example webhook ‘mitts’ that are open sourced for you to take advantage of or use as a starting point to developing your own. Head here to see some open source examples for processing inbound messages using the following languages/frameworks:
Note that these inbound processing examples are graciously contributed by the Postmark community and are not developed, maintained, or supported by Postmark directly. If you have any specific questions around the examples, your best bet is to reach out to the GitHub project’s owner through an issue for help, to report a bug, request a feature, or get clarification on functionality.
Once you’re set up and processing email, you can, for the most part, forget about your transactional email. We’ll take care of making sure your messages get to your customers’ inboxes as quickly as possible, and if there are any problems, you’ll be able to find out about it immediately if you use webhooks.
But Postmark doesn’t stop there. As you explore our app you’ll discover that we have an extensive web app that gives you access to a bunch of statistics and events. This activity data can help you to understand your email performance better, and improve the parts that don’t work so well.
Let’s look at some ways to make sure you get the most out of our statistics.
Open tracking works only for HTML emails. You can send a multi-part email (both plaintext and HTML), but an open will only be tracked if the HTML version was opened. For every email you tell Postmark to track, an invisible, 1x1 pixel image, is added. When the recipient opens the email and the image is loaded, Postmark will know that the email was opened.
Most email clients will download images by default, but some will not. If a person reads the email without images, an open event will not be tracked.
Postmark will record each time the email is opened, including multiple opens by the same recipient. Both unique and total opens will be displayed so you can gather both stats. Postmark will also provide you with the following data (when available):
Geographic information
Operating system information (Mac, Win, etc)
Browser information
Device and platform used to read the email
You can enable open tracking for an entire server, a specific email, or for all emails that belong to a tag.
Viewing Open Tracking details
HTML emails that have been opened will appear in your Activity page and look like this:
When you click on an individual email subject, you’ll be able to see the full email text, as well as additional details about the Open event:
Tracking Emails By Server
To track all email sent through a particular server, set the Open tracking switch to enabled in the settings tab of the server you want to track.
Tracking a Single Email With The API
You'll need to enable a flag called TrackOpens by adding a new property to the JSON you send to the /email endpoint. Use TrackOpens and set it to true. Setting it to false will omit open tracking from that email.
"TrackOpens" : true
Tracking a Single Email With STMP
To enable open tracking for a single email, add a header called X-PM-TrackOpens to your email and set it to true. Setting it to false will omit open tracking from that email.
To track all emails with a specific Tag (for instance all of your Welcome emails) you'll need to use our /stats/outbound/opens endpoint. Please read the documentation for more details.
Link tracking lets you gain insight into what actions your users are taking within the emails you send them. This help article will provide some additional details about how we are able to track what links are clicked by a recipient.
Link tracking works by routing the links you place in the tracked emails through our tracking servers at click.pstmrk.it. When link tracking is enabled for an email you send, we will scan the HTML and/or Plain Text content (depending on your Link Tracking settings) of the email for links and replace them with the wrapped version that performs a redirect through our pstmrk.it domain. We then record the following data before directing the recipient to the original URL:
IP
User-Agent
Link ID
Timestamp
Viewing Link Tracking Details
Successfully tracked links will appear in your Activity page and will look like this:
If you open the Message for more details, you can see the information obtained for the click:
In the Message details, you can see which link was clicked, along with the browser used, time, and geolocation. With this link tracking information, you can check to see if a specific link was clicked and when.
Formatting Links
Do not use URLs as the display text for links in your emails or your email may appear to ISPs as a phishing attempt. Instead, describe the link in your HTML like this:
There are several options for enabling and using our Link Tracking feature. You can track links at the message server level (tracks links for all emails sent from a specific server) or Message level (track links for individual emails manually). Both of these options allow for you to also choose whether to track links in HTML emails, Plain Text emails, or both.
Server Level
The easiest and quickest way to enable Link Tracking is directly from the Settings tab for your Server. Click the toggle to enable link tracking for the server from here.
If you wish to track all links for emails you send from this server, you are now all set and tracking will begin immediately. If you would like to learn more about advanced options for Link Tracking, continue reading.
More Link Tracking Options
Link Tracking can also be enabled for a server by opening the server's Settings tab. Click the toggle below Link tracking to enable Link Tracking for all emails sent using this server. This option will track links for all emails sent from this server by default.
Once enabled, you will then have the option to track links in HTML or Plain Text emails. By default, links in both HTML and Plain Text emails will be tracked when you enable Link Tracking. You can disable link tracking for HTML or Plain Text emails from a server's Settings in the Tracking panel.
All emails from this server will now have their links tracked for the email types chosen by default. See below for details on how you can override these defaults at an individual email level.
Message Level Link Tracking
When sending using the API, you can set the Link Tracking behavior at the individual email level using the "TrackLinks” field. Options for this field are:
"TrackLinks": "HtmlAndText" - tracks links in both the HTML and Plain Text parts of the email
"TrackLinks": "None” - do not track any links
"TrackLinks": "HtmlOnly” - only track links in the HTML part of the email
"TrackLinks": "TextOnly” - only track links in the Plain Text part of the email
"TrackLinks": null - do not specify a value, uses the default for the Server
Disable Tracking for Specific Links
If you are tracking links in HTML emails, you can also opt out specific links by adding an attribute with value data-pm-no-track to the link. For example, this link will not be tracked: <a data-pm-no-track href=\"http://www.somedomain.com\">This link won't be tracked.</a>
Step 2: Set up tags for more effective statistics #
You can categorize outgoing email using the Tag property. One Tag can be added to each message sent. Adding tags to your messages lets you categorize them for sorting and searching later. You can search your Postmark activity feed by Tag, allowing you to find messages faster. In addition, with open tracking, Tags will allow you to segment campaign statistics.
For example, you can add a tag called Welcome to all welcome emails to your customers. You can then choose to use a different tag for password resets or confirmation messages to make groups of messages easier to filter. You will be able to filter activity by this specific tag, get daily or weekly sent totals and also view open tracking stats based on this tag only.
Below: password reset emails generally have a much higher open rate than welcome emails.
Step 3: Review your stats regularly to spot issues #
Using the API you can easily review emails filtered by the Tag property. Using the Messages API / GET Messages API call and filtering by Tag will show messages which include each Tag.
You can also use the Stats API and filter by Tag to gets specific counts for each Tag sent during a specified date range. If messages tagged with Welcome are down from the previous week or month then this can signal that your marketing initiatives need to be reviewed to help get new users signed up.
Stats and Activity can also be used to spot other issues like high bounces and spam complaints. If you see an issue with this in your Postmark weekly digest or Stats overview page, then further investigation is usually required. An acceptable bounce rate should be under 5%. If you notice bounces above that it’s likely that either people are giving you bad emails or you are sending to old and outdated addresses. Try to figure out why the rate is high and work to lower it.
Is your spam complaint rate is high then there is something there too wrong. Good transactional emails should not generate any spam at all and your spam rate should be less than 0.10%. Yes, that is 1 complaint in 1,000 emails sent. If you’re seeing much more then people didn’t expect or want your email and you need to figure out how to avoid it from happening. There are strict rules, we know, but these rules are why Postmark has some of the best inbox rates in the industry.
We make it easy for you to spot trends by allowing you to filter the activity view by bounce type. Here you will be able to quickly see the number of Hard bounces, Spam complaints and any other bounce types recorded and view all emails that returned this specific bounce. Keep in mind that sent message are kept for 45 days by default (and retention can be customized from 7 to 365 days), but bounces and spam complaints are kept indefinitely since they can help with troubleshooting.
You can also search the activity to find delivery information for each message. Let’s say one of your users is reporting they never received a confirmation email from you. From the activity page you can easily search for the users address and find all messages that were sent to them. Clicking on the message in question will reveal the delivery information we received back from the recipients mail server. If you see a successful delivery event there, this data can then be passed on to the user to help them track down the message on their mail server.
Even with all this information about how to get started with Postmark, we understand that you might need a bit more assistance to get going. Fear not — if it’s detailed information you want, we have it! There are several ways to dig even deeper into what Postmark has to offer.
Our guides are a great place to start for more detailed information on the more common areas of transactional email. We cover topics like authentication (SPF, DKIM, and DMARC), how to troubleshoot when things go wrong with your email, and how to make sure you write emails that will get to your customers’ inboxes.
We also have a series of guides on best practices for different kinds of emails you might want to send — from welcome emails, to password reset emails, to receipts (and more!).
If you’re ready to get a bit more technical with your Postmark implementation, check out our extensive knowledge base. This is where you’ll find detailed information on topics like how to track your emails, how sender signatures and domain verification work, and how to integrate with third party systems.
Since our product is primarily aimed at developers we spend a lot of time to make sure our technical documentation is clear and comprehensive. Here you’re find technical user guides, as well as detailed API reference documentation.
If you’re ready to try out the API, you can use our API Explorer to to send API requests directly to your Postmark server or account.
Even with all that, we know that sometimes you just want to ask someone a question. Well, we’ve got you covered there as well. We have an amazing support team ready to answer any questions you have. Just email us at support@postmarkapp.com and we’ll get back to you within a day (or two!).
