Overview

Integration

User guide

API reference

Webhooks

Stats API

Lets you get all of the statistics of your outbound emails for a specific server. These statistics are stored permanently and do not expire. All stats use EST timezone. If no from/to date is provided, all time stats are returned.

Get outbound overview Try → #

get

/stats/outbound

Gets a brief overview of statistics for all of your outbound email.

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found on the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/stats/outbound?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Sent integer

Number of sent emails.
Bounced integer

Number of bounced emails.
SMTPApiErrors integer

Number of SMTP errors.
BounceRate double

Bounce rate percentage calculated by total sent.
SpamComplaints integer

Number of spam complaints received.
SpamComplaintsRate double

Spam complaints percentage calculated by total sent.
Opens integer

Number of opens.
UniqueOpens integer

Number of unique opens.
TotalClicks integer

Total number of clicks from all tracked links.
UniqueLinksClicked integer

Total number of unique clicks from all tracked links.
TotalTrackedLinksSent integer

Total number of tracked links sent in emails.
Tracked integer

Number of emails sent with either Link or Open Tracking enabled. An email that has both types of tracking enabled will only increase this total by 1.
WithLinkTracking integer

Number of emails sent with Link Tracking enabled.
WithOpenTracking integer

Number of emails sent with Open Tracking enabled.
WithClientRecorded integer

Number of emails where the client was successfully tracked.
WithPlatformRecorded integer

Number of emails where platform was successfully tracked.

Example response

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

{
  "Sent": 615,
  "Bounced": 64,
  "SMTPApiErrors": 25,
  "BounceRate": 10.406,
  "SpamComplaints": 10,
  "SpamComplaintsRate": 1.626,
  "Opens": 166,
  "UniqueOpens": 26,
  "Tracked": 111,
  "WithLinkTracking": 90,
  "WithOpenTracking": 51,
  "TotalTrackedLinksSent": 60,
  "UniqueLinksClicked": 30,
  "TotalClicks": 72,
  "WithClientRecorded": 14,
  "WithPlatformRecorded": 10
}

Get sent counts Try → #

get

/stats/outbound/sends

Gets a total count of emails you’ve sent out.

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/stats/outbound/sends?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent sent counts by date.
Sent integer

Number of sent emails.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Sent": 140
    },
    {
      "Date": "2014-01-02",
      "Sent": 160
    },
    {
      "Date": "2014-01-04",
      "Sent": 50
    },
    {
      "Date": "2014-01-05",
      "Sent": 115
    }
  ],
  "Sent": 615
}

Get bounce counts Try → #

get

/stats/outbound/bounces

Gets total counts of emails you’ve sent out that have been returned as bounced.

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/stats/outbound/bounces?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent bounce counts by date.
HardBounce integer

Indicates total number of hard bounces.
SMTPApiError integer

Indicates total number of SMTP errors.
SoftBounce integer

Indicates total number of soft bounces.
Transient integer

Indicates total number of transient bounces.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "HardBounce": 12,
      "SoftBounce": 36
    },
    {
      "Date": "2014-01-03",
      "Transient": 7
    },
    {
      "Date": "2014-01-04",
      "Transient": 4
    },
    {
      "Date": "2014-01-05",
      "SMTPApiError": 25,
      "Transient": 5
    }
  ],
  "HardBounce": 12,
  "SMTPApiError": 25,
  "SoftBounce": 36,
  "Transient": 16
}

Get spam complaints Try → #

get

/stats/outbound/spam

Gets a total count of recipients who have marked your email as spam.

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/stats/outbound/spam?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent spam complaint counts by date.
SpamComplaint integer

Number of spam complaints received.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "SpamComplaint": 2
    },
    {
      "Date": "2014-01-02",
      "SpamComplaint": 3
    },
    {
      "Date": "2014-01-05",
      "SpamComplaint": 5
    }
  ],
  "SpamComplaint": 10
}

Get tracked email counts Try → #

get

/stats/outbound/tracked

Gets a total count of emails you’ve sent with open tracking or link tracking enabled.

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/stats/outbound/tracked?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent tracked email counts by date.
Tracked integer

Number of emails sent with either Link or Open Tracking enabled. An email that has both types of tracking enabled will only increase this total by 1.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Tracked": 24
    },
    {
      "Date": "2014-01-02",
      "Tracked": 26
    },
    {
      "Date": "2014-01-03",
      "Tracked": 15
    },
    {
      "Date": "2014-01-04",
      "Tracked": 15
    },
    {
      "Date": "2014-01-05",
      "Tracked": 31
    }
  ],
  "Tracked": 111
}

Get email open counts Try → #

get

/stats/outbound/opens

Gets total counts of recipients who opened your emails. This is only recorded when open tracking is enabled for that email.

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/stats/outbound/opens?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent tracked email counts by date.
Opens integer

Indicates total number of opened emails. This total includes recipients who opened your email multiple times.
Unique integer

Indicates total number of uniquely opened emails.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Opens": 44,
      "Unique": 4
    },
    {
      "Date": "2014-01-02",
      "Opens": 46,
      "Unique": 6
    },
    {
      "Date": "2014-01-03",
      "Opens": 25,
      "Unique": 5
    },
    {
      "Date": "2014-01-04",
      "Opens": 25,
      "Unique": 5
    },
    {
      "Date": "2014-01-05",
      "Opens": 26,
      "Unique": 6
    }
  ],
  "Opens": 166,
  "Unique": 26
}

Get email platform usage Try → #

get

/stats/outbound/opens/platforms

Gets an overview of the platforms used to open your emails. This is only recorded when open tracking is enabled for that email.

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/stats/outbound/opens/platforms?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent email usage by date.
Desktop integer

Indicates total number of users that opened email in desktop app.
Mobile integer

Indicates total number of users that opened email in mobile app.
Unknown integer

Indicates total number of users who’s platforms could not be determined.
WebMail integer

Indicates total number of users that opened email in web email platform.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Desktop": 1,
      "WebMail": 1
    },
    {
      "Date": "2014-01-02",
      "Mobile": 2,
      "WebMail": 1
    },
    {
      "Date": "2014-01-04",
      "Desktop": 3,
      "Unknown": 2
    }
  ],
  "Desktop": 4,
  "Mobile": 2,
  "Unknown": 2,
  "WebMail": 2
}

Get email client usage Try → #

get

/stats/outbound/opens/emailclients

Gets an overview of the email clients used to open your emails. This is only recorded when open tracking is enabled for that email.

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/stats/outbound/opens/emailclients?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent email client usage by date.
Client (e.g. Apple Mail) integer

Indicates total number of users for that given email client.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Apple Mail": 1,
      "Outlook 2010": 1
    },
    {
      "Date": "2014-01-02",
      "Apple Mail": 1,
      "Outlook 2010": 2
    },
    {
      "Date": "2014-01-04",
      "Apple Mail": 4,
      "Outlook 2010": 5
    }
  ],
  "Apple Mail": 6,
  "Outlook 2010": 8
}

Get click counts Try → #

get

/stats/outbound/clicks

Gets total counts of unique links that were clicked.

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/stats/outbound/clicks?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent clicks by date.
Clicks integer

Indicates total number of clicked links. This total includes recipients who clicked links in your email multiple times.
Unique integer

Indicates total number of unique links that were clicked. Links are considered unique for each recipient, per email. However the same url in both the text or html bodies will be treated as the same link.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Clicks": 44,
      "Unique": 4
    },
    {
      "Date": "2014-01-02",
      "Clicks": 46,
      "Unique": 6
    },
    {
      "Date": "2014-01-03",
      "Clicks": 25,
      "Unique": 5
    },
    {
      "Date": "2014-01-04",
      "Clicks": 25,
      "Unique": 5
    },
    {
      "Date": "2014-01-05",
      "Clicks": 26,
      "Unique": 6
    }
  ],
  "Clicks": 166,
  "Unique": 26
}

Get browser usage Try → #

get

/stats/outbound/clicks/browserfamilies

Gets an overview of the browsers used to open links in your emails. This is only recorded when Link Tracking is enabled for that email.

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/stats/outbound/clicks/browserfamilies?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent browser usage by date.
Client (e.g. Safari mobile) integer

Indicates total number of of times the given browser was used to open a tracked link in your emails.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Google Chrome": 1,
      "Safari mobile": 1
    },
    {
      "Date": "2014-01-02",
      "Google Chrome": 1,
      "Safari mobile": 2
    },
    {
      "Date": "2014-01-04",
      "Google Chrome": 4,
      "Safari mobile": 5
    }
  ],
  "Google Chrome": 6,
  "Safari mobile": 8
}

Get browser platform usage Try → #

get

/stats/outbound/clicks/platforms

Gets an overview of the browser platforms used to open your emails. This is only recorded when Link Tracking is enabled for that email.

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/stats/outbound/clicks/platforms?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent browser usage by date.
Desktop integer

Indicates total number of clicks that opened in desktop browsers.
Mobile integer

Indicates total number of clicks that opened in mobile browsers.
Unknown integer

Indicates total number of clicks where the browser platform could not be determined.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "Desktop": 1
    },
    {
      "Date": "2014-01-02",
      "Mobile": 2
    },
    {
      "Date": "2014-01-04",
      "Desktop": 3,
      "Unknown": 2
    }
  ],
  "Desktop": 4,
  "Mobile": 2,
  "Unknown": 2
}

Get click location Try → #

get

/stats/outbound/clicks/location

Gets an overview of which part of the email links were clicked from (HTML or Text). This is only recorded when Link Tracking is enabled for that email.

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/stats/outbound/clicks/location?fromdate=2014-01-01&todate=2014-02-01" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

tag

Filter by tag
fromdate

Filter stats starting from the date specified (inclusive). e.g. 2014-01-01
todate

Filter stats up to the date specified (inclusive). e.g. 2014-02-01
messagestream

Filter by message stream. If not provided, the response will include stats for all streams in the server.

Response

Days that didn’t produce statistics won’t appear in the JSON response.

Days array

List of objects that each represent browser usage by date.
HTML integer

Indicates total number of clicks that were from links in the HTML content of the email.
Text integer

Indicates total number of clicks that were from links in the text content of the email.

Example response

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

{
  "Days": [
    {
      "Date": "2014-01-01",
      "HTML": 1
    },
    {
      "Date": "2014-01-02",
      "Text": 2
    },
    {
      "Date": "2014-01-04",
      "HTML": 3,
      "Text": 2
    }
  ],
  "HTML": 4,
  "Text": 4
}