Two paper planes. One white and one yellow.

Mailgun Migration Guide

Everything you need to know about moving from Mailgun to Postmark

Table of Contents

Chapter 1

Introduction#

Key differences between Mailgun 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 Mailgun. This guide will detail some of the differences and similarities between Mailgun and Postmark, as well as give some useful tips for migrating to Postmark from Mailgun. 

It includes details on differences between Postmark and Mailgun’s APIs, sending outbound emails, processing inbound emails, UI differences, and webhooks. For quick reference, we have included tables where possible to equate Mailgun functionality and JSON fields to their comparable functionality and fields in Postmark.

Key differences between Mailgun and Postmark #

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

  • Postmark does not allow anyone to send marketing or bulk email, whereas Mailgun does. If you were sending your marketing and/or bulk email through Mailgun 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 adding unsubscribe links to your emails.
  • Successfully sent messages are stored for 45 days in Postmark (including the content). Bounces and spam complaints are stored indefinitely for troubleshooting purposes.
  • Postmark uses a pay as you go credits model instead of monthly billing for the previous month’s usage. See our pricing page for more details. One credit is used per email sent/received and credits never expire. Credits are purchased in advance and discounts are offered for large volume credit purchases.
  • All Postmark accounts have all features. There are no differences between a Postmark account that has made a credits purchase and one that hasn’t.
  • Postmark does not provide 10,000 free emails each month like Mailgun. We start you with 25,000 free credits when you create your account but you will need to purchase more credits once those are used.
  • We do not recommend using dedicated IPs for most senders but do move senders to dedicated IPs at no additional charge once they reach a significantly large volume.
  • Postmark does not have an email validation service. You can either continue using Mailgun’s validation endpoints or use a service like kickbox.io, to replace Mailgun’s email validator.
  • Postmark does not have a reseller program.

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 and sender signatures/domains. A server and a confirmed sender signature/verified domain are required for sending, so it is important to understand what they are used for.

Servers #

Each Postmark account contains servers. 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 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 DNS records lets you send from any email address on that domain.

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.

Tip: You can use any sender signature/verified domain for sending with any Postmark server. It is different from Mailgun where the sending domain and its activity are linked together.


Chapter 3

APIs#

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 Mailgun API Name Postmark API Name
Sending Emails MessagesEmail
Managing Bounces SuppressionsBounce
Managing Templates
Templates
Managing Sending Settings
Server
Managing Servers Servers
Managing Sent Emails Events Messages
Managing Inbound Emails Messages, Events Messages
Manage Inbound Processing SettingsRoutesServer
Manage email domains you can send from Domains
Domains
Manage email addresses you can send from Sender Signatures
Sending Statistics Stats Stats

Chapter 4

Sending Outbound Emails#

Start sending through Postmark

Similarities to Mailgun #

  • Sending via a REST API and/or SMTP supported
  • Like Mailgun’s sandbox domain, you can also send test emails to Postmark’s sink email address, test@blackhole.postmarkapp.com. Messages sent to this domain will be dropped on the receiving end but you will be able to see the delivery confirmation and message in your Activity. Also see our blog post about best practices when testing with your Postmark account.
  • Entire domains can be verified for sending using DKIM and SPF records

Differences from Mailgun #

  • Since Postmark only sends your email from high reputation, fully warmed up IP ranges, there is no chance of your sending rate being throttled or queued, which happens when Mailgun is sending from a newly allocated IP.
  • Mailgun allows sending messages using a MIME string through their API, which is not supported by Postmark. Emails must be sent through Postmark’s API using the MIME components (To, From, Subject, etc…)
  • Postmark’s outbound message size limit is 10 MB including attachments, Mailgun’s limit is 25 MB.
  • Postmark messages can have up to 50 recipients in a single message.
  • You must use a Server API Token for both your SMTP username and password when using SMTP with Postmark. You can generate as many Server API Tokens as you need.
  • Postmark does not support scheduling messages to be delivered later. Postmark sends the emails as soon as the request to send is received. If you want to schedule messages to be sent at a later date or time, you would need to do that in your codebase.
  • Templates are not supported with Postmark’s SMTP service and can only be used with the Postmark API.
  • Mailgun allows for adding metadata as JSON to sent emails using the v: prefix. Postmark only has the Tag field for adding additional data to messages that is returned from the API/webhooks. One Tag can be used on each message sent through Postmark.

