Overview

Integration

User guide

API reference

Webhooks

Messages API

Lets you get all the details about any outbound or inbound message that you sent or received through a specific server. Messages expire after your retention period, which is 45 days by default (but retention can be customized from 7 to 365 days).

Outbound message search Try → #

get

/messages/outbound

The message search allows you to return up-to 10,000 messages in a search. For searches where you're looking to retrieve more than 10,000 messages use parameters like todate and fromdate to filter the messages.

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/messages/outbound?recipient=john.doe@yahoo.com&count=50&offset=0&tag=welcome&status=sent&todate=2015-01-12&fromdate=2015-01-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset required

Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient

Filter by the user who was receiving the email.
fromemail

Filter by the sender email address.
tag

Filter by tag
status

Filter by status (queued or sent / processed). Note that sent and processed will return the same results and can be used interchangeably.
todate

Filter messages up to the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
fromdate

Filter messages starting from the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
subject

Filter by email subject.
messagestream

Filter by message stream ID. If not provided, message will default to the 'outbound' transactional stream.
metadata_

Filter by metadata value. e.g. metadata_color. You can currently only search by a single metadata field at a time.

Response

TotalCount integer

Indicates the number of messages that matched the search criteria you specified. An email that is sent to multiple recipients is counted as 1 message in the Messages API, so TotalCount will be less than the total number of emails sent if some messages were sent to multiple recipients. On the Statistics page in the Postmark UI, a message sent to multiple recipients is counted once for each recipient, so the Sent number on the Statistics page indicates the total number of emails sent. This ensures accurate tracking of opens, link clicks, etc.
Messages array

List of objects that each represent a single message.

Example response

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

{
  "TotalCount": 194,
  "Messages": [
    {
      "Tag": "Invitation",
      "MessageID": "0ac29aee-e1cd-480d-b08d-4f48548ff48d",
      "MessageStream": "outbound",
      "To": [
        {
          "Email": "john.doe@yahoo.com",
          "Name": null
        }
      ],
      "Cc": [],
      "Bcc": [],
      "Recipients": [
        "john.doe@yahoo.com"
      ],
      "ReceivedAt": "2014-02-20T07:25:02.8782715-05:00",
      "From": "\"Joe\" <joe@domain.com>",
      "Subject": "staging",
      "Attachments": [],
      "Status": "Sent",
      "TrackOpens" : true,
      "TrackLinks" : "HtmlAndText",
      "Metadata": {
      "color": "blue",
      "client-id": "12345"
      },
      "Sandboxed": false
    }
  ]
}

Outbound message details Try → #

get

/messages/outbound/{messageid}/details

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/messages/outbound/{messageid}/details" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

TextBody string

Text body of the message.
HtmlBody string

Html body of the message.
Body string

Raw source of the message.
Tag string

Tags associated with this message.
MessageID string

Unique ID of the message.
MessageStream string

The outbound sending message stream for the message.
To string

List of objects that contain To recipients.
Cc string

List of objects that contain Cc recipients.
Bcc string

List of objects that contain Bcc recipients.
Recipients string

List of recipients.
ReceivedAt string

Timestamp of when the message was sent by Postmark. Corresponds with the Processed event in the UI.
From string

The sender email address.
Subject string

Email subject
Attachments array

List of objects that each represent an attachment.
Status string

Status of message in your Postmark Activity. Possible statuses: Sent, Processed, or Queued.
TrackOpens boolean

Indicates whether Open Tracking was enabled for this message.
TrackLinks string

Indicates whether Link Tracking was enabled for this message. Possible options: None HtmlAndText HtmlOnly TextOnly
Metadata array

Key/Value metadata pairs. You can currently only search by a single metadata field at a time.
Sandboxed boolean

Indicates whether the message was sandboxed or not. This is determined based on the Server type
MessageEvents array

List of summaries (MessageEvent) of things that have happened to this message. They can be SubscriptionChanged, Delivered, Transient, Opened, LinkClicked, or Bounced as shown in the type field.

Example response

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

