Overview

Integration

User guide

API reference

Webhooks

Templates API

Lets you manage templates for a specific server.

Please note that a Server may have up to 100 templates. Requests that exceed this limit won't be processed. Please contact support if you need more Templates within a Server.

Send email with template Try → #

post

/email/withTemplate/

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found on the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/email/withTemplate" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
          "From": "sender@example.com",
          "To": "receiver@example.com",
          "TemplateId": 1234,
          "TemplateModel": {
              "user_name": "John Smith"
          }
      }'

Body format

TemplateId integer required

The template to use when sending this message. Required if TemplateAlias is not specified.
TemplateAlias string required

The alias of a template to use when sending this message. Required if TemplateId is not specified.
TemplateModel object required

The model to be applied to the specified template to generate HtmlBody, TextBody, and Subject.
InlineCss boolean

By default, if the specified template contains an HTMLBody, we will apply the style blocks as inline attributes to the rendered HTML content. You may opt-out of this behavior by passing false for this request field.
From string required

The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>". Punctuation in the name would need to be escaped.
To string required

Recipient email address. Multiple addresses are comma separated. Max 50.
Cc string

Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc string

Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag string

Email tag that allows you to categorize outgoing emails and get detailed statistics. Max characters 1000.
ReplyTo string

Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers array

List of custom headers to include.
TrackOpens boolean

Activate open tracking for this email.
TrackLinks string

Activate link tracking for links in the HTML or Text bodies of this email. Possible options: None HtmlAndText HtmlOnly TextOnly
Attachments array

List of attachments
Metadata object

Custom metadata key/value pairs.
MessageStream string

Set message stream ID that's used for sending. If not provided, message will default to the outbound transactional stream.

Example body format

{
  "TemplateId": 1234,
  "TemplateModel": {
    "user_name": "John Smith",
    "company": {
      "name": "ACME"
    }
  },
  "InlineCss": true,
  "From": "sender@example.com",
  "To": "receiver@example.com",
  "Cc": "copied@example.com",
  "Bcc": "blank-copied@example.com",
  "Tag": "Invitation",
  "ReplyTo": "reply@example.com",
  "Headers": [
    {
      "Name": "CUSTOM-HEADER",
      "Value": "value"
    }
  ],
  "TrackOpens": true,
  "TrackLinks": "None",
  "Attachments": [
    {
      "Name": "readme.txt",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "text/plain"
    },
    {
      "Name": "report.pdf",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "application/octet-stream"
    }
  ],
  "Metadata": {
      "color":"blue",
      "client-id":"12345"
   },
   "MessageStream": "outbound"
}

Response

To string

Recipient email address
SubmittedAt string

Timestamp
MessageID string

ID of message
ErrorCode integer

API Error Codes
Message string

Response message

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

Send batch with templates Try → #

post

/email/batchWithTemplates

Request headers

Content-Type required

application/json
Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/email/batchWithTemplates" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
    "Messages": [
        {
            "From": "sender@example.com",
            "To": "receiver1@example.com",
            "TemplateId": 12345,
            "TemplateModel": {
                "fizz": "buzz"
            }
        },
        {
            "From": "sender@example.com",
            "To": "receiver2@example.com",
            "TemplateAlias": "welcome-notification",
            "TemplateModel": {
                "fizz": "buzz"
            }
        }
    ]
}'

Body format

Messages array required

The list of templates to send. Please note that we accept up to 500 messages per API call.
TemplateAlias string

The template to use for this message. This value is required if TemplateId is not supplied. If both are supplied, TemplateId will be used to select the template.
TemplateId integer

The template to use for this message. This value is required if TemplateAlias is not supplied. If both are supplied, TemplateId will be used to select the template.
From string required

The sender email address. Must have a registered and confirmed Sender Signature. To include a name, use the format "Full Name <sender@domain.com>". Punctuation in the name would need to be escaped.
To string required

Recipient email address. Multiple addresses are comma separated. Max 50.
Cc string

Cc recipient email address. Multiple addresses are comma separated. Max 50.
Bcc string