Verifying Email Addresses and Domains for Sending #

Similar to Mailgun, domains in Postmark are verified for sending using DKIM and SPF records added to your domain’s DNS. Head over to our help article on verifying a domain for sending with Postmark for more detailed steps.

Postmark also includes an additional option for sending from a single email address that you can confirm using an emailed link. You can add individual addresses as Sender Signatures to your account, which does not require that you add DKIM and SPF records to send with that email address, though we always recommend setting up DKIM and SPF to maximize deliverability.
You can add and manage your sending domains and email addresses from the Sender Signature page in Postmark. Each domain you add has an Authentication page that includes the unique DNS record information for setting up DKIM, SPF, and a custom return-path.

Tip: Postmark does not allow sending from any public domain email addresses, such as Gmail, Yahoo, AOL, Outlook, Live, etc…

Configuration for Sending via SMTP #

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 credentials 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 Mailgun, you will need to switch over to using port 25, 2525, or 587 when using Postmark SMTP. We recommend using port 2525 or 587, since port 25 is sometimes blocked by ISPs.

Setting Mailgun Postmark
SMTP Endpoint smtp.mailgun.org smtp.postmarkapp.com
Port 465 for SSL, 25, 2525, or 587 for unencrypted/TLS 25, 2525, or 587
Username Domain’s SMTP username Server API Token
Password Domain’s SMTP password Server API Token
Authentication Unencrypted, SSL, TLS Plain text (unencrypted), CRAM-MD5, TLS

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

  • 147.75.195.176/30        [147.75.195.176 - 147.75.195.179]
  • 147.75.202.84/30          [147.75.202.84 - 147.75.202.87]
  • 147.75.205.84/30          [147.75.205.84 - 147.75.205.87] 

This IP list is maintained at http://support.postmarkapp.com/article/800-ips-for-firewalls.

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 credentials tab.

Outbound Sending API JSON Fields Map #

Field Mailgun Postmark
From email address(es) from From
From name from From
ReplyTo email address ReplyTo
ReplyTo name ReplyTo
To email addresses to To
To name to To
Cc email addresses cc Cc
Cc name cc Cc
Bcc email address(es) bcc Bcc
Bcc name bcc Bcc
Subject line subject Subject
Custom Tag o:tag Tag
HMTL Body html HtmlBody
Text Body text TextBody
Custom Headers h:X-My-Header Headers
Template Identifier TemplateId
Data to use in Template TemplateModel
Open Tracking o:tracking-opens TrackOpens
Link Tracking o:tracking-clicks TrackLinks
Attachments attachment Attachments
Inline attachments inline Attachments
Send At Time o:deliverytime
Send API Request without sending email o:testmode Use POSTMARK_API_TEST for your X-Postmark-Server-Token header value

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

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 Mailgun Official Library Postmark Official Library Postmark Community Library
C# 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
Erlang Erlang Library
Go Postmark Golang, Postmark.go
Grails Grails plugin
Grunt Postmark Grunt
Haskell Haskell Library
Java Java library, Spring's MailSender compatible implementation
Laravel Laravel Plugin
Magento Magento Extension
NodeJS Postmark.js Node Email Templates
Objective-C Standalone Objective-C Class
Perl Perl WWW::Postmark
Pharo Smalltalk Pharo Smalltalk, Postmark
PHP Mailgun PHP Postmark PHP PHP Community Libraries
PowerShell Postmark PowerShell Snap-in
Python Postmarker, pystmark, Postmark Python library
Ruby Mailgun Ruby Gem Postmark Ruby
Rails Postmark Rails
Scala Scala Client, Scala Library
WordPress Plugin Postmark for WordPress
Zend Postmark drop-in replacement for Zend



Chapter 5

Processing Inbound Email#

Migrating your inbound email handling

How inbound email processing is implemented is very different between Postmark and Mailgun. If you were using inbound processing with Mailgun and will be using Postmark for processing email once you migrate, this section is an important read.

