Using Postmark Templates

Out of the box, Rails’ ActionMailer comes with a rich toolkit for rendering email views on the server. However, you may prefer to use Postmark Templates instead for various reasons:

• Enabling everyone on the team to edit email templates.
• Being able to modify your templates without redeploying the app.
• Improving delivery performance by reducing the HTTP payload.
• Easy access to Postmark’s open source Transactional Email Templates.

The postmark-rails gem version 0.19.0 (and above) is here to help you! To create a Mailer with templates support, inherit from PostmarkRails::TemplatedMailer:

require 'postmark-rails/templated_mailer'

class MyMailer < PostmarkRails::TemplatedMailer
end

Alternatively (e.g., if you’d prefer to keep some shared code in ApplicationMailer), include a special mixin:

require 'postmark-rails/templated_mailer'

class MyMailer < ApplicationMailer
  include PostmarkRails::TemplatedMailerMixin
end

By default, when you define a mailer action, its name is treated as its template alias. Make sure a matching template exists in the server referenced by your API token.

def test
  # will use the "test" template
  mail to: 'recipient@example.org'
end

To override the default template alias, provide a postmark_template_alias header when you call #mail along with a template model for your template:

def test
  self.template_model = { product_name: 'Postmark', name: 'Chris N' }

  mail to: 'recipient@example.org', postmark_template_alias: 'cookies'
end

Other than that, Postmark’s templated mailers are just your regular mailers that support interceptors, delayed delivery, action and rescue hooks, and can be tested with your favorite testing framework.

Previews

Rails 5.0 and above comes with a special controller for previewing email templates locally. By default, the postmark-rails gem will try to present you with a helpful body and subject stubs like below:

Date: Thu, 10 Jan 2019 16:43:23 -0500
From: sender@example.org
To: recipient@example.org
Message-ID: 61fad914-eec1-4895-86d9-2f57496d4374
Subject: Postmark Template: "welcome"
Mime-Version: 1.0
Content-Type: text/plain;
 charset=UTF-8
Content-Transfer-Encoding: 7bit
postmark-template-alias: welcome

This message is using a Postmark template.

Alias: "welcome"
Model:
{
  "product_name": "Postmark",
  "name": "Chris N"
}

Use the #prerender method on this object to contact the Postmark API to pre-render the template.

Cheers,
Your friends at Postmark

If you have access to a Postmark API token, you may want to connect directly to the Postmark API for previewing your emails locally. To do that, create an initializer (e.g., config/initializers/postmark_templates.rb) with the following contents:

# Enables email previews via the Postmark API. The interceptor relies on
# the Postmark token being set for the current environment, which is
# normally defined in config/environments/application.rb or other
# environment-specific configs.
# 
# config.action_mailer.postmark_settings = { api_token: Rails.application.secrets.postmark_api_token }
#
if ActionMailer::Base.postmark_settings[:api_token].present?
  ActionMailer::Base.register_preview_interceptor(PostmarkRails::PreviewInterceptor)
end