Two paper planes. One white and one yellow.

Mandrill Migration Guide

Everything you need to know about moving from Mandrill to Postmark

Table of Contents

Chapter 1


Key differences between Mandrill and Postmark

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.

Key differences between Mandrill and Postmark #

These are some important differences to be aware of when moving over to Postmark from Mandrill:

  • Postmark does not allow anyone to send marketing or bulk email, whereas MailChimp does. If you were sending your marketing and/or bulk email through MailChimp and want to switch those over to another provider, we highly recommend using Campaign Monitor for any bulk email you need to send.
  • Since Postmark does not allow bulk email (including subscription newsletters), there are no list management features available in Postmark, such as handling unsubscribes or automatically adding unsubscribe links to your outbound emails.
  • Postmark’s APIs accept and return JSON only. HTTP POST parameters are not accepted for API requests and there is not an option to have API responses returned in XML, YAML, or PHP formats.
  • We do not recommend using dedicated IPs for most senders but do have that option available if you meet certain eligibility requirements as a sender.
  • Postmark does not have an option to automatically generate HTML content from Text email parts or vice versa. All content must be explicitly specified when sending the email or creating a template.

Let our team guide your migration process. Schedule a call with our success team.

Chapter 2

Postmark Concepts#

Important concepts to learn when moving over to Postmark

There are a couple important concepts to learn when moving over to Postmark: Servers, 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.

Servers #

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 has its own activity (inbound and outbound), stats, 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 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.

Sender Signatures and Verified Domains #

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.

Chapter 3


How the Postmark API works

A note on API tokens in Postmark #

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.

Check out our help article on the different API Tokens in Postmark for more information.

APIs Map #

API Type Mandrill API Name Postmark API Name
Sending Emails Messages
Managing Bounces Whitelists, Rejects, ExportsBounce
Managing TemplatesTemplatesTemplates
Managing Sending Settings SubaccountsServer
Managing Servers SubaccountsServers
Managing Sent Emails ExportsMessages
Managing Inbound Emails ExportsMessages
Manage email domains you can send from SendersDomains
Manage email addresses you can send from SendersSender Signatures
Sending Statistics ExportsStats
Manage Webhooks WebhooksServer
Manage Users Users
Managing IP Pools Ips

API Libraries #

In addition to the official libraries offered by Postmark, we also include community submitted libraries for additional language/framework options.

API Libraries Map #

Language/Framework Mandrill Official Library Postmark Official Library Postmark Community Library
Postmark .NET
Classic ASP Simple Classic ASP Class for Postmark
Clojure Clojure Binding for Postmark API
ColdFusion cfPostmarkapp, ColdFusion component, A replacement for the stock Coldbox MailService Plugin
Drupal Drupal Library
ElixirEx Postmark
Erlang Erlang Library
Postmark Golang, Postmark.go
Grails Grails plugin
Grunt Postmark Grunt
Haskell Haskell Library
JavaPostmark JavaJava library, Spring's MailSender compatible implementation
Laravel Laravel Plugin
Magento Magento Extension
NodeJS NodeJS Postmark.js
Objective-C Standalone Objective-C Class
Perl Perl WWW::Postmark
Pharo Smalltalk Pharo Smalltalk, Postmark
PHP PHP Postmark PHP PHP Community Libraries
PowerShell Postmark PowerShell Snap-in
Python Python Postmarker, pystmark, Postmark Python library
Ruby Ruby Postmark Ruby
Rails Postmark Rails
Scala Scala Client, Scala Library
WordPress Plugin Postmark for WordPress
Zend Postmark drop-in replacement for Zend

Chapter 4

Sending Outbound Emails#

Start sending through Postmark

Similarities to Mandrill

  • Sending via a REST API and/or SMTP supported.
  • 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 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 server settings page in the Postmark 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 are transactional.

Configuration for Sending via SMTP #

When using SMTP with Postmark, we recommend not opening more than 100 simultaneous connections.