Similarities #

  • Both Mailgun and Postmark feature the ability to process emails sent to an entire sub-domain or domain using MX records.
  • Postmark and Mailgun both have an inbound message size limit of 25 MB.
  • Inbound spam filtering using Spam Assassin is available in both Postmark and Mailgun.

Differences #

  • Postmark does not require you to take a specific store action (store() in Mailgun) to preserve inbound messages. We will automatically keep them in your Activity and available through the API for 45 days.
  • Postmark does not require that you set up inbound domain forwarding using an MX record in order to use inbound processing, though it is an option.
  • Each server you create in Postmark will come with a unique inbound email address (found in the credentials tab) that you can use to receive emails inbound at your webhook URL.  
  • Postmark receives inbound emails, converts them to JSON, and POSTs them to your inbound webhook URL, rather than processing them using Routes with the data being sent as form data.
  • Postmark does not have an option to receive inbound messages in their raw MIME form. Inbound messages will always be sent to your inbound webhook URL as well-formatted JSON.
  • You can use a wildcard in your MX record to have all sub-domains of your domain point to Postmark for inbound processing.
  • Postmark requires that you enable SMTP (if not enabled already) on your Postmark server to use inbound processing.
  • Mailgun will retry for 8 hours if there is a failure at the following intervals: 10 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour and 4 hours. With Postmark, 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 has a processing error.

Inbound Processing JSON Fields Map #

Email Property Mailgun Postmark
Message Identifier for UI/API MessageID
HTML Bodybody-htmlHtmlBody
Stripped HTML Body (no quotes)stripped-html
Plain Text Bodybody-plainTextBody
Subject LinesubjectSubject
To Email AddressrecipientTo, ToFull → Email
From Email AddressfromFrom, FromFull → Email
Cc Email Address Cc, CcFull → Email
Bcc Email Address Bcc, BccFull → Email
ReplyTo Email Address ReplyTo
Signaturestripped-signature
DatetimestampDate
Attachment Filename(s)attachment-info → filenameAttachments → Name
Attachment Contentattachment-xAttachments → Content
Attachment Content-Typeattachment-xAttachments → ContentType
Attachment Sizeattachment-xAttachments → ContentLength
Attachment Content-IDcontent-id-mapAttachments → ContentID
Number of Attachmentsattachment-countAttachments(array size)
Headersmessage-headersHeaders
Tag Tag
Mailbox Hash MailboxHash
Stripped Text Replystripped-textStrippedTextReply
DKIMX-Mailgun-Dkim-Check-ResultHeaders → DKIM-Signature
SPFX-Mailgun-SpfHeaders → Received-SPF
SpamAssasssin ScoreX-Mailgun-Sscore Headers
SpamAssassin Report Headers → X-Spam-Tests
SpamAssassin Version Headers → X-Spam-Checker-Version
Identified as SpamX-Mailgun-SflagHeaders → X-Spam-Status

Inbound Spam Filtering #

Postmark provides you with some additional control on how spam filtering is handled that is not available in Mailgun. In your inbound settings in the Postmark UI (Settings > Inbound) you can set your Spam Assassin threshold, which is the Spam Assassin score that needs to be reached or exceeded to trigger the spam filter (the higher the Spam Assassin score, the more likely the email is spam).

Inbound spam filtering settings
Inbound spam filtering settings

In the inbound spam filtering settings you can also add rules for blocking inbound messages from specific email addresses and domains.


Chapter 6

Webhooks#

Migrating your webhooks handlers to Postmark

Mailgun and Postmark both allow you to receive notifications as JSON POSTs to URLs you specify when specific events occur using webhooks. Postmark also does not yet have a link tracking webhook, so there is not a way to receive webhook notifications when someone clicks a link in emails you send.

Webhook Types Map #

Event Type Mailgun Postmark
Inbound Processing Inbound webhook
Delivery deliver, drop Delivery webhook
Bounces bounce, drop Bounce webhook
Spam Complaints spam Bounce webhook
Open tracking open Open tracking webhook
Click tracking click

Tip: Postmark uses an absolute time (e.g. 2017-06-23T14:14:39.3185236-04:00) for any webhook event timestamps, whereas Mailgun uses epoch time (number of seconds passed since January 1, 1970).

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.

Delivery webhook fields map #

