How do I transition from the Heroku add-on to a stand alone account?

On June 30th, 2017, Postmark’s Heroku add-on will no longer be available in the Heroku marketplace and the integration will stop functioning. This means you will no longer be able to access your Postmark activity or send and process emails from the Heroku Postmark add-on after this date. Before then you will want to make sure you have successfully transitioned over to a standalone Postmark account. Although the transition process is quick, follow this guide to help ensure a successful switch to a standalone Postmark account.

Benefits of a standalone Postmark account

Multiple Servers

The Heroku Postmark add-on had a limit of one server per add-on. This could be a pain if you were managing multiple Heroku applications that were using Postmark. With a stand alone Postmark account, you can create as many servers as you need. Each server you create comes with a unique server API token, settings, and inbound email address.

More servers means you can now organize your email activity easily and separate sending for different environments such as development, staging, or production. If you are using Postmark in multiple Heroku applications, you can now create a server for each Heroku app, giving you one account for accessing all of your Postmark activity and settings.

User Accounts

Another limitation of Heroku add-on Postmark accounts was that you could not add additional users to your account. You may have wanted to add other users to your account to manage settings, create servers and sending domains, or view sending activity.

Your standalone Postmark account lets you add more users that can access your account. There are four levels of permissions available for Postmark users (Account Owner, Account Admin, Server Admin, and Server Viewer). See our help article for more information on setting a user’s permissions and what permissions options are available.

Account API Endpoints Access

Postmark’s Account API Token lets you perform account level actions with our Servers API, Domains API, and Sender Signatures API. When using the Heroku Postmark add-on, you did not have access to these APIs and their endpoints. With access to an Account API Token and related endpoints you can now create or edit your account’s domains, sender signatures, and servers.

Flexible Pricing

Stand alone Postmark accounts come with more monthly plan options for different volume requirements. Our pricing page details the cost per month for different volumes.

Transitioning sending to your new account

Sign up for a Postmark account here.

Create a server

Once you’ve created your account, Postmark creates a server in your account to get you started called My First Server. Servers in Postmark are a way to isolate your emails by client or environments such as staging or production.

If you plan on having production and development environments, you might setup a server called mydomain.com (dev) for now, and then you add mydomain.com (production). Of course, you can use whatever names help you keep things organized.

Add domains and sender signatures

Add any Sender Signatures or domains you were using for sending from your Heroku app(s) to your new Postmark account. Domains and sender signatures will need to be verified again in your new Postmark account.

If you had already verified the domain using DKIM, you will need to add the new DKIM record we generate in your new Postmark account to your DNS. You must add the new DKIM record we show in the new account to your DNS, in order to verify the domain for sending from your new account. This is because the new DKIM key will have a different selector and value than your DKIM key from the Heroku add-on account. If you need a refresher on verifying a domain, head here.

Update your Server API Token

Since you are already sending through Postmark from your Heroku applications you will now just need to update your Server API Tokens being used in your Heroku app(s). Server API tokens can be retrieved from the API Tokens tab of your servers in Postmark. Grab your new API token and be sure to update it everywhere it’s used in your codebase for sending emails through Postmark.

If you were using ENV['POSTMARK_API_TOKEN'] to pull your Postmark API token from your Heroku config, you can update it to your new token with this command from the Heroku CLI:

heroku config:set POSTMARK_API_TOKEN=ServerAPIToken

You can also update your Heroku variables from your Heroku dashboard if you prefer to use a UI. Just open up your app in your Heroku dashboard, click Settings and edit them in the Config Variables section.

How do I copy over my Templates to my new stand alone account?

You can use our Templates API to pull Templates from your Heroku account and push them into your new account. Here are the steps to take for each Template you want to transfer over:

1. Grab your Server API Token for your Postmark Heroku add-on.
2. Get the Template ID for the Template you want to transfer to your new account. You can find this by opening the Template in the UI.
3. Make a GET Template call. Use your Heroku account's Server API Token for the X-Postmark-Server-Token header. You will receive back JSON for the Template that has this format:

   {
     "Name": "Onboarding Email",
     "TemplateId": 1234,
     "Subject": "Hi there, {{Name}}",
     "HtmlBody": "Hello dear Postmark user. {{Name}}",
     "TextBody": "{{Name}} is a {{Occupation}}",
     "AssociatedServerId": 1,
     "Active": false
   }
   	

4. Delete the fields "TemplateId", "AssociatedServerId", and "Active" from the returned JSON. In our example the JSON would then become:

   {
     "Name": "Onboarding Email",
     "Subject": "Hi there, {{Name}}",
     "HtmlBody": "Hello dear Postmark user. {{Name}}",
     "TextBody": "{{Name}} is a {{Occupation}}"
   }
   	

5. Grab your Server API Token from the new account's Server you want to copy the Template to.
6. Use the modified JSON for the Template you retrieved in a POST new Template API call. Be sure to use your new Server's API Token for the X-Postmark-Server-Token header so the new Template is created in your new account. Keep in mind that the new Templates will have different Template IDs than they had in your Heroku add-on Postmark account.
7. If your Heroku add-on contains a lot of Templates you want to copy over, you can also use our List Templates API call to retrieve all of the Template IDs for your Templates at once. You can use this to programmatically transfer over all of your Templates that are in your Heroku add-on Postmark account.

What if I need help transitioning to a stand alone account?

Be sure to reach out to us at support@postmarkapp.com or connect with us in live chat if you need any help with the transition or have any questions about making the switch.