Each server you create in Postmark will have its own unique server API token(s). You will need to use a server API token (found in the API Tokens tab of a server in Postmark) for authenticating SMTP sending.

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.

Setting MandrillPostmark
SMTP Endpoint
Port 465 for SSL, 25, 587, or 252525, 587, or 2525
Username Retrieved from SMTP & API Info pageServer API Token
Password API KeyServer API Token
Authentication Unencrypted, SSL, TLS Plain text (unencrypted), LOGIN, DIGEST-MD5, CRAM-MD5, TLS

If you need to whitelist the IPs you connect to Postmark SMTP with, whitelist the following ranges:

  • [ -]
  • [ -]
  • [ -]

This IP list is maintained at

Message Level Options when Sending with SMTP #

Similar to Mandrill, customizing messages sent using SMTP is done via SMTP headers.

Option MandrillPostmark
Bcc recipient X-MC-BccAddress Add as a Bcc w/ SMTP client
Click Tracking X-MC-Track X-PM-TrackLinks header
Open Tracking X-MC-Track X-PM-TrackOpens header
Tags X-MC-Tags X-PM-Tag header
MetadataX-MC-MetadataX-PM-Metadata- headers
Recipient VisibilityX-MC-PreserveRecipients
Inline CSSX-MC-InlineCSS
Content ManagementX-MC-ViewContentLink
DKIM Automatically uses DKIM signature if DKIM has been verified for the sending domain Automatically uses DKIM signature if DKIM has been verified for the sending domain
Custom Return-PathX-MC-ReturnPathDomainAutomatically uses custom return-path, if a custom return-path has been verified for the sending domain
Send using a template X-MC-Template
Postmark Templates can only be used when sending with the Postmark API

Sending via API #

Authentication #

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.

Outbound Sending API JSON Fields Map #

Field MandrillPostmark
From email addressfrom_emailFrom
From name from_nameFrom
To email addresses to → email To *
To nameto → name To *
Cc email addresses to → email + *cc headerCc *
Cc name to → email + *cc headerCc *
Bcc email address(es) to → email + *bcc header Bcc *
Bcc name to → email + *bcc header Bcc *
Subject line subjectSubject
Custom Tag tagsTag
HMTL Body htmlHtmlBody
Text Body textTextBody
ReplyTo email address headers → Reply-ToReplyTo
ReplyTo name headers → Reply-To ReplyTo
Custom Headers headers Headers
Template Identifier template_nameTemplateId
Data to use in Template template_contentTemplateModel
Open Tracking track_opensTrackOpens
Link Tracking track_clicksTrackLinks
Attachments attachmentsAttachments
Send At Time send_at
Google Analytics google_analytics_domains, google_analytics_campaign
IP Pool to Send From ip_pool
Send API Request w/o Sending Email Use a test tokenUse POSTMARK_API_TEST for your X-Postmark-Server-Token Token

Tip: To set a name when adding a To, From, Cc, or Bcc field with the Postmark API, use this format: Full Name <>”

To start sending quickly with Postmark's API, be sure to check our our official and community API libraries.

Chapter 5

Processing Inbound Email#

Migrating your inbound email handling


  • 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 server 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. 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.

Inbound Processing JSON Fields Map #

Email Property MandrillPostmark
Message Identifier for UI/API MessageID
HTML Body html HtmlBody
Plain Text Body text TextBody
Subject Line subject Subject
To Email Address toTo, ToFull → Email
From Email Address from_emailFrom, FromFull → Email
Cc Email Address Cc, CcFull → Email
Bcc Email Address Bcc, BccFull → Email
ReplyTo Email Address ReplyTo
Date tsDate
Attachment Filename(s) attachments → nameAttachments → Name
Attachment Content attachments → content Attachments → Content
Attachment Content-Type attachments → type Attachments → ContentType
Attachment base64 encodingattachments → base64* All Postmark attachments are base64 encoded
Attachment Size Attachments → ContentLength
Imagesimages* Images included with other attachments when using Postmark
Headers headers Headers
Tag tagsTag
Mailbox Hash MailboxHash
Stripped Text Reply StrippedTextReply
DKIM headersHeaders → DKIM-Signature
SPF headersHeaders → Received-SPF
SpamAssasssin Score spam_reportHeaders → X-Spam-Score
SpamAssassin Report spam_report Headers → X-Spam-Tests
SpamAssassin Version Headers → X-Spam-Checker-Version
Identified as Spam Headers → X-Spam-Status