Parameter Mailgun Postmark
Recipient’s email address recipient Recipient
Tag/Metadata “custom variables” Tag
Delivery time timestamp DeliveredAt
Receiving mail server’s response response Details
Email Identifier Message-Id MessageID
Email Source (Server in Postmark, Domain in Mailgun) domain ServerID
MIME Headers message-headers

Bounce webhook #

Postmark includes some additional information for bounce events that is not present in the Mailgun Bounce Event Webhook you should be aware of:

  • From email address
  • Subject of the email
  • Unique identifier for the bounce (used to reactivate a bounced email address using the Postmark Bounce API)
  • Unique identifier for the sent message (MessageID)
  • The Postmark server used to send the email
  • 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 Mailgun Postmark
Recipient’s email address recipient Email
From email address From
Email subject line Subject
Bounce timestamp timestamp BouncedAt
Tag/Metadata tag, “custom variables” Tag
Unique bounce identifier ID
Bounce Type event Type
Email Identifier MessageID
Server used to send the email domain ServerID
SMTP Status code code
Bounce details notification Details
Description of bounce error Description
MIME Headers message-headers
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 when receiving bounce event information.

Open Tracking webhook #

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

  • How long the email was opened for
  • Whether this open event was the first time the email was opened
  • Unique identifier for the sent email

Open tracking webhook fields map #

Parameter Mailgun Postmark
Recipient’s email address recipient Recipient
Tag/Metadata tag, “custom variables” Tag
Timestamp of when open occurred timestamp ReceivedAt
Email Identifier MessageID
User Agent user-agent UserAgent
IP Address of recipient when they opened the email ip Geo → IP
Country where email was opened country Geo → Country, Geo → CountryISOCode
Region where email was opened region Geo → Region, Geo → RegionISOCode
City where email was opened city Geo → City
Platform client-type Platform
Email client used to open the email client-name Client
OS recipient was using client-os OS
How long the email was opened ReadSeconds
Whether this was the first open for this email FirstOpen
Domain email was sent from  domain




Chapter 7

UI Overview#

Getting familiar with the Postmark app

When you log into Postmark you are placed in the Servers page, which shows each Server you have created. Each Server has tabs for Statistics, Activity, Templates, Settings, and Credentials.

Statistics #

To view statistics and metrics for a server, click on the server, which will take you to its statistics tab. 

The statistics tab is similar to Mailgun's Reporting page, though each server has its own statistics page rather than an overall account view like Mailgun. Included in the statistics area are the server's sending volume, processed (inbound) volume, link tracking metrics (if enabled), open tracking metrics (if enabled), and bounce metrics.

Postmark Statistics
Postmark UI Statistics Page

Activity #

To see your inbound and outbound activity in a server, click on the Activity tab. This area will show a detailed event view of that Server’s events, including sent, delivered, open events, spam complaints, bounces, etc... Use the search bar to look for emails by subject or email address.

Keep in mind that with Postmark, you do not need to store messages explicitly using a Route to keep them for more than three days. Postmark will automatically store all successfully sent messages for 45 days and all bounces indefinitely.

To see details for a particular event, click on the event. Some events included are sent emails, bounces, spam complaints, clicked links, and opened emails. Events in Activity are color coded to help you tell what occurred at a glance:

Email sent - green
Email opened - blue
Link clicked - purple
Bounce/spam complaint - red
Message queued - yellow

Examples of Event Types in Activity
Activity Events Examples

Templates #

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.

Templates Overview
Templates Overview

Settings #

The Settings tab lets you modify the server’s general, outbound, and inbound settings. This is where you can change the server’s name, color, webhook URLs, open tracking, and link tracking settings.

Server Settings
Server Settings

Credentials #

The Credentials tab shows you your server API token(s) and the server’s inbound email address. Use this tab to create/delete server API tokens and access your inbound email address.

Server Credentials
Server Credentials

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, purchase credits, and other administrative features.

Account Settings
Account Settings

Users and Permissions #

The Users page is where you add and manage 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.

Users Example
Users Example

Chapter 8

Conclusion#

It’s time to switch

You now have a solid understanding of how to transition over the core features you need in an ESP from Mailgun 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?

  • Dana Chaby Dana
  • Marek Loder Marek

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