Overview

Integration

User guide

API reference

Webhooks

Message opens API

Search message opens

Query message opens according to the specified input criteria. Opens are sorted by ReceivedAt in descending order. Open events are retained for 45 days in Postmark. Events older than 45 days will not be available via the API.

get

/messages/outbound/opens

Example request with curl

curl "https://api.postmarkapp.com/messages/outbound/opens?recipient=john.doe@yahoo.com&tag=welcome-user&count=25&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Authentication headers

Message opens belong to servers, which means that requests for message opens should use the X-Postmark-Server-Token header for authentication and authorization.

The header name and value are case insensitive. Should you execute the request with wrong or missing headers, you will receive an HTTP response with a status code of 401 (Unauthorized).

Querystring parameters

count Required
Limit the number of message opens to return per request, max of 500.
offset Required
Specify the number of messages to skip.
recipient Filter by the value of the To, Cc, or Bcc fields.
tag Filter by tag.
client_name Filter by the client name, i.e. Outlook, Gmail.
client_company Filter by the client company, i.e. Microsoft, Apple, Google.
client_family Filter by the client family, i.e. OS X, Chrome.
os_name Filter by the full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7.
os_family Filter by the kind of OS used without specific version, i.e. OS X, Windows.
os_company Filter by the company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation.
platform Filter by the platform, i.e. webmail, desktop, mobile.
country Filter by the country messages were opened in, i.e. Denmark, Russia.
region Filter by the full name of region messages were opened in, i.e. Hauts-de-Seine, Pennsylvania.
city Filter by the full name of city messages were opened in, i.e. Minneapolis, Philadelphia.

Example header

X-Postmark-Server-Token: server token

Response

If all goes well, you will get back a JSON document in the same format as the example.

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 Contains an array of objects that each represent a single email open. Note that an open is unique to a 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 for the unique combination of email and recipient. Any subsequent opens of the same email 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 webhooks.
UserAgent string Contains the full user-agent header passed by the client software to Postmark. Postmark will fill in the Platform Client and OSfields based on this.
MessageID string Contains the unique ID of an email.
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 Contains the email client (or browser) used to open the email. Name companyand familyare described in the parameters specification for this endpoint.
OS object Contains the operating system used to open the email.
Platform string Contains what platform was used to open the email, i.e. WebMail, Desktop, Mobile, Unknown.
ReadSeconds integer Contains the time in seconds the email was opened.
Geo object Contains IP of the recipient’s machine where the email was opened and the information based on that IP - Coords and Country, Region, City, and Zip.

Example JSON 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": {
        "City": "Chicago",
        "Zip": "60604",
        "Region": "Illinois",
        "RegionISOCode": "IL",
        "Country": "United States",
        "CountryISOCode": "US",
        "IP": "50.31.208.163",
        "Coords": "41.8776,-87.6272"
      },
      "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

Fetches all opens that occurred for a specified message. Opens are sorted by ReceivedAtin descending order.

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"

Authentication headers

Message opens belong to servers, which means that requests for message opens should use the X-Postmark-Server-Token header for authentication and authorization.

The header name and value are case insensitive. Should you execute the request with wrong or missing headers, you will receive an HTTP response with a status code of 401 (Unauthorized).

Querystring parameters

count Required
Limit the number of message opens to return per request, max of 500.
offset Required
Specify the number of messages to skip.

This response format is identical to the search opens call above. Check out the Messages API reference for all the details about this endpoint.

Example header

X-Postmark-Server-Token: server token