Postmark inbound processing libraries and code examples #

Language/Framework Library/Code example
Rails Griddler Postmark
Ruby Postmark mitt (gem), Sample application
PHP Postmark inbound PHP
Python Postmark Inbound Python, postmarker
.NET C# + MVC Inbound Demo, Inbound Reply Text Parser in VB

Chapter 6


Migrating your webhook handlers to Postmark

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.

Webhook Types Map #

Event Type MandrillPostmark
Inbound Processing Inbound webhookInbound webhook
SentSent event
DeliveryDelivery webhook
BouncesBounced, Rejected, Soft-BouncedBounce webhook
Spam Complaints Marked as spamSpam Complaint Webhook
Open tracking OpenedOpen tracking webhook
Click tracking ClickedClick tracking webhook

Postmark will send a webhook event for each individual event, whereas Mandrill may send a single POST with multiple events included.

Delivery webhook #

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 Delivery Webhook Fields #

Parameter Postmark
Recipient’s email address Recipient
Tag/Category Tag
Delivery time DeliveredAt
Receiving mail server’s response Details
Email Identifier MessageID
Server used to send the email ServerID

Bounce webhook #

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 but retains bounce information indefinitely. 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

Bounce Webhook Fields Map #

Parameter MandrillPostmark
Recipient’s email address email Email
From email address senderFrom
Email subject line subjectSubject
Bounce timestamp tsBouncedAt
Tag/Category tagsTag
Unique bounce identifier ID
Bounce Type type, eventType
Email Identifier _id MessageID
Server used to send the email subaccountServerID
Custom metadatametadataMetadata
SMTP Status code status
Bounce details diagDetails
Description of bounce reason Description
Whether the recipient’s email is deactivated Inactive
Whether the recipient’s email address can be reactivated CanActivate
If a message dump is available DumpAvailable

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.

Spam complaint webhook fields map #

Parameter Mandrill Postmark
Event identifier ID
Recipient’s email address email Recipient
Sender address sender From
Tag/Category tags Tag
Timestamp of when spam complaint occurred ts BouncedAt
Email Identifier _id MessageID
Server used to send the email subaccount ServerID
Custom metadata metadata Metadata
Spam complaint details Details
Whether the recipient’s email is deactivated Inactive
Whether the recipient’s email address can be reactivated CanActivate
If a message dump is available DumpAvailable

Rebound #

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.

Screenshot of rebound JavaScript snippet
You can even customize this notifications appearance and messaging without writing any code.

Open Tracking webhook #

You will notice some open tracking information available with the Postmark open tracking webhook that does not exist in Mandrill’s events webhook:

  • Whether this open event was the first time the email was opened

Open Tracking Webhook Fields Map #

Parameter MandrillPostmark
Recipient’s email address email Recipient
Tag/Category tagsTag
Timestamp of when open occurred tsReceivedAt
Email Identifier _id MessageID
User Agent uaUserAgent
IP Address of recipient when they opened the email ip Geo → IP
Platform uaPlatform
Email client used to open the email uaClient
Geographic Location locationGeo
Whether this was the first open for this email FirstOpen

Click Tracking webhook #

You will notice some click tracking information available with the Postmark click tracking webhook that does not exist in Mandrill’s events webhook:

  • The platform the recipient was using (mobile, desktop, webmail) when they clicked the link
  • The geographic location the recipient was in, including the region, country, city, zip code, and coordinates
  • The email client or browser and version the recipient was using when they clicked a link in the email
  • The IP address of the recipient when the link was clicked

