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 45 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 on the Credentials 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.

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

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.

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

MessageEvents array

List of summaries (MessageEvent) of things that have happened to this message. They can be 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",
  "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": [
    {
      "Name": "myimage.png",
      "Content": "[BASE64-ENCODED CONTENT]",
      "ContentType": "image/png",
      "ContentLength": 4096,
      "ContentID": "myimage.png@01CE7342.75E71F80"
    },
    {
      "Name": "mypaper.doc",
      "Content": "[BASE64-ENCODED CONTENT]",
      "ContentType": "application/msword",
      "ContentLength": 16384,
      "ContentID": ""
    }
  ],
  "Status": "Sent",
  "TrackOpens" : true,
  "TrackLinks" : "HtmlOnly",
  "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":"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 on the Credentials 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 on the Credentials 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.

Body string

Raw source 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 on the Credentials 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 on the Credentials 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"

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 on the Credentials 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 message opens to return per request. Max 500.

offset required

Number of messages 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 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.

FirstOpen boolean

Indicates if the open was first open of message with MessageID and by Recipient. Any subsequent opens of the same message by the same Recipient will show false in this field. Postmark only saves first opens to its store, while all opens are available via Open web hooks.

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.

Example response

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

{
  "TotalCount": 1,
  "Opens": [
    {
      "FirstOpen": true,
      "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",
      "ReadSeconds": 16,
      "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",
      "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

ReadSeconds integer

Shows the reading time.

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 on the Credentials 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

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.

FirstOpen boolean

Indicates if the open was first open of message with MessageID and by Recipient. Any subsequent opens of the same message by the same Recipient will show false in this field. Postmark only saves first opens to its store, while all opens are available via Open web hooks.

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.

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",
      "ReadSeconds": 16,
      "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",
      "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

ReadSeconds integer

Shows the reading time.

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.