Migrating email service providers can be a large undertaking. We want to help relieve some of that stress of moving to Postmark from Mandrill. This guide will detail some of the differences and similarities between Mandrill and Postmark, as well as give some useful tips for migrating to Postmark from Mandrill.
It includes details on differences between Postmark and Mandrill’s APIs, sending outbound emails, processing inbound emails, UI differences, and webhooks.
Important concepts to learn when moving over to Postmark
There are a couple important concepts to learn when moving over to Postmark: Servers, Message Streams, Sender Signatures, and Verified Domains. A server and a confirmed sender signature or verified domain are required for sending, so it is important to understand what they are used for.
Each Postmark account contains servers, which are somewhat similar to Mandrill's sub-accounts feature. Servers can be thought of as folders you create that group together similar email activity. Each server contains Message Streams to separate your Inbound, Transactional, and Broadcast messages and stats, as well as the server API token(s), a unique inbound email address, and templates. You can create as many of these servers as you need, there is no limit.
Some uses of servers are separating different types of emails such as transactional and broadcasts, separating your clients’ activity, sending emails for different environments (prod, staging, development), or separating sending for your different domains. When you begin adding more users to your Postmark account, you can also assign them access to specific servers so that they can’t view email activity or change settings across your entire Postmark account.
Postmark separates email traffic through Message Streams, meaning that transactional and broadcast traffic never intersects in Postmark, including IP ranges. This is a longstanding best practice for ensuring optimal deliverability. Transactional message streams are for messages that are usually unique and triggered by a user action like a password reset, opted-into weekly digest, or receipts. Transactional streams do not support bulk messages. Broadcast message streams are for bulk messages that sent to multiple recipients at once like announcements, newsletters, or other application email.
In Postmark, you need to have a confirmed sender signature or verified domain for each email address you want to send from. Sender signatures are individual email addresses that are authorized for sending via a confirmation email sent to that address. Adding and verifying a domain using a DKIM record lets you send from any email address on that domain. Unlike Mandrill, it is not required that you set up both a DKIM and SPF record to verify a domain - only a DKIM record is required.
We use sender signatures and verified domains to ensure you own or are authorized to send from the mailboxes you add to your Postmark account. You can have as many signatures and domains as you need, there is not a limit. Sender signatures and domains are associated with your account, not a specific server. This means they can be used for sending across all of your account’s servers.
Each Postmark account has an account API token. Every server in an account also has its own server API token(s). Server API tokens are used for server-level actions such as sending email, getting statistics, modifying a template, etc… account API tokens are used for account-level actions such as creating a new server or adding a new domain for sending.
Postmark also has a test API token option - use POSTMARK_API_TEST as your token when you want to generate a test API send request that does not actually send an email. Note: Postmark's test token cannot be used to test sending with a template.
Postmark also allows for customizing messages sent using SMTP via SMTP headers.
Differences from Mandrill
Postmark does not have the option of automatically generating plain text content for your emails.
Postmark allows you to create servers that have a sandbox mode so that you can safely test out different parts of the system.
Postmark cannot be used to schedule messages to be sent at a later time - all messages are sent immediately. A priority can also not be sent with Postmark, since messages are sent immediately in the order the requests are received.
To generate test webhook events for bounces, spam complaints, etc... use the test area of the webhook settings in Postmark's UI.
Postmark lets you have an unlimited amount of unique tags, Mandrill has a 100 tag per account limit. Only one tag can be used on each Postmark message.
Postmark supports both HTTP and HTTPS for API endpoints, though we recommend using HTTPS.
Postmark’s outbound message size limit is 10 MB including attachments, whereas Mandrill’s limit is 25 MB.
Postmark messages can have up to 50 recipients in a single message - Mandrill can have up to 1,000 recipients when sending with SMTP and no recipient limit when using their API.
Mandrill assigns an hourly quota to accounts that can't be modified manually. Postmark does not limit the number of messages you can send per hour, so long as the messages fit our sending guidelines.
You can use the unique API Token for your server (which acts as both a username and password) and a Header to
specify the message stream you're sending through. If a header is not
specified, Postmark will send through the default transactional stream.
If you don't have an option to add a custom header during the SMTP send, you can instead use an SMTP Token. An
SMTP Token consists of an Access Key (which acts as a username) and a
Secret Key (which acts as a password).
Tip: Port 465 is not supported with Postmark SMTP. If you were using that port with Mandrill, you will need to switch over to using port 25, 2525, or 587 when using Postmark SMTP.
When authenticating with the Postmark API for sending emails, you will need to use your server API token in an X-Postmark-Server-Token header. As a reminder, you can get your server API token from the server’s API Tokens tab.
Postmark and Mandrill both process inbound emails by converting them to well-formed JSON, which is then posted to a URL that you specify for receiving inbound webhook events.
Both implementations of inbound processing feature the ability to process emails sent to an entire sub-domain/domain using MX records.
Attachment content is received in base64.
Manage inbound webhook settings using an API (Inbound API in Mandrill, Server API in Postmark).
You can use a wildcard in your MX record to have all sub-domains of your domain work for inbound processing.
Inbound domains are managed at the Stream level in Postmark, Mandrill has inbound domains specified account wide.
There is not an option to set up routes for Postmark inbound processing.
Images are not separated from other attachments when processing email with Postmark.
Each server you create in Postmark will come with a unique inbound email address (ex. email@example.com) that you can use to receive emails inbound at your webhook URL without needing to set up an MX record. If you want to use inbound domain forwarding, an MX record is required.
Postmark requires that you enable SMTP (if not enabled already) on your Postmark server to use inbound processing.
When an inbound webhook URL returns a non-200 code, Postmark 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 activity page will show the message as Inbound Error.
Mandrill batches events for each webhook URL and POSTs approximately every minute, Postmark sends POSTs immediately in the order the messages are received.
Postmark’s inbound message size limit including attachments is 35 MB, whereas Mandrill’s is 25 MB.
Both Mandrill and Postmark allow you to receive notifications as JSON POSTs to URLs you specify when specific events occur. Like Mandrill, Postmark splits up event types into multiple webhook types, which allows for some additional flexibility and separation of concerns when developing and setting URLs for receiving webhooks.
Postmark’s delivery webhook allows you to receive notifications when an email is delivered to a recipient. In Postmark, an email is considered successfully delivered when the destination email server returns a 250 OK response after delivery is attempted.
Postmark includes some additional information for bounce events that is not present in the Mandrill Event Webhook you should be aware of:
Unique identifier for the specific bounce event (used to reactivate a bounced email address using the Postmark Bounce API)
Information on whether the recipient’s email address is deactivated and can be reactivated
Whether a message dump is available. Postmark stores content for 45 days. If the message was sent less than 45 days ago,
you can get a full dump of the message content if this parameter’s
value is true
Whether the recipient’s email address can be reactivated
If a message dump is available
Stream used to send the email
Tip: Postmark includes an additional option when setting your bounce webhook URL to include the message content in the JSON sent to your URL. This option lets you receive the full message content (as a dump) when receiving bounce event information.
A subscription change is recorded when an email address is added or removed from a Message Stream's Suppression list. An email address is added to a Suppression List after a Hard Bounce, Spam Complaint, or Manual Suppression.
When you log into Postmark you are placed in the Servers page, which shows each server you have created. Each server you create has a default transactional message stream for outbound sending and an inbound message stream for processing inbound email. Each server has tabs for Message Streams, Templates, API Tokens, and Settings. Each message stream has tabs for Statistics, Activity, Suppressions, Webhooks, Setup Instructions, and Settings, which are unique for each message stream.
Servers let you separate your outbound and inbound message streams, templates, and credentials based on domains, environments, customers, or any other criteria that helps organize the activity of a given application or website.
The main servers page will show you a list of your servers. You can create as many servers as you need, there is no limit. You can also pin your most frequently accessed servers so they appear at the top of the list. Servers not used in the last 30 days will be greyed out, for easy identification of which servers you may want to delete or repurpose.
To view detailed statistics and metrics for a server's message streams, locate the server in the servers list or by using the search field. Click on the bar graph icon and select the server's message stream you are interested in to be taken to its overview page.
The statistics tab is similar to Mandrill's dashboard and stats pages, though each message stream in a server has its own statistics page, rather than an overall account view like Mandrill. Included in the statistics area for an outbound message stream is the sending volume, link tracking metrics (if turned on), open tracking metrics (if turned on), and bounce/spam complaint metrics. The inbound message stream's statistics page includes metrics on the number of successfully processed emails and failures.
To see your inbound and outbound activity in a server, select the message stream you are interested in and click on the Activity tab. This area will show a detailed event view of the stream's events, including sent, delivered, open events, spam complaints, bounces, etc... for the outbound stream and inbound processing events for the inbound stream. Use the search bar to look for emails by subject or email address.
To see details for a particular event in a stream, click on the event. Some events included in the outbound stream are sent emails (Processed), bounces, spam complaints, clicked links, and opened emails. Events in Activity are color coded to help you tell what occurred at a glance:
Postmark gives you the ability to create and store templates, including a variety of pre-built and well-tested templates for common scenarios. From the templates tab you can create, edit, and delete the server’s templates. Each server contains its own templates but you can copy templates from one server to another.
Alternatively, if you'd like to build your own batch of templates, we've created and open-sourced MailMason to help you automate the process of creating, testing, and managing your own templates using partials, variables, SASS, and asset management. We also have an online template generation tool that provides customization options for the most common template types.
The Settings tab in a server lets you modify the server’s name and color, turn on/off SMTP sending for the Server, and turn on/off Link and Open Tracking. It is also where you can delete a server that is no longer being used.
The API Tokens tab shows you your server API token(s). Use this tab to generate and delete server API tokens. Server API Tokens are used for outbound sending, SMTP authentication, and making server level API calls. A Server can have up to 3 active API Tokens.
The users page is where you add and manage your Postmark account users. You may need to add additional users to your account for tasks such as viewing activity for troubleshooting and tracking purposes, managing server settings, creating templates, etc... Use our different roles to effectively manage the security of your account. See our help article on setting permissions for an overview of what options there are and how to control your users’ permissions.
For more Postmark specific insight on how to get started and get the most out of Postmark, make sure to look through our “Getting Started Guide” or visit our support center where you can easily search all of our documentation from a single place. API docs. Guides. Blog posts. Help docs. Labs projects. You name it. We probably have something that can help you out.
Once you've switched to Postmark, you may want to become familiar with our status page and status API. We believe deeply in transparency, and we go a step further than just system availability and share our inbox rates and delivery speeds for the five most popular inbox providers. We also offer all of the data via an API so you can monitor us and set up automation in the event something does go wrong.
You now have a solid understanding of how to transition over the core features you need in an ESP and how to move from Mandrill to Postmark, including how to send outbound and process inbound email, what APIs and webhooks to use for certain functions, and how to view your email activity and statistics. If you have any questions about where to find a setting or how to use a feature in Postmark, get in touch and we can help!