Overview

Integration

User guide

API reference

Webhooks

Email API

This endpoint is solely responsible for sending emails with Postmark through a specific server. Please note that the batch endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.

Send a single email Try → #

post

/email

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

Example request with curl

curl "https://api.postmarkapp.com/email" \
  -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",
  "Subject": "Postmark test",
  "TextBody": "Hello dear Postmark user.",
  "HtmlBody": "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
  "MessageStream": "outbound"
}'

Body format

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

Email subject
Tag string

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

If no TextBody specified HTML email message
TextBody string required

If no HtmlBody specified Plain text email message
ReplyTo string

Reply To override email address. Defaults to the Reply To set in the sender signature. Multiple addresses are comma separated.
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
Metadata object

Custom metadata key/value pairs.
Attachments array

List of attachments
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

{
  "From": "sender@example.com",
  "To": "receiver@example.com",
  "Cc": "copied@example.com",
  "Bcc": "blind-copied@example.com",
  "Subject": "Test",
  "Tag": "Invitation",
  "HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
  "TextBody": "Hello",
  "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"
    },
    {
      "Name": "image.jpg",
      "ContentID": "cid:image.jpg",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "image/jpeg"
    }
  ],
  "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 emails Try → #

post

/email/batch

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/batch" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '[
  {
    "From": "sender@example.com",
    "To": "receiver1@example.com",
    "Subject": "Postmark test #1",
    "TextBody": "Hello dear Postmark user.",
    "HtmlBody": "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
    "MessageStream": "outbound"
  },
  {
    "From": "sender@example.com",
    "To": "receiver2@example.com",
    "Subject": "Postmark test #2",
    "TextBody": "Hello dear Postmark user.",
    "HtmlBody": "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
    "MessageStream": "outbound"
  }
]'

Body format

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

Email subject
Tag string

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

If no TextBody specified HTML email message
TextBody string

If no HtmlBody specified Plain text email message
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
Metadata object

Custom metadata key/value pairs.
Attachments array

List of attachments
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

[
  {
    "From": "sender@example.com",
    "To": "receiver1@example.com",
    "Cc": "copied@example.com",
    "Bcc": "blank-copied@example.com",
    "Subject": "Test",
    "Tag": "Invitation",
    "HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
    "TextBody": "Hello",
    "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"
      },
     {
       "Name": "image.jpg",
       "ContentID": "cid:image.jpg",
       "Content": "dGVzdCBjb250ZW50",
       "ContentType": "image/jpeg"
     }
    ],
    "Metadata": {
      "color":"green",
      "client-id":"12345"
   },
    "MessageStream": "outbound"
  },
  {
    "From": "sender@example.com",
    "To": "receiver2@example.com",
    "Cc": "copied@example.com",
    "Bcc": "blank-copied@example.com",
    "Subject": "Test",
    "Tag": "Invitation",
    "HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
    "TextBody": "Hello",
    "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"
      },
     {
       "Name": "image.jpg",
       "ContentID": "cid:image.jpg",
       "Content": "dGVzdCBjb250ZW50",
       "ContentType": "image/jpeg"
     }
    ],
    "Metadata": {
      "color":"blue",
      "client-id":"54321"
   },
    "MessageStream": "outbound"
  }
]

Response

Please note that the /batch 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. "
  }
]