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 300 active templates. Requests that exceed this limit won't be processed.

Get a template Try → #

get

/templates/{templateid}

Request headers

Accept required

application/json

X-Postmark-Server-Token required

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

Example request with curl

curl "https://api.postmarkapp.com/templates/{templateid}" \
  -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.

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
}

Create a template Try → #

post

/templates

Request headers

Accept required

application/json

X-Postmark-Server-Token

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

Example request with curl

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

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.

TextBody 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.

HtmlBody 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.

Example body format

{
  "Name": "Onboarding Email",
  "Subject": "Hello from {{company.name}}!",
  "TextBody": "Hello, {{name}}!",
  "HtmlBody": "<html><body>Hello, {{name}}!</body></html>"
}

Response

TemplateId integer

ID of template

Name string

Name of template

Active boolean

Indicates that this template may be used for sending email.

Example response

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

{
  "TemplateId": 1234,
  "Name": "Onboarding Email",
  "Active": true
}

Edit a template Try → #

put

/templates/{templateid}

Request headers

Accept required

application/json

X-Postmark-Server-Token

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

Example request with curl

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

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.

TextBody 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.

HtmlBody 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.

Example body format

{
  "Name": "Onboarding Email",
  "Subject": "Hello from {{company.name}}!",
  "TextBody": "Hello, {{name}}!",
  "HtmlBody": "<html><body>Hello, {{name}}!</body></html>"
}

Response

TemplateId integer

ID of template

Name string

Name of template

Active boolean

Indicates that this template may be used for sending email.

Example response

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

{
  "TemplateId": 1234,
  "Name": "Onboarding Email",
  "Active": true
}

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 on the Credentials tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/templates?count=100&offset=0" \
  -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.

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": "Account Activation Email"
    },
    {
      "Active": true,
      "TemplateId": 5678,
      "Name": "Password Recovery Email"
    }]
}

Delete a template Try → #

delete

/templates/{templateid}

Request headers

Accept required

application/json

X-Postmark-Server-Token

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

Example request with curl

curl "https://api.postmarkapp.com/templates/{templateid}" \
  -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

X-Postmark-Server-Token

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

Example request with curl

curl "https://api.postmarkapp.com/templates/validate" \
  -X POST \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d "{ 'HtmlBody' : '<html><body>{{content}}</body</html>' }"

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.

TextBody string required

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

HtmlBody string required

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

TestRenderModel object

The 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.

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

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

Send email with template Try → #

post

/email/withTemplate/

Request headers

Accept required

application/json

X-Postmark-Server-Token required

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

Example request with curl

curl "https://api.postmarkapp.com/email/withTemplate" \
  -X POST \
  -H "Accept: 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.

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 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.

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

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

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