{
  "TextBody": "Thank you for your order...",
  "HtmlBody": "<p>Thank you for your order...</p>",
  "Body": "SMTP dump data",
  "Tag": "product-orders",
  "MessageID": "07311c54-0687-4ab9-b034-b54b5bad88ba",
  "MessageStream": "outbound",
  "To": [
    {
      "Email": "john.doe@yahoo.com",
      "Name": null
    }
  ],
  "Cc": [],
  "Bcc": [],
  "Recipients": [
    "john.doe@yahoo.com"
  ],
  "ReceivedAt": "2014-02-14T11:12:54.8054242-05:00",
  "From": "\"Joe\" <joe@domain.com>",
  "Subject": "Parts Order #5454",
  "Attachments": [
      "myimage.png",
      "mypaper.doc"
  ],
  "Status": "Sent",
  "TrackOpens" : true,
  "TrackLinks" : "HtmlOnly",
  "Metadata": {
    "color": "blue",
    "client-id": "12345"
  },
  "Sandboxed": false,
  "MessageEvents": [
    {
      "Recipient": "john.doe@yahoo.com",
      "Type": "Delivered",
      "ReceivedAt": "2014-02-14T11:13:10.8054242-05:00",
      "Details": {
        "DeliveryMessage": "smtp;250 2.0.0 OK l10si21599969igu.63 - gsmtp",
        "DestinationServer": "yahoo-smtp-in.l.yahoo.com (433.899.888.26)",
        "DestinationIP": "173.194.74.256"
      }
    },
    {
      "Recipient": "john.doe@yahoo.com",
      "Type": "Transient",
      "ReceivedAt": "2014-02-14T11:12:10.8054242-05:00",
      "Details": {
        "DeliveryMessage": "smtp;400 Server cannot accept messages at this time, please try again later",
        "DestinationServer": "yahoo-smtp-in.l.yahoo.com (433.899.888.26)",
        "DestinationIP": "173.194.74.256"
      }
    },
    {
      "Recipient": "john.doe@yahoo.com",
      "Type": "Opened",
      "ReceivedAt": "2014-02-14T11:20:10.8054242-05:00",
      "Details": {
        "Summary": "Email opened with Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
      }
    },
    {
      "Recipient": "badrecipient@example.com",
      "Type": "Bounced",
      "ReceivedAt": "2014-02-14T11:20:15.8054242-05:00",
      "Details": {
        "Summary": "smtp;550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces.",
        "BounceID": "374814878"
      }
    },
    {
      "Recipient": "badrecipient@example.com",
      "Type": "SubscriptionChanged",
      "ReceivedAt": "2014-02-14T11:21:15.8054242-05:00",
      "Details": {
        "Origin": "Recipient",
        "SuppressSending": "True"
      }
    },
    {
      "Recipient":"click-tracked@example.com",
      "Type":"LinkClicked",
      "ReceivedAt":"2016-10-05T16:03:56.0000000-04:00",
      "Details":{
        "Summary":"Tracked Link 'https://example.com/a/path/to/the/future?queryValue=1&queryValue=2' was clicked from the HTMLBody.",
        "Link":"https://example.com/a/path/to/the/future?queryValue=1&queryValue=2",
        "ClickLocation":"HTML"
      }
    }
  ]
}

Outbound message dump Try → #

get

/messages/outbound/{messageid}/dump

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/messages/outbound/{messageid}/dump" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

Body string

Raw source of message. If no dump is available this will return an empty string.

Example response

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

{
  "Body": "From: \"John Doe\" <john.doe@yahoo.com> \r\nTo: \"john.doe@yahoo.com\" <john.doe@yahoo.com>\r\nReply-To: joe@domain.com\r\nDate: Fri, 14 Feb 2014 11:12:56 -0500\r\nSubject: Parts Order #5454\r\nMIME-Version: 1.0\r\nContent-Type: text/plain; charset=UTF-8\r\nContent-Transfer-Encoding: quoted-printable\r\nX-Mailer: aspNetEmail ver 4.0.0.22\r\nX-Job: 44013_34141\r\nX-virtual-MTA: shared1\r\nX-Complaints-To: abuse@postmarkapp.com\r\nX-PM-RCPT: |bTB8NDQwMTN8MzQxNDF8anBAd2lsZGJpdC5jb20=|\r\nX-PM-Tag: product-orders\r\nX-PM-Message-Id: 07311c54-0687-4ab9-b034-b54b5bad88ba\r\nMessage-ID: <SC-ORD-MAIL4390fbe08b95f4257984dcaed896b4730@SC-ORD-MAIL4>\r\n\r\nThank you for your order=2E=2E=2E\r\n"
}

Inbound message search Try → #

get

/messages/inbound

The message search allows you to return up-to 10,000 messages in a search. For searches where you're looking to retrieve more than 10,000 messages use parameters like todate and fromdate to filter the messages.

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/messages/inbound?recipient=john.doe@yahoo.com&count=50&offset=0&fromdate=2015-02-01&todate=2015-03-01&status=blocked" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset required

Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient

Filter by the user who was receiving the email.
fromemail

Filter by the sender email address.
tag

Filter by tag
subject

Filter by email subject
mailboxhash

Filter by mailboxhash
status

Filter by status (blocked, processed , queued, failed, scheduled). The default value is processed. This means that if no status is specified, only processed messages are returned.
todate

Filter messages up to the date specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.
fromdate

Filter messages starting from the date specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.

Response

TotalCount integer

Indicates the number of messages that matched the search criteria you specified. An email that is sent to multiple recipients is counted as 1 message in the Messages API, so TotalCount will be less than the total number of emails sent if some messages were sent to multiple recipients. On the Statistics page in the Postmark UI, a message sent to multiple recipients is counted once for each recipient, so the Sent number on the Statistics page indicates the total number of emails sent. This ensures accurate tracking of opens, link clicks, etc.
Messages array

List of objects that each represent a single message.

Example response

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

{
  "TotalCount": 7,
  "InboundMessages": [
    {
      "From": "dart-zzzzz@yandex.ru",
      "FromName": "Dart Zzzzz",
      "FromFull": {
        "Email": "dart-zzzzz@yandex.ru",
        "Name": "Dart Zzzzz"
      },
      "To": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
      "ToFull": [
        {
          "Email": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
          "Name": ""
        }
      ],
      "CcFull": [],
      "Cc": "",
      "ReplyTo": "",
      "OriginalRecipient": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
      "Subject": "Тест.",
      "Date": "Thu, 13 Feb 2014 17:48:22 +0300",
      "MailboxHash": "",
      "Tag": "",
      "Attachments": [
        {
          "Name": "myimage.png",
          "ContentID": "myimage.png@01CE7342.75E71F80",
          "ContentType": "image/png",
          "ContentLength": 4096
        },
        {
          "Name": "mypaper.doc",
          "ContentID": "",
          "ContentType": "application/msword",
          "ContentLength": 16384
        }
      ],
      "MessageID": "cc5727a0-ea30-4e79-baea-aa43c9628ac4",
      "Status": "Blocked"
    }
  ]
}

Inbound message details Try → #

get

/messages/inbound/{messageid}/details

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/messages/inbound/{messageid}/details" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

From string

The sender email address.
FromName name

The sender name.
FromFull object

Object that contains sender email address and name.
To string

List of objects that contain To recipients.
ToFull array

Object that contains the To address and name.
CcFull array

Object that contains the Cc address and name.
Cc string

List of objects that contain Cc recipients.
ReplyTo string

Reply to override email address.
OriginalRecipient string

Receiver (RCPT TO) address this webhook is for.
Subject string

Email subject
Date string

Timestamp
MailboxHash string

Custom hash that the email was sent to.
TextBody string

Text body of the message.
HtmlBody string

Html body of the message.
Tag string

Tags associated with this message.
Headers array

List of objects that each represent a header name and value.
Attachments array

List of objects that each represent an attachment.
MessageID string

Unique ID of the message.
BlockedReason string

Reason message was blocked.
Status string

Status of message in your Postmark activity.

Example response

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

