Two paper planes. One white and one yellow.

SendGrid Migration Guide

Everything you need to know about moving from SendGrid to Postmark

Table of Contents

Chapter 1

Introduction#

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

It includes details on differences between Postmark and SendGrid’s APIs, sending outbound emails, processing inbound emails, UI differences, and webhooks.

Key differences between SendGrid and Postmark #

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

  • Postmark does not allow anyone to send marketing or bulk email, whereas SendGrid does. If you were sending your marketing and/or bulk email through SendGrid 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.
  • Postmark’s APIs do not have XML support, all requests and responses will be in JSON.
  • Postmark does not have a reseller program and there are no Reseller APIs available.
  • Postmark uses a pay as you go credits model instead of subscriptions/plans. See our pricing page for more details. One credit is used per email sent/received and credits never expire.
  • 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.

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.


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 SendGrid API Name Postmark API Name
Sending Emails Mail Email
Managing Bounces Bounces, Blocks, Spam Reports, Invalid Emails Bounce
Managing Templates Transactional Templates Templates
Managing Sending Settings Filter Commands, Filter Settings (account wide) Server
Managing Servers Servers
Managing Sent Emails Messages
Managing Inbound Emails Messages
Manage email domains you can send from Domains
Manage email addresses you can send from Sender Signatures
Sending Statistics Statistics Stats
Managing User Profiles Profile
Manage Users Users
Managing IP Pools IP Management

Chapter 4

Sending Outbound Emails#

Start sending through Postmark

Similarities to SendGrid

  • Sending via a REST API and/or SMTP supported
  • Like SendGrid’s sink.sendgrid.net 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.

Differences from SendGrid

  • Postmark does not have an SMTP API to be used for special sending instructions when sending with SMTP.
  • Postmark supports both HTTP and HTTPS for API endpoints, whereas SendGrid requires HTTPS.
  • Postmark’s outbound message size limit is 10 MB including attachments, SendGrid’s limit is 30 MB.
  • Postmark messages can have up to 50 recipients in a single message, SendGrid can have up to 1,000.
  • SendGrid has a 3000 requests/second maximum rate at which you may call the Mail endpoint, Postmark does not have a hard limit for requests/second when sending email.

Configuration for Sending via SMTP #

When using SMTP with SendGrid, You can send 100 messages per SMTP connection at a time, and open up to 10 concurrent connections from a single server at a time. Postmark does not have a limit here.

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 SendGrid, you will need to switch over to using port 25, 2525, or 587 when using Postmark SMTP.

Setting SendGrid Postmark
SMTP Endpoint smtp.sendgrid.net smtp.postmarkapp.com
Port 465 for SSL, 25, 2525, or 587 for unencrypted/TLS 25, 2525, or 587
Username Uses the string “apikey” Server API Token
Password API Key w/ mail permissions enabled 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.

Message Level Options when Sending with SMTP #

All SendGrid options are specified in the JSON you set in a X-SMTPAPI header. Postmark does not have a single SMTP header that you have to add all your settings to. Instead, Postmark uses individual SMTP headers that you add to the email for setting specific options. Note that there are no list management options with Postmark SMTP sending, since Postmark can only be used for sending transactional email.

Option SendGrid Postmark
Bcc recipient filters → bcc Add as a Bcc w/ SMTP client
Click Tracking filters → clicktrack X-TrackLinks header
Open Tracking filters → opentrack X-PM-TrackOpens header
Tags X-PM-Tag header
DKIM filters → dkim Automatically uses DKIM signature if DKIM has been verified for the sending domain
Footer to add to bottom of email filters → footer Add the footer in your HTML body
Test email content for spam filters → spamcheck
Send using a template filters → templates 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 credentials tab.

Outbound Sending API JSON Fields Map #

Field Sendgrid Postmark
From email address(es) from → email From
From name from → name From
To email addresses personalizations → to → email To
To name personalizations → to → name To
Cc email addresses personalizations → cc → email Cc
Cc name personalizations → cc → name Cc
Bcc email address(es) personalizations →bcc → email Bcc
Bcc name personalizations → bcc → name Bcc
Subject line personalizations → subject Subject
Custom Tag Tag
HMTL Body content HtmlBody
Text Body content TextBody
ReplyTo email address reply_to → email ReplyTo
ReplyTo name reply_to → name ReplyTo
Custom Headers headers Headers
Template Identifier template_id TemplateId
Data to use in Template TemplateModel
Open Tracking tracking_settings → open_tracking TrackOpens
Link Tracking tracking_settings → click_tracking TrackLinks
Subscription Tracking tracking_settings → subscription_tracking
Attachments Attachments
Send At Time send_at
Google Analytics ganalytics
Batch Identifier batch_id
Specify how to handle unsubscribes asm
IP Pool to Send From ip_pool_name
Send API Request w/o Sending Email mail_settings → sandbox_mode Use POSTMARK_API_TEST for your X-Server-Authentication Token
Footer to add to bottom of email footer
Test email content for spam spam_check
Bypass unsubscribed recipients mail_settings → bypass_list_management

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 SendGrid Official Library Postmark Official Library Postmark Community Library
C# 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 Go Postmark Golang, Postmark.go
Grails Grails plugin
Grunt Postmark Grunt
Haskell Haskell Library
Java Java Java library, Spring's MailSender compatible implementation
Laravel Laravel Plugin
Magento Magento Extension
NodeJS NodeJS Postmark.js Node Email Templates
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 5

Processing Inbound Email#