Bcc recipient email address. Multiple addresses are comma separated. Max 50.
Tag string

Email tag that allows you to categorize outgoing emails and get detailed statistics. Max characters 1000.
ReplyTo string

Reply To override email address. Defaults to the Reply To set in the sender signature.
Headers array

List of custom headers to include.
TrackOpens boolean

Activate open tracking for this email.
TrackLinks string

Activate link tracking for links in the HTML or Text bodies of this email. Possible options: None HtmlAndText HtmlOnly TextOnly
Attachments array

List of attachments
Metadata object

Custom metadata key/value pairs.
MessageStream string

Set message stream ID that's used for sending. If not provided, message will default to the outbound transactional stream.

Example body format

{
  "Messages": [
    {
      "From": "sender@example.com",
      "To": "receiver@example.com",
      "Cc": "copied@example.com",
      "Bcc": "blank-copied@example.com",
      "Tag": "Invitation",
      "ReplyTo": "reply@example.com",
      "TemplateAlias": "invitation-letter",
      "TemplateModel": {
        "fizz": "buzz"
      },
      "Headers": [
        {
          "Name": "CUSTOM-HEADER",
          "Value": "value"
        }
      ],
      "TrackOpens": true,
      "TrackLinks": "None",
      "Attachments": [
        {
          "Name": "readme.txt",
          "Content": "dGVzdCBjb250ZW50",
          "ContentType": "text/plain"
        },
        {
          "Name": "report.pdf",
          "Content": "dGVzdCBjb250ZW50",
          "ContentType": "application/octet-stream"
        },
        {
          "Name": "image.jpg",
          "ContentID": "cid:image.jpg",
          "Content": "dGVzdCBjb250ZW50",
          "ContentType": "image/jpeg"
        }
      ],
      "Metadata": {
        "color":"blue",
        "client-id":"12345"
      },
     "MessageStream": "outbound"
    }
  ]
}

Response

Please note that the /batchWithTemplates endpoint will return a 200-level http status, even when validation for individual messages may fail. Users of these endpoints should check the success and error code for each message in the response from our API (the results are ordered the same as the original messages).

To string

Recipient email address
SubmittedAt string

Timestamp
MessageID string

ID of message
ErrorCode integer

API Error Codes
Message string

Response message

Example response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "ErrorCode": 0,
    "Message": "OK",
    "MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
    "SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
    "To": "receiver1@example.com"
  },
  {
    "ErrorCode": 406,
    "Message": "You tried to send to a recipient that has been marked as inactive. Found inactive addresses: example@example.com. Inactive recipients are ones that have generated a hard bounce, a spam complaint, or a manual suppression.",
  }
]

Push templates to another server Try → #

put

/templates/push

Push all templates with changes to another server. If the template already exists on the destination server, the template will be updated. If the template does not exist on the destination server, it will be created and assigned the alias of the template on the source server.

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Account-Token required

This request requires account level privileges. Only accessible by the account owner, this token can be found on the API Tokens tab of your Postmark account.

Example request with curl

curl "https://api.postmarkapp.com/templates/push" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token" \
  -d '{
          "SourceServerID": 997287,
          "DestinationServerID": 997285,
          "PerformChanges": true
      }'

Body format

SourceServerID string required

Server ID of the source server containing the templates that will be pushed.
DestinationServerID string required

Server ID of the destination server receiving the pushed templates.
PerformChanges boolean required

Specifies whether to push templates to destination server or not. This parameter can be set to false to allow you to do a "dry-run" of the push operation so that you can see which templates would be created or updated from this operation.

Example body format

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

Response

TotalCount integer

Indicates the total number of template changes.
Templates object

List of affected templates on the destination server.
Action string

Value will be Create or Edit, depending on whether the pushed template will modify an existing template on the destination server or create a new template.
Alias string

Template alias
Name string

Name of the template.
TemplateType string

The type of template in changeset pushed. Possible options: Standard or Layout.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "TotalCount": 1,
    "Templates": [
        {
            "Action": "Create",
            "TemplateId": 7270,
            "Alias": "comment-notification",
            "Name": "Comment notification",
            "TemplateType": "Standard"
        }
    ]
}