{
  "From": "dart-zzzzz@yandex.ru",
  "FromName": "Dart Zzzzz",
  "FromFull": {
    "Email": "dart-zzzzz@yandex.ru",
    "Name": "Dart Zzzzz"
  },
  "To": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
  "ToFull": [
    {
      "Email": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
      "Name": ""
    }
  ],
  "CcFull": [],
  "Cc": "",
  "ReplyTo": "",
  "OriginalRecipient": "ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com",
  "Subject": "Тест.",
  "Date": "Thu, 13 Feb 2014 17:48:22 +0300",
  "MailboxHash": "",
  "TextBody": "stuff stuff.",
  "HtmlBody": "",
  "Tag": "",
  "Headers": [
    {
      "Name": "X-Spam-Checker-Version",
      "Value": "SpamAssassin 3.3.1 (2010-03-16) on sc-ord-inbound1"
    },
    {
      "Name": "X-Spam-Status",
      "Value": "No"
    },
    {
      "Name": "X-Spam-Score",
      "Value": "0.7"
    },
    {
      "Name": "X-Spam-Tests",
      "Value": "DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,FSL_HELO_BARE_IP_2,RCVD_IN_DNSWL_LOW,SPF_PASS"
    },
    {
      "Name": "Received-SPF",
      "Value": "Pass (sender SPF authorized) identity=mailfrom; client-ip=95.108.130.92; helo=forward14.mail.yandex.net; envelope-from=dart-zzzzz@yandex.ru; receiver=ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com"
    },
    {
      "Name": "DKIM-Signature",
      "Value": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=yandex.ru; s=mail;t=1392302902; bh=4mN45y6KsGBYQjvZYsA49+gc9iuptslitnW5OR+Gg0M=;h=From:To:Subject:Date;b=StRtIzi3pvGDORwJkDc49RGqcgvlFvUEqAXi8RoHGu3LvHQmZs0F2pRdqc5UYt1gO OvLSKhlDslDkACdSJQAkj6EF99gXgiLItWo7hNfbv03qDlIq27f8vCZN5Uw0DY5shQ mVatnZbP/L01YP1pTXQONaalDFJ4ByRjjrWDrFVI="
    },
    {
      "Name": "Envelope-From",
      "Value": "Dart-zzzzz@yandex.ua"
    },
    {
      "Name": "MIME-Version",
      "Value": "1.0"
    },
    {
      "Name": "Message-Id",
      "Value": "<51351392302902@web19j.yandex.ru>"
    },
    {
      "Name": "X-Mailer",
      "Value": "Yamail [ http://yandex.ru ] 5.0"
    },
    {
      "Name": "Content-Transfer-Encoding",
      "Value": "8bit"
    }
  ],
  "Attachments": [
    {
      "Name": "myimage.png",
      "ContentID": "myimage.png@01CE7342.75E71F80",
      "ContentType": "image/png",
      "ContentLength": 4096
    },
    {
      "Name": "mypaper.doc",
      "ContentID": "",
      "ContentType": "application/msword",
      "ContentLength": 16384
    }
  ],
  "MessageID": "cc5727a0-ea30-4e79-baea-aa43c9628ac4",
  "BlockedReason": "Inbound request blocked by domain rule: badsender@example.com",
  "Status": "Blocked"
}

Bypass rules for a blocked inbound message Try → #

put

/messages/inbound/{messageid}/bypass

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/messages/inbound/{messageid}/bypass" \
  -X PUT \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ErrorCode integer

API Error Codes
Message string

The result of trying to bypass the blocked message.

Example response

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

{
  ErrorCode: 0
  Message: "Successfully bypassed message: 792a3e9d-0078-40df-a6b0-fc78f87bf277."
}

Retry a failed inbound message for processing Try → #

put

/messages/inbound/{messageid}/retry

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/messages/inbound/{messageid}/retry" \
  -X PUT \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d ""

Response

ErrorCode integer

API Error Codes
Message string

The result of trying to bypass the blocked message.

Example response

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

{
  ErrorCode: 0
  Message: "Successfully rescheduled failed message: 041e3d29-737d-491e-9a13-a94d3rjkjka13."
}

Message opens Try → #

get

/messages/outbound/opens

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/messages/outbound/opens?recipient=john.doe@yahoo.com&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of messages to return per request. Max 500. Count + Offset cannot exceed 10,000 messages.
offset required

Number of messages to skip. Count + Offset cannot exceed 10,000 messages.
recipient

Filter by To, Cc, Bcc
tag

Filter by tag
messagestream

Filter by message stream ID. If not provided, search will default to the outbound transactional stream.
client_name

Filter by client name, i.e. Outlook, Gmail
client_company

Filter by company, i.e. Microsoft, Apple, Google
client_family

Filter by client family, i.e. OS X, Chrome
os_name

Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
os_family

Filter by kind of OS used without specific version, i.e. OS X, Windows
os_company

Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
platform

Filter by platform, i.e. webmail, desktop, mobile
country

Filter by country messages were opened in, i.e. Denmark, Russia
region

Filter by full name of region messages were opened in, i.e. Moscow, New York
city

Filter by full name of city messages were opened in, i.e. Minneapolis, Philadelphia

Response

Consistent fields

These fields will always be returned.

TotalCount integer

Indicates how many opens match the search criteria you specified. This can be more than what is fetched by a single call.
Opens array

List of documents that each represent a single email open. Note that a single open is bound to a single recipient, so if the same message was sent to two recipients and both of them opened it, that will be represented by two entries in this array.
RecordType string

Type of record
UserAgent string

Full user-agent header passed by the client software to Postmark. Postmark will fill in the Platform Client and OS fields based on this.
MessageID string

Unique ID of the message.
MessageStream string

The outbound sending message stream for the message.
ReceivedAt string

