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 →

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

/messages/outbound/{messageid}/details

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 array List of objects that contain To recipients.
Cc array List of objects that contain Cc recipients.
Bcc array List of objects that contain Bcc recipients.
Recipients array 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 bool 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 →

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

/messages/outbound/{messageid}/dump

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 →

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

/messages/inbound/{messageid}/details

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 string The sender name.
FromFull object Object that contains sender email address and name.
To string Inbound address the message was sent to.
ToFull array Object that contains the To address and name.
CcFull array Object that contains the Cc address and name.
Cc string Cc recipient email address.
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 Plain text email message.
HtmlBody string HTML email message.
Tag string Tag name
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 →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level priveledges. This token can be found on the Credentials tab under your Postmark server.
put

/messages/inbound/{messageid}/bypass

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 →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level priveledges. This token can be found on the Credentials tab under your Postmark server.
put

/messages/inbound/{messageid}/retry

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 retry processing the failed inbound 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 →

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.

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
get

/messages/outbound/opens

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"

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

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

Opens for a single message 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.

Querystring parameters

count Required
Number of message opens to return per request. Max 500.
offset Required
Number of messages to skip
get

/messages/outbound/opens/{messageid}

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"

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

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