Get a template Try → #

get

/templates/{templateIdOrAlias}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

TemplateId integer

ID of template
Name string

Name of template
Subject string

The content to use for the Subject when this template is used to send email.
HtmlBody string

The content to use for the HtmlBody when this template is used to send email.
TextBody string

The content to use for the TextBody when this template is used to send email.
AssociatedServerId integer

The ID of the Server with which this template is associated.
Active boolean

Indicates that this template may be used for sending email.
Alias string

An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
TemplateType string

The type of template returned. Possible options: Standard or Layout.
LayoutTemplate string

If returned template is a standard template and uses a layout template, this returns the layout template alias. null if no layout.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Name": "Onboarding Email",
  "TemplateId": 1234,
  "Subject": "Hi there, {{Name}}",
  "HtmlBody": "Hello dear Postmark user. {{Name}}",
  "TextBody": "{{Name}} is a {{Occupation}}",
  "AssociatedServerId": 1,
  "Active": false,
  "Alias": "onboarding-v1",
  "TemplateType": "Standard",
  "LayoutTemplate": "my-layout"
},
{
  "Name": "Receipt Email",
  "TemplateId": 1235,
  "Subject": "Receipt for {{ product_name }}",
  "HtmlBody": "<body><span class="preheader">This is a receipt for {{ product_name }}...",
  "TextBody": "This is a receipt for {{ product_name }}",
  "AssociatedServerId": 1,
  "Active": false,
  "Alias": "receipt-v1",
  "TemplateType": "Standard",
  "LayoutTemplate": "null"
}

Create a template Try → #

post

/templates

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
          "Name": "Welcome Email",
          "Alias": "onboarding-v1",
          "HtmlBody": "<html><body>Hello{{name}}<body><html>",
          "TextBody": "Hello, {{name}}",
          "Subject": "Hello, from {{company.name}}",
          "TemplateType": "Standard",
          "LayoutTemplate": "my-layout"
      }'

Body format

Name string required

Name of template
Alias string

An optional string you can provide to identify this template (if creating a standard template). Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
HtmlBody string required

The content to use for the HtmlBody when this template is used to send email. Required if TextBody is not specified. See our template language documentation for more information on the syntax for this field.

A content placeholder is required to be present for a layout template, and can be placed only once in the HtmlBody.
TextBody string required

The content to use for the TextBody when this template is used to send email. Required if HtmlBody is not specified. See our template language documentation for more information on the syntax for this field.

A content placeholder is required to be present for a layout template, and can be placed only once in the TextBody.
Subject string required

The content to use for the Subject when this template is used to send email. Subject is only required on standard templates. See our template language documentation for more information on the syntax for this field.

Subjects are not allowed for layout templates and will result in an API error.
TemplateType string

Available when creating a template. To set if a template is standard template or layout template. Possible options: Standard or Layout. Defaults to Standard. After creation, it's not possible to change a template type.
LayoutTemplate string

An optional string to specify which Layout Template to use (via layout alias) for an existing Layout Template when creating a standard template.

Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.

The API will throw an error if LayoutTemplate is present and the template type is a Layout. This field can also be set to null by using an empty string "".

Example body format

{
  "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"
}

Response

TemplateId integer

ID of template.
Name string

Name of template.
Active boolean

Indicates that this template may be used for sending email.
Alias string

Template alias (or null if not specified).
TemplateType string

Type of template. Possible options: Standard or Layout.
LayoutTemplate string

Alias of layout used.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

Edit a template Try → #

put

/templates/{templateIdOrAlias}

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
          "Name": "Onboarding Email",
          "Subject": "Hello from {{company.name}}!",
          "TextBody": "Hello, {{name}}!",
          "HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
          "Alias": "welcome-v1"
      }'

Body format

Name string required

Name of template
Subject string required

The content to use for the Subject when this template is used to send email. See our template language documentation for more information on the syntax for this field.
HtmlBody string required

The content to use for the HtmlBody when this template is used to send email. Required if TextBody is not specified. See our template language documentation for more information on the syntax for this field.
TextBody string required

The content to use for the TextBody when this template is used to send email. Required if HtmlBody is not specified. See our template language documentation for more information on the syntax for this field.
Alias string

An optional string you can provide to identify this Template. Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.
LayoutTemplate string

An optional string to specify which Layout Template to use (via layout alias) for an existing Layout Template when creating a standard template.

Allowed characters are numbers, ASCII letters, and ‘.’, ‘-’, ‘_’ characters, and the string has to start with a letter.

The API will throw an error if LayoutTemplate is present and the template type is a Layout. This field can also be set to null by using an empty string "".

Example body format

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

Response

TemplateId integer

ID of template
Name string

Name of template
Active boolean

Indicates that this template may be used for sending email.
Alias string

Template alias (or null if not specified).

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

List templates Try → #

get

/templates

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

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

Querystring parameters

Count required

The number of templates to return.
Offset required

The number of templates to "skip" before returning results.
TemplateType

Filters templates based on template type (layout template or standard template). Possible options: All Standard Layout. Defaults to All.
LayoutTemplate

Filter results by layout alias.

Response

TotalCount integer

The total number of templates associated with the current server.
Templates array

A list of templates associated with this server.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "TotalCount": 2,
  "Templates": [
    {
      "Active": true,
      "TemplateId": 1234,
      "Name": "Password Recovery Email",
      "Alias": "password-recovery",
      "TemplateType": "Standard",
      "LayoutTemplate": "my-layout"
    },
    {
      "Active": true,
      "TemplateId": 5678,
      "Name": "Default Layout",
      "Alias": "my-layout",
      "TemplateType": "Layout",
      "LayoutTemplate": null
    }]
}

Delete a template Try → #

delete

/templates/{templateIdOrAlias}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
  -X DELETE \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ErrorCode integer

API Error Codes
Message string

Associated success or error message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

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

Validate a template Try → #

post

/templates/validate

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates/validate" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
          "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"
      }'

Body format

Subject string required

The subject content to validate. Must be specified if HtmlBody or TextBody are not. See our template language documentation for more information on the syntax for this field.
HtmlBody string required

The HTML body content to validate. Must be specified if TextBody or Subject are not. See our template language documentation for more information on the syntax for this field.

A content placeholder is required to be present to validate a layout template, and can be placed only once in the HtmlBody.
TextBody string required

The plain text body content to validate. Must be specified if Subject or HtmlBody are not. See our template language documentation for more information on the syntax for this field.

A content placeholder is required to be present to validate a layout template, and can be placed only once in the TextBody.
TestRenderModel object

The template model to be used when rendering test content.
InlineCssForHtmlTestRender boolean

When HtmlBody is specified, the test render will have style blocks inlined as style attributes on matching html elements. You may disable the css inlining behavior by passing false for this parameter.
TemplateType string

Validates templates based on template type (layout template or standard template). Possible options: Standard or Layout. Defaults to Standard.
LayoutTemplate string

An optional string to specify which layout template alias to use to validate a standard template. If not provided a standard template will not use a layout template.

Example body format

{
  "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"
}

Response

AllContentIsValid boolean

Indicates all of the template content that was submitted is parseable. Note, we do not "Validate" HTML content to match any HTML standards, simply that we are able to parse the markup, and inline styles.
ContentIsValid boolean

Whether the supplied content is parseable/renderable by the template system.
ValidationErrors array

An array of validation errors related to the content being validated. This property will never be null. An empty array indicates that there were no validation errors.

When the result contains errors, Line and CharacterPosition are the 1-based offsets where those errors start. Both of these values may be null if the location of the validation error cannot be determined.
RenderedContent string

Using the SuggestedTemplateModel and, if submitted, the TestRenderModel, the text content that would be produced by this template when the template content and model are combined.
SuggestedTemplateModel object

A JSON object structure that will provide information for all keys found in the template content submitted. If a TestRenderModel was submitted, it will be merged and returned with this model.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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"
  }
}