Click Tracking Webhook Fields Map #

Recipient’s email addressemailRecipient
Timestamp of when click occurredtsReceivedAt
Email Identifier_idMessageID
User Agent
IP Address of recipient when they clicked the email
Geo → IP
Email client used when a link was clickedClient
Geographic LocationGeo
Click location (HTML or Plain Text email part)ClickLocation
URL that was clickedurlOriginalLink

Chapter 7

UI Overview#

Getting familiar with the Postmark web app

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, Setup Instructions, and Settings, which are unique for each message stream.

Servers #

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. Unused servers will be greyed out, for easy identification of which servers you may want to delete or repurpose.

A screenshot of Postmark's servers.
You can use servers in Postmark to group logically related email activity by domains, environments, or other factors.

Statistics #

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 (inbound or transactional) 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 the transactional message stream is the sending volume, link tracking metrics (if enabled), open tracking metrics (if enabled), and bounce/spam complaint metrics. The inbound message stream's statistics page includes metrics on the number of successfully processed emails and failures.

Screenshot of accessing a message stream's statistics.
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 (inbound or outbound) you are interested in to be taken to its overview page.
Screenshot of a transactional message stream's statistics tab.
Statistics can be filtered by date and tag to show the levels of engagement for various groups of emails or all emails.

Activity #

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 transactional 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 transactional 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:

  • Email processed - light green
  • Email delivered - green
  • Email opened - blue
  • Link clicked - purple
  • Bounce/spam complaint - red
  • Message queued - yellow
Screenshot of an example transactional stream activity feed showing emails sent, opened, clicked, bounced, or marked as spam.
The events activity stream will show emails, opens, bounces, clicks, and spam complaints.
Screenshot of the detailed view of an email.
In addition to message events, Postmark stores the full content (both plain text and HTML) of emails for 45 days.
Screenshot of an email with a bounce notification and the option to reactivate.
When an email bounces, Postmark provides a detailed explanation from the server response as well as the option to reactivate delivery. You can also reactivate delivery for bounced addresses using the API.

Templates #

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 easily 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.

Screenshot of the choice of templates or the option to code your own templates.
Postmark includes a variety of pre-built and well-tested templates to make getting started easier. They include Welcome emails, Password reset, Receipts, Invoices, and more.

Settings #

The Settings tab in a server lets you modify the server’s name and color. It is also where you can delete a server that is no longer being used.

Screenshot of server settings featuring the server name, a color, and the option to delete the server.
The main server settings let you rename your server as well as change the server's representative color.

API Tokens #

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.

Screenshot of example server credentials for the server API.
The Server credentials tabs provides a unique API token for the server.

Managing Account Settings #

The account page is where you can add emergency contacts in case we need to reach you regarding your account and have not heard back from the owner, set up billing notifications, mange your account API tokens, manage your plan subscription, and other administrative features.

Screenshot of account settings like emergency contacts and billing notification contacts.
From the account settings, you can add emergency contacts as well as billing notification contacts.

Users and Permissions #

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.

Screenshot of the users and permissions list with an owner and an admin showing server-level permissions.
Users and permissions can be managed to allow full or read-only access to individual servers.
Screenshot of advanced user permissions management.
You can control whether someone has access to the full account or individual servers, and with each individual server, you can control whether they have full access or read only access.

Chapter 8


It’s time to switch

Dive Deeper #

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.

Status information #

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.

Say hello! #

We love to help. Feel free to reach out via email or through our contact form, Twitter (@postmarkapp), or even give us a call at 1-855-286-7373. Or, if you have questions or need advice, you can schedule time directly with Rian, the Postmark product manager.

Welcome aboard #

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!

Still have questions?

  • Brian Kerr Brian

Ask us anything! We’re eager to help you with any problem or question you have…

Schedule a call