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 bulk marketing email, and the second is transactional email. Marketing emails are comprised primarily of newsletters and other scenarios where the same message is delivered to hundreds or thousands of people at the same time. With transactional, the emails are usually sent to an individual or a small group of people and triggered by specific actions or inactions.
One thing that sets these two types of emails apart is the context within which they’re sent. Transactional emails are emails that recipients expect. These are things like receipts, password reset emails, or comment notifications. Because of the fact that recipients expect these emails, they see much higher open rates and engagement when compared to marketing emails. That context also makes transactional emails different in terms of the content customers want and expect from them.
You should think of transactional 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 transactional 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 transactional email so that you can focus on your business.
We focus only on transactional email — we don’t allow bulk marketing of any kind on our platform. We do this for a simple reason: it ensures that we have the highest inbox rate and delivery speed in the industry, since our IP addresses have stellar reputations with virtually no spam complaints. 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 transactional 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 transactional 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 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". This allows you to separate your clients in a logical structure and view the results for each of their different message streams on their own.
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. 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
Sign up for an account
Decide if you need to send email (outbound), 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?
You’ll notice we talk about Outbound and Inbound email a lot in this manual. 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, invoices, 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: Send a test email
Step 4: Integrate with your app
Step 5: Get the most out of sending with webhooks, templates, and tags (optional)
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.
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
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 environments. In that way, servers are like folders on your computer.
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.
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 Full Name, From email address, and Reply To email address (optional).
Once you add a Sender Signature, a confirmation email will be sent automatically from Postmark to the email address you added. These Sender Signature confirmation emails cannot be customized at this time and 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 a custom Return-Path.” 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.
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 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.
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 5: Get the most out of sending with 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.
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:
"Name": "Hard bounce",
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "Test bounce details",
"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”.
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, time spent reading the email, 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:
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 your templates.
Getting started with templates
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.
If you're using one of our official API libraries, they will include the ability to send emails using a Template.
Sending using a template w/ the API
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:
You will notice that the data we passed in our TemplateModel field is what gets populated for the variables we had placed in the Template.
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.
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.
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.
DMARC1 (Must be upper-case here)
Required. When the record is looked up this tells us what version of DMARC the policy is using.
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.
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.
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://dmarc.postmarkapp.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 our DMARC reporting tool, 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.
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.
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.
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 firstname.lastname@example.org.
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 InboundAddressemail@example.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.
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:
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.
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 firstname.lastname@example.org 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.
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):
Operating system information (Mac, Win, etc)
Device and platform used to read the email
You can enable open tracking for an entire stream, 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 Stream
To track all email sent through a particular stream, set the Open tracking switch to enabled in the settings tab of the stream 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:
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.
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 stream level (tracks links for all emails sent from a transactional message stream) 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.
The easiest and quickest way to enable Link Tracking is directly from the Statistics tab for your message stream. Scroll down to the bottom in Statistics to see the area for Link tracking. Click the toggle to enable link tracking for the stream from here.
If you wish to track all links for emails you send from this stream, 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 stream by opening the transactional stream’s Settings tab. Click the toggle below Link tracking to enable Link Tracking for all emails sent using this stream. This option will track links for all emails sent from this stream 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 transactional message stream's Settings in the Tracking panel.
All emails from this message stream 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 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.
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 email@example.com and we’ll get back to you within a day.