Overview

Integration

User guide

API reference

Webhooks

Message opens API

Search message opens Try → #

get

/messages/outbound/opens

Query message opens according to the specified input criteria. Opens are sorted by ReceivedAt in descending order. Open events are retained for your retention period, which is 45 days by default (and retention can be customized from 7 to 365 days). Events older than your retention period will not be available via the API.

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

Example header

X-Postmark-Server-Token: server token

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.

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 OS fields based on this.
MessageID string

Contains the unique ID of an email.

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

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

Opens for a single message Try → #

get

/messages/outbound/opens/{messageid}

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

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

Example header

X-Postmark-Server-Token: server token

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.