Postmark
Tracking opens

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

TerminalCode
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

TerminalCode
X-Postmark-Server-Token: server token

Querystring parameters

required

Limit the number of message opens to return per request, max of 500.

required

Specify the number of messages to skip.

Filter by the value of the To, Cc, or Bcc fields.

Filter by tag.

Filter by the client name, i.e. Outlook, Gmail.

Filter by the client company, i.e. Microsoft, Apple, Google.

Filter by the client family, i.e. OS X, Chrome.

Filter by the full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7.

Filter by the kind of OS used without specific version, i.e. OS X, Windows.

Filter by the company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation.

Filter by the platform, i.e. webmail, desktop, mobile.

Filter by the country messages were opened in, i.e. Denmark, Russia.

Filter by the full name of region messages were opened in, i.e. Hauts-de-Seine, Pennsylvania.

Filter by the full name of city messages were opened in, i.e. Minneapolis, Philadelphia.

count
offset
recipient
tag
client_name
client_company
client_family
os_name
os_family
os_company
platform
country
region
city

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.

Indicates how many opens match the search criteria you specified. This can be more than what is fetched by a single call.

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.

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.

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.

Contains the unique ID of an email.

TotalCountinteger
Opensarray
FirstOpenboolean
UserAgentstring
MessageIDstring

Example response

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

Contains the email client (or browser) used to open the email. Name companyand familyare described in the parameters specification for this endpoint.

Contains the operating system used to open the email.

Contains what platform was used to open the email, i.e. WebMail, Desktop, Mobile, Unknown.

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.

Clientobject
OSobject
Platformstring
Geoobject

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

TerminalCode
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

TerminalCode
X-Postmark-Server-Token: server token

Querystring parameters

required

Limit the number of message opens to return per request, max of 500.

required

Specify the number of messages to skip.

count
offset

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

← Tracking opens per email

Last modified on