Timestamp of when the message was opened

Example response

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

{
  "TotalCount": 1,
  "Opens": [
    {
      "RecordType": "Open",
      "Client": {
        "Name": "Chrome 34.0.1847.131",
        "Company": "Google Inc.",
        "Family": "Chrome"
      },
      "OS": {
        "Name": "OS X 10.7 Lion",
        "Company": "Apple Computer, Inc.",
        "Family": "OS X"
      },
      "Platform": "WebMail",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
      "Geo": {
        "CountryISOCode": "RS",
        "Country": "Serbia",
        "RegionISOCode": "VO",
        "Region": "Autonomna Pokrajina Vojvodina",
        "City": "Novi Sad",
        "Zip": "21000",
        "Coords": "45.2517,19.8369",
        "IP": "188.2.95.4"
      },
      "MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
      "MessageStream": "outbound",
      "ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
      "Tag": "welcome-user",
      "Recipient": "john.doe@yahoo.com"
    }
  ]
}

Additional fields

When reading the resulting JSON, please allow for any of the following fields to be missing. If Postmark could not obtain that part of the information, the field will not be present in the resulting JSON.

Client object

Shows the email client (or browser) used to open the email. Name company and family are described in the parameters specification for this endpoint
OS object

Shows the operating system used to open the email.
Platform string

Shows what platform was used to open the email. WebMail Desktop Mobile Unknown
Geo object

Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Opens for a single message Try → #

get

/messages/outbound/opens/{messageid}

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/messages/outbound/opens/{messageid}?count=10&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of message opens to return per request. Max 500.
offset required

Number of messages to skip

Response

Consistent fields

These fields will always be returned.

TotalCount integer

Postmark API only stores the first open, so TotalCount will always equal "1". The Open Webhook will post each individual open if needed.
Opens array

List of documents that each represent a single email open. Note that a single open is bound to a single recipient, so if the same message was sent to two recipients and both of them opened it, that will be represented by two entries in this array.
UserAgent string

Full user-agent header passed by the client software to Postmark. Postmark will fill in the Platform Client and OS fields based on this.
MessageID string

Unique ID of the message.
MessageStream string

The outbound sending message stream for the message.
ReceivedAt string

Timestamp of when the message was opened.

Example response

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

{
  "TotalCount": 1,
  "Opens": [
    {
      "Client": {
        "Name": "Chrome 34.0.1847.131",
        "Company": "Google Inc.",
        "Family": "Chrome"
      },
      "OS": {
        "Name": "OS X 10.7 Lion",
        "Company": "Apple Computer, Inc.",
        "Family": "OS X"
      },
      "Platform": "WebMail",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
      "Geo": {
        "CountryISOCode": "RS",
        "Country": "Serbia",
        "RegionISOCode": "VO",
        "Region": "Autonomna Pokrajina Vojvodina",
        "City": "Novi Sad",
        "Zip": "21000",
        "Coords": "45.2517,19.8369",
        "IP": "188.2.95.4"
      },
      "MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
      "MessageStream": "outbound",
      "ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
      "Tag": "welcome-user",
      "Recipient": "john.doe@yahoo.com"
    }
  ]
}

Additional fields

When reading the resulting JSON, please allow for any of the following fields to be missing. If Postmark could not obtain that part of the information, the field will not be present in the resulting JSON.

Client object

Shows the email client (or browser) used to open the email. Name company and family are described in the parameters specification for this endpoint
OS object

Shows the operating system used to open the email.
Platform string

Shows what platform was used to open the email. WebMail Desktop Mobile Unknown
Geo object

Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Message clicks Try → #

get

/messages/outbound/clicks

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/messages/outbound/clicks?recipient=john.doe@yahoo.com&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of message clicks to return per request. Max 500.
offset required

Number of clicks to skip
recipient

Filter by To, Cc, Bcc
tag

Filter by tag
client_name

Filter by client name, i.e. Outlook, Gmail
client_company

Filter by company, i.e. Microsoft, Apple, Google
client_family

Filter by client family, i.e. OS X, Chrome
os_name

Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
os_family

Filter by kind of OS used without specific version, i.e. OS X, Windows
os_company

Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
platform

Filter by platform, i.e. webmail, desktop, mobile
country

Filter by country messages were clicked in, i.e. Denmark, Russia
region

Filter by full name of region messages were clicked in, i.e. Moscow, New York
city

Filter by full name of city messages were clicked in, i.e. Minneapolis, Philadelphia
messagestream

Filter by message stream ID. If not provided, message will default to the outbound transactional stream.

Response

Consistent fields

These fields will always be returned.

TotalCount integer

Indicates how many clicks match the search criteria you specified. This can be more than what is fetched by a single call.
Clicks array

List of events that each represent a single email click. Note that a single click is bound to a single recipient and unique link, so if the same message was sent to two recipients and both of them clicked links in the message each will be included in the array.
RecordType string

Type of record
UserAgent string

Full user-agent header passed by the client software to Postmark. Postmark will fill in the Platform Client and OS fields based on this.
MessageID string

Unique ID of the message.
ReceivedAt string

Timestamp of when the link was clicked.

Example response

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

{
  "TotalCount": 1,
  "Clicks": [
    {
      "RecordType": "Click",
      "ClickLocation" : "HTML",
      "Client": {
        "Name": "Chrome 34.0.1847.131",
        "Company": "Google Inc.",
        "Family": "Chrome"
      },
      "OS": {
        "Name": "OS X 10.7 Lion",
        "Company": "Apple Computer, Inc.",
        "Family": "OS X"
      },
      "Platform": "WebMail",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
      "OriginalLink" : "https://example.com",
      "Geo": {
        "CountryISOCode": "RS",
        "Country": "Serbia",
        "RegionISOCode": "VO",
        "Region": "Autonomna Pokrajina Vojvodina",
        "City": "Novi Sad",
        "Zip": "21000",
        "Coords": "45.2517,19.8369",
        "IP": "188.2.95.4"
      },
      "MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
      "MessageStream": "Outbound",
      "ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
      "Tag": "welcome-user",
      "Recipient": "john.doe@yahoo.com"
    }
  ]
}

Additional fields

When reading the resulting JSON, please allow for any of the following fields to be missing. If Postmark could not obtain that part of the information, the field will not be present in the resulting JSON.

Client object

Shows the email client (or browser) used to open the email. Name company and family are described in the parameters specification for this endpoint
OS object

Shows the operating system used to open the email.
Platform string

Shows what platform was used to open the email. WebMail Desktop Mobile Unknown
Geo object

Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.

Clicks for a single message Try → #

get

/messages/outbound/clicks/{messageid}

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/messages/outbound/clicks/{messageid}?count=10&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of message clicks to return per request. Max 500.
offset required

Number of messages to skip

Response

Consistent fields

These fields will always be returned.

TotalCount integer

Indicates how many clicks match the search criteria you specified. This can be more than what is fetched by a single call.
Clicks array

List of events that each represent a single email click. Note that a single click is bound to a single recipient and unique link, so if the same message was sent to two recipients and both of them clicked links in the message each will be included in the array.
UserAgent string

Full user-agent header passed by the client software to Postmark. Postmark will fill in the Platform Client and OS fields based on this.
MessageID string

Unique ID of the message.
MessageStream string

The outbound sending message stream for the message.
ReceivedAt string

Timestamp of when the link was clicked.

Example response

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

{
  "TotalCount": 1,
  "Clicks": [
    {
      "ClickLocation" : "HTML",
      "Client": {
        "Name": "Chrome 34.0.1847.131",
        "Company": "Google Inc.",
        "Family": "Chrome"
      },
      "OS": {
        "Name": "OS X 10.7 Lion",
        "Company": "Apple Computer, Inc.",
        "Family": "OS X"
      },
      "OriginalLink" : "https://example.com",
      "Platform": "WebMail",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
      "Geo": {
        "CountryISOCode": "RS",
        "Country": "Serbia",
        "RegionISOCode": "VO",
        "Region": "Autonomna Pokrajina Vojvodina",
        "City": "Novi Sad",
        "Zip": "21000",
        "Coords": "45.2517,19.8369",
        "IP": "188.2.95.4"
      },
      "MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
      "MessageStream": "outbound",
      "ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
      "Tag": "welcome-user",
      "Recipient": "john.doe@yahoo.com"
    }
  ]
}

Additional fields

When reading the resulting JSON, please allow for any of the following fields to be missing. If Postmark could not obtain that part of the information, the field will not be present in the resulting JSON.

Client object

Shows the email client (or browser) used to open the email. Name company and family are described in the parameters specification for this endpoint
OS object

Shows the operating system used to open the email.
Platform string

Shows what platform was used to open the email. WebMail Desktop Mobile Unknown
Geo object

Contains IP of the recipient’s machine where the email was opened and the information based on that IP - geo coordinates (Coords) and country, region, city and zip.