Migrating your inbound email handling

Similarities

  • Postmark and SendGrid both process inbound emails by converting them to well-formed JSON, which is then posted to a URL that you specify for receiving inbound webhooks. 
  • Both implementations of inbound processing feature the ability to process emails sent to an entire sub-domain/domain using MX records.
  • Attachments are received as multipart/form-data in SendGrid, whereas Postmark will send attachments as base64.
  • Manage inbound webhook settings using an API (Parse API in Sendgrid, Server API in Postmark).

Differences

  • Postmark does not require that you set up inbound domain forwarding using an MX record in order to use inbound processing, though an MX record is required for inbound domain forwarding. 
  • 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 does not provide the option to use XML instead of JSON for processed emails.
  • You can use a wildcard in your MX record to have all sub-domains of your domain point to Postmark for inbound processing.
  • With Postmark, you do not have to use a verified (called “whitelabled” at SendGrid) domain for inbound domain forwarding.
  • Postmark requires that you enable SMTP (if not enabled already) on your Postmark server to use inbound processing.
  • SendGrid retries inbound message POSTs for 3 days when a non-200 response code is received. With Postmark, a total of 10 retries will be made over a 10.5 hour period, 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.
  • Postmark’s inbound message size limit including attachments is 25 MB, whereas SendGrid’s is 20 MB.

Inbound Processing JSON Fields Map #

Email Property SendGrid Postmark
Message Identifier for UI/API MessageID
HTML Body html HtmlBody
Plain Text Body text TextBody
Subject Line subject Subject
To Email Address to, envelope To, ToFull → Email
From Email Address from, envelope From, FromFull → Email
Cc Email Address Cc, CcFull → Email
Bcc Email Address Bcc, BccFull → Email
ReplyTo Email Address ReplyTo
Date headers → Date Date
Attachment Filename(s) attachment-info → filename Attachments → Name
Attachment Content Attachments → Content
Attachment Content-Type Attachments → ContentType
Attachment Size Attachments → ContentLength
Number of Attachments attachments Attachments (array size)
Headers headers Headers
Tag Tag
Mailbox Hash MailboxHash
Stripped Text Reply StrippedTextReply
Sender’s IP Address sender_ip
DKIM dkim Headers → DKIM-Signature
SPF SPF Headers → Received-SPF
SpamAssasssin Score spam_score Headers
SpamAssassin Report spam_report Headers → X-Spam-Tests
SpamAssassin Version Headers → X-Spam-Checker-Version
Character Sets charsets
Identified as Spam Headers → X-Spam-Status

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

Webhooks#

Migrating your webhooks handlers to Postmark

Both SendGrid and Postmark allow you to receive notifications as JSON POSTs to URLs you specify when specific events occur. While SendGrid has two webhook types (Event and Inbound Parse), Postmark splits up event types into multiple webhooks, which allows for some additional flexibility and separation of concerns when developing and setting URLs for receiving webhooks.

Webhook Types Map #

Event Type SendGrid Postmark
Inbound Processing Inbound Parse Webhook Inbound webhook
Delivery Event Webhook Delivery webhook
Bounces Event Webhook Bounce webhook
Spam Complaints Event Webhook Bounce webhook
Open tracking Event Webhook Open tracking webhook
Click tracking Event Webhook

There are some parameters used in the SendGrid Event Webhook that do not have comparable fields in Postmark’s webhooks, such as:

  • Whether TLS was used when sending the email
  • IP address used to send the email
  • If there was a certificate error on the receiving mail server when the email was sent
  • Newsletter and unsubscribe information (since Postmark does not support sending newsletters)
  • The SMTP message identifier for the sent email. Postmark includes the Postmark MessageID for identifying the email.

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 SendGrid Postmark
Recipient’s email address email Recipient
Tag/Category category Tag
Delivery time timestamp DeliveredAt
Receiving mail server’s response response Details
Email Identifier sg_message_id MessageID
Server used to send the email ServerID
TLS used when sending tls
IP address used for sending ip
Certificate error on the receiving mail server cert_err

Bounce webhook #

Postmark includes some additional information for bounce events that is not present in the SendGrid 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)
  • 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 SendGrid Postmark
Recipient’s email address email Email
From email address From
Email subject line Subject
Bounce timestamp timestamp BouncedAt
Tag/Category category Tag
Unique bounce identifier ID
Bounce Type type Type
Email Identifier sg_message_id MessageID
Server used to send the email ServerID
SMTP Status code status
Bounce details reason Details
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 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 SendGrid’s Event webhook:

  • The platform the recipient was using (mobile, desktop, webmail)
  • The geographic location the recipient was in, including the region, country, city, zip code, and coordinates
  • The email client or browser the recipient was using when they opened the email
  • How long the email was opened for
  • Whether this open event was the first time the email was opened

Open Tracking Webhook Fields Map #

Parameter SendGrid Postmark
Recipient’s email address email Recipient
Tag/Category category Tag
Timestamp of when open occurred timestamp ReceivedAt
Email Identifier sg_message_id MessageID
User Agent useragent UserAgent
IP Address of recipient when they opened the email ip Geo → IP
Platform Platform
Email client used to open the email Client
How long the email was opened ReadSeconds
Geographic Location Geo
Whether this was the first open for this email FirstOpen

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 SendGrid's dashboard and stats pages, though each server has its own statistics page rather than an overall account view like SendGrid. 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.

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 (called ‘Teammates’ in SendGrid) 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 SendGrid 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…