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 →

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

/templates/{templateid}

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 →

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

/templates

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

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 →

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

/templates/{templateid}

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

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 →

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

/templates

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 →

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

/templates/{templateid}

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 →

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

/templates/validate

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.
HtmlBody 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.
TextBody 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 bool 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 →

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

/email/withTemplate/

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