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