Skip to content

Templates

Jump to bottom
Igor Balos edited this page Mar 18, 2020 · 15 revisions

For these API requests you will need to use a server API token. Once you obtain it, you will need to use server API client.

server_token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
client = Postmark::ApiClient.new(server_token)

Get list of available templates or layouts

Retrieve templates and layouts list.

total_count, templates = client.get_templates(count: 2, offset: 0)

templates.first
# => {:active=>true, :template_id=>1, :name=>"Welcome email", :alias=>nil, :template_type=>"Layout"}

templates.last
# => {:active=>true, :template_id=>1, :name=>"Welcome email", :alias=>nil, :template_type=>"Standard"}

Retrieve layouts list.

total_count, templates = client.get_templates(count: 2, offset: 0, templateType: 'Layout')

templates.first
# => {:active=>true, :template_id=>1, :name=>"Welcome email", :alias=>nil, :template_type=>"Layout"}

templates.last
# => {:active=>true, :template_id=>1, :name=>"Welcome email", :alias=>nil, :template_type=>"Layout"}

Get template by ID

You can get the full template information by using it's ID or Alias. You can identify the template by either it's :template_id or :alias.

# get template by ID
client.get_template(1)

# => {:name=>"Welcome", :template_id=>1, :subject=>"Hello from {{product}}!", :html_body=>nil, :text_body=>"This is {{product}} email.", :associated_server_id=>1, :active=>true, :alias=>nil}

Get template or layout by Alias

# get template by Alias
client.get_template('test_alias')

# => {:name=>"Welcome", :template_id=>1, :subject=>"Hello from {{product}}!", :html_body=>nil, :text_body=>"This is {{product}} email.", :associated_server_id=>1, :active=>true, :alias=>"test_alias"}

Create a new template or layout

You can easily create template with create_template method:

client.create_template(name:'Welcome', 
                       alias: 'welcome-v2',
                       subject: 'Welcome email', 
                       html_body: '<html><body>Welcome, {{name}}!</body></html>', 
                       text_body: 'Welcome, {{name}}!')

# => {:template_type => 'Standard', :template_id=>2, :alias=>"welcome-v2", :name=>"Welcome", :active=>true, :layout_template => nil}

Similarly you can easily create layout.

client.create_template(template_type: 'Layout',
                       name:'Welcome',
                       alias: 'layout',
                       html_body: '<html><body>{{{@content}}}</body></html>',
                       text_body: '{{{@content}}}')
# => {:template_type: 'Layout', :template_id=>2, :alias=>"welcome-v2", :name=>"Welcome", :active=>true, :layout_template => nil}

Update template by ID

You can update template by identifying it by ID or Alias and providing template data you wish to update.

client.update_template(1, name: 'Welcome to our product')

# => {:template_id=>1, :alias=>null, :name=>"Welcome to our product", :active=>true}

Update template or layout by Alias

client.update_template('welcome-v2', name: 'Welcome to our product')

# => {:template_id=>2, :alias=>"welcome-v2", :name=>"Welcome to our product", :active=>true}

Delete template by ID

client.delete_template(2)

# => {:error_code=>0, :message=>"Template 2 removed."}

Delete template by Alias

client.delete_template('template_alias')

# => {:error_code=>0, :message=>"Template 2 removed."}

Validate template or layout

We also have an API endpoint to validate an example template provided and also provide an example structure for the template model to provide when sending with this template. Full information about this endpoint can be found at the Postmark API docs.

client.validate_template(html_body: '<html><body>Welcome to {{product}}, {{name}}!</body></html>')

# => {:all_content_is_valid=>true, :html_body=>{:content_is_valid=>true, :validation_errors=>[], :rendered_content=>"<html><head></head><body>Welcome to product_Value, name_Value!</body></html>"}, :text_body=>nil, :subject=>nil, :suggested_template_model=>{"product"=>"product_Value", "name"=>"name_Value"}}

client.validate_template(subject: '{{#each}}')

# => {:all_content_is_valid=>false, :html_body=>nil, :text_body=>nil, :subject=>{:content_is_valid=>false, :validation_errors=>[{:message=>"The 'each' block being opened requires a model path to be specified in the form '{#each <name>}'.", :line=>1, :character_position=>1}], :rendered_content=>nil}, :suggested_template_model=>nil}

Similarly you can validate layout.

client.validate_template(template_type: 'Layout', html_body: '<html><body>{{{@content}}}</body></html>', text_body: '{{{@content}}}')

# => {:all_content_is_valid=>true, :html_body=>{:content_is_valid=>true, :validation_errors=>[], :rendered_content=>"<html><head></head><body>[Template @content goes here]</body></html>"}, :text_body=>{:content_is_valid=>true, :validation_errors=>[], :rendered_content=>"[Template @content goes here]"}, :subject=>nil, :suggested_template_model=>{}}

Send email with template

The deliver_with_template method accepts almost all the same options as the regular deliver method with a few differences. First, you don't include :text_body, :html_body, or :subject as that data will be generated from your template. You will need to include :template_id or :template_alias for the template you want to use and :template_model which is a hash containing the variables your template requires. The minimum request info required would look like:

client.deliver_with_template(from: '[email protected]',
                             to: 'Penny <[email protected]>',
                             template_id: 123,
                             template_model: {
                               name: 'Penny',
                               message: 'Bazinga!'
                             })

You can still include the other fields that deliver method accepts such as :attachments, :tag, :track_opens, :message_stream and others. You can view the full list of options at Postmark API Docs

Send batch email with templates

When you have many templated emails to send at once (e.g., you need to alert multiple users on an event), the deliver_in_batches_with_templates method can come in handy. Provide it with an array of message attributes accepted by deliver_with_template and it will send them all in batches.

messages = [
  {
    template_id: 42,
    to: '[email protected]',
    # other attributes
  },
  {
    template_id: 43,
    to: '[email protected]',
    # other attributes
  },
  # ...
]
client.deliver_in_batches_with_templates(messages)

# => [{:to=>"[email protected]", :submitted_at=>"2018-03-14T09:56:50.4288265-04:00", :message_id=>"59fdb4f9-xxxx-xxxx-xxxx-b2ec518f3892", :error_code=>0, :message=>"OK"}, {:error_code=>1101, :message=>"The 'TemplateId' associated with this request is not valid or was not found."}]

Postmark Ruby Gem.

For additional information about the capabilities of the Postmark API, see Postmark Developers Documentation.

General information

API overview

Clone this wiki locally