Managing Layouts with Postmark’s API

If you manage Templates through Postmark’s API, you’ll feel right at home managing your Layouts with Postmark’s API. That’s because Layouts use Postmark’s Template endpoints to manage different functions.

Not sure what Layouts are? Layouts let you generate reusable code for Templates in Postmark. Layouts are perfect for wrapping your email Templates with reusable CSS styles, headers, and footers. To learn more about Layouts check out our comprehensive help doc and blog post.

Before we dive into the endpoints that you can use with Layouts, here are some rules of the road:

The TemplateType parameter is the type of Template used. There are two types of Templates in Postmark: Standard and Layout.
It’s possible to associate a Standard Template with one Layout Template to take advantage of reusable elements. On the opposite side, it’s possible to associate a Layout Template with many Standard Templates letting the Templates use elements from the Layout Template.
The LayoutTemplate parameter is the alias for the Layout Template.

Send email with template

Using the Send email with template API call, you can send emails using Postmark’s templates. Including Standard Templates that use Layouts.

It’s not possible to send a Layout Template as an email. The TemplateId needs to reference a Standard Template.

For Standard Templates using Layout Template, the variables from the Layout Template are available to the Standard Template when using the TemplateModel API parameter.

Method: POST

Endpoint: https://api.postmarkapp.com/email/withTemplate

Example Body:

{
  "From": "sender@example.com",
  "To": "receiver@example.com",
   "TemplateId": 1234,
   "TemplateModel":  {
      "user_name": "John Smith"
    }
}

Example Response:

{
  "To": "receiver@example.com",
  "SubmittedAt": "2019-06-25T07:25:01.4178645-05:00",
  "MessageID": "0a129aee-e1cd-480d-b08d-4f48548ff48d",
  "ErrorCode": 0,
  "Message": "OK"
}

Creating and Updating a Template

Using the Create a template API call, you can add or update a Template in your Postmark account. Including updating a Layout Template.

When creating a Layout Template, a content placeholder(Example: {{{ @content }}}) is required exactly once in the TextBody and HtmlBody. The content placeholder cannot be placed in a Standard Template. The Subject parameter is not allowed for a Layout Template.

Method: POST

Endpoint: https://api.postmarkapp.com/templates

Example Body:

{
  "Name": "Onboarding Email",
  "Subject": "Hello from {{company.name}}!",
  "TextBody": "Hello, {{name}}!",
  "HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
  "TemplateType": "Standard",
  "Alias": "onboarding-v1",
  "LayoutTemplate": "my-layout"
}

Example Response:

{
  "TemplateId": 1234,
  "Name": "Onboarding Email",
  "Active": true,
  "Alias": "onboarding-v1",
  "TemplateType": "Standard",
  "LayoutTemplate": "my-layout"
}

Validating a Template

The Validate a Template API call tests Template content to confirm it’s valid. Including validating a Layout Template.

When validating a Layout Template, a content placeholder(Example: {{{ @content }}}) is required exactly once in the TextBody and HtmlBody — After validating, the content placehoder is returned as:[Template @content goes here]. The content placeholder cannot be placed in a Standard Template. The Subject parameter is not allowed for a Layout Template.

Method: POST

Endpoint: https://api.postmarkapp.com/templates/validate

Example Body:

{
  "Subject": "{{#company}}{{name}}{{/company}} {{subjectHeadline}}",
  "HtmlBody": "{{#company}}{{address}}{{/company}}{{#each person}} {{name}} {{/each}}",
  "TextBody": "{{#company}}{{phone}}{{/company}}{{#each person}} {{name}} {{/each}}",
  "TestRenderModel": {
    "userName": "bobby joe"
    },
  "TemplateType": "Standard",
  "LayoutTemplate": "my-layout"
}

Example Response:

{
  "AllContentIsValid": true,
  "HtmlBody": {
    "ContentIsValid": true,
    "ValidationErrors": [],
    "RenderedContent": "address_Value name_Value "
  },
  "TextBody": {
    "ContentIsValid": true,
    "ValidationErrors": [
      {
        "Message": "The syntax for this template is invalid.",
        "Line": 1,
        "CharacterPosition": 1
      }
    ],
    "RenderedContent": "phone_Value name_Value "
  },
  "Subject": {
    "ContentIsValid": true,
    "ValidationErrors": [],
    "RenderedContent": "name_Value subjectHeadline_Value"
  },
  "SuggestedTemplateModel": {
    "userName": "bobby joe",
    "company": {
      "address": "address_Value",
      "phone": "phone_Value",
      "name": "name_Value"
    },
    "person": [
      {
        "name": "name_Value"
      }
    ],
    "subjectHeadline": "subjectHeadline_Value"
  }
}

List Templates

The List Templates API call will list all Templates on a Server.

An optional querystring parameter of TemplateType returns Templates based on their type ( Standard | Layout | All). The default is All.

A second optional querystring parameter of LayoutTemplate based on Layout alias returns Standard and Layout Templates associated with a specific Layout alias.

Method: GET

Endpoint: https://api.postmarkapp.com/templates

No body is needed for this API call. For example:

curl "https://api.postmarkapp.com/templates?count=100&offset=0&TemplateType=All" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

It will return a body like the following:

{
 "TotalCount": 2,
 "Templates": [{
    "Active": true,
    "TemplateId": 1234,
    "Name": "Account Activation Email",
    "Alias": "alias-1",
    "TemplateType": "Standard",
    "LayoutTemplate": "my-layout" 
},   
{
    "Active": true,
    "TemplateId": 5678,
    "Name": "Default Layout",
    "Alias": "layout",
    "TemplateType": "Layout",
    "LayoutTemplate": null
  }]
}

Push templates to another server

With the Push templates to another server API call, it’s possible to Push Standard and Layout Templates to another server.

Use this option for programmatically keeping your templates in sync across multiple environments or giving your users a way to sync template changes from your own UI.

When pushing, each Template type must have a unique alias. For example, it’s not possible to push a Layout Template with an alias of“welcome-email” to a server that has a Standard Template with an alias of“welcome-email”.

Method: PUT

Endpoint: https://api.postmarkapp.com/templates/push

Example Body:

{
  "SourceServerID": 997287,
  "DestinationServerID":997285,
  "PerformChanges": true
}

Example response:

{
  "Action": "Create",
  "TemplateId": 7270,
  "Alias": "comment-notification",
  "Name": "Comment notification",
  "TemplateType": "Standard"
}

Deleting a Template

If you need to delete a Standard or Layout Template in your server, you can use the Delete a Template API call.

Deleting a Layout Template will fail if the Layout has dependent Standard Templates.

Method: DELETE

Endpoint: https://api.postmarkapp.com/templates/{templateIdOrAlias}

No body is needed for this API call. It will return a response like the following example:

{
  "ErrorCode": 0, 
  "Message": "Template 1234 removed."
}

Send email with template

Creating and Updating a Template

Validating a Template

List Templates

Push templates to another server

Deleting a Template

Still need some help?