openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Statistics API
summary: The Twilio SendGrid Statistics API allows you to retrieve the various statistics
related to your email program.
description: 'The Twilio SendGrid Statistics API allows you to retrieve the various
statistics related to your email program.
Tracking your emails is an important part of being a good sender and learning
about how your users interact with your email. This includes everything from clicks
and opens to looking at which browsers and mailbox providers your customers use.
SendGrid has broken up statistics in specific ways so that you can get at-a-glance
data, as well as the details of how your email is being used.
Category statistics are available for the previous thirteen months only.
See [**Statistics Overview**](https://docs.sendgrid.com/ui/analytics-and-reporting/stats-overview)
for more information.'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: stats
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/browsers/stats:
get:
operationId: ListBrowserStat
summary: Retrieve email statistics by browser.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented
by browser type.**
**We only store up to 7 days of email activity in our database.** By default,
500 items will be returned per request via the Advanced Stats API endpoints.
Advanced Stats provide a more in-depth view of your email statistics and the
actions taken by your recipients. You can segment these statistics by geographic
location, device type, client type, browser, and mailbox provider. For more
information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- name: browsers
in: query
description: The browsers to get statistics for. You can include up to 10
different browsers by including this parameter multiple times.
schema:
type: string
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetLimit'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetOffset'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetAggregatedBy'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetStartDate'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetEndDate'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsClicks'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
clicks: 0
unique_clicks: 0
name: Chrome
type: browser
- metrics:
clicks: 1
unique_clicks: 1
name: Firefox
type: browser
- date: '2014-10-02'
stats:
- metrics:
clicks: 0
unique_clicks: 0
name: Chrome
type: browser
- metrics:
clicks: 1
unique_clicks: 1
name: Firefox
type: browser
/v3/categories:
get:
operationId: ListCategory
summary: Retrieve all categories
tags:
- Categories
description: '**This endpoint allows you to retrieve a paginated list of all
of your categories.**
You can use the `limit` query parameter to set the page size. If your list
contains more items than the page size permits, you can make multiple requests.
Use the `offset` query parameter to control the position in the list from
which to start retrieving additional items.'
parameters:
- name: limit
in: query
description: '`limit` sets the page size, i.e. maximum number of items from
the list to be returned for a single API request. If omitted, the default
page size is used.'
schema:
type: integer
minimum: 1
default: 50
- name: category
in: query
description: Allows you to perform a prefix search on this particular category.
schema:
type: string
- $ref: '#/components/parameters/PaginationCommonOffset'
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
category:
type: string
description: A category used to group emails by broad topic.
required:
- category
examples:
response:
value:
- category: category 1
- category: category 2
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
description: The error returned.
items:
type: object
properties:
field:
type: string
message:
type: string
description: A message explaining why your categories could
not be retrieved.
required:
- field
- message
examples:
response:
value:
errors:
- field: sort_by
message: invalid sort value
/v3/categories/stats:
get:
operationId: ListCategoryStat
summary: Retrieve Email Statistics for Categories
tags:
- Categories
description: '**This endpoint allows you to retrieve all of your email statistics
for each of your categories.**
If you do not define any query parameters, this endpoint will return a sum
for each category in groups of 10.'
parameters:
- name: start_date
in: query
description: The starting date of the statistics to retrieve. Must follow
format YYYY-MM-DD
required: true
schema:
type: string
- name: end_date
in: query
description: The end date of the statistics to retrieve. Defaults to today.
Must follow format YYYY-MM-DD.
required: false
schema:
type: string
- name: categories
in: query
description: The individual categories that you want to retrieve statistics
for. You may include up to 10 different categories.
required: true
schema:
type: string
- name: aggregated_by
in: query
description: How to group the statistics. Must be either "day", "week", or
"month".
required: false
schema:
type: string
$ref: '#/components/schemas/AggregatedBy'
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CategoryStats'
examples:
response:
value:
- date: '2015-10-01'
stats:
- type: category
name: docs
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- type: category
name: mattscategory
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-11-01'
stats:
- type: category
name: docs
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- type: category
name: mattscategory
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
/v3/categories/stats/sums:
get:
operationId: ListCategoryStatSum
summary: Retrieve sums of email stats for each category.
tags:
- Categories
description: '**This endpoint allows you to retrieve the total sum of each email
statistic for every category over the given date range.**
If you do not define any query parameters, this endpoint will return a sum
for each category in groups of 10.'
parameters:
- name: sort_by_metric
in: query
description: The metric that you want to sort by. Must be a single metric.
required: false
schema:
type: string
default: delivered
- name: sort_by_direction
in: query
description: The direction you want to sort.
required: false
schema:
type: string
default: desc
$ref: '#/components/schemas/SortByDirection'
- name: start_date
in: query
description: The starting date of the statistics to retrieve. Must follow
format YYYY-MM-DD.
required: true
schema:
type: string
- name: end_date
in: query
description: The end date of the statistics to retrieve. Defaults to today.
Must follow format YYYY-MM-DD.
required: false
schema:
type: string
- name: limit
in: query
description: Limits the number of results returned.
required: false
schema:
type: integer
default: 5
- name: offset
in: query
description: The point in the list to begin retrieving results.
required: false
schema:
type: integer
default: 0
- name: aggregated_by
in: query
description: How to group the statistics. Must be either "day", "week", or
"month".
required: false
schema:
type: string
$ref: '#/components/schemas/AggregatedBy1'
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryStats'
examples:
response:
value:
date: '2015-01-01'
stats:
- metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 20
deferred: 0
delivered: 20
invalid_emails: 0
opens: 20
processed: 0
requests: 20
spam_report_drops: 0
spam_reports: 0
unique_clicks: 20
unique_opens: 20
unsubscribe_drops: 0
unsubscribes: 20
name: cat1
type: category
- metrics:
blocks: 1
bounce_drops: 0
bounces: 0
clicks: 19
deferred: 0
delivered: 19
invalid_emails: 0
opens: 19
processed: 0
requests: 20
spam_report_drops: 0
spam_reports: 0
unique_clicks: 19
unique_opens: 19
unsubscribe_drops: 0
unsubscribes: 19
name: cat2
type: category
- metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 5
deferred: 0
delivered: 5
invalid_emails: 0
opens: 5
processed: 0
requests: 5
spam_report_drops: 0
spam_reports: 0
unique_clicks: 5
unique_opens: 5
unsubscribe_drops: 0
unsubscribes: 5
name: cat3
type: category
- metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 6
deferred: 0
delivered: 5
invalid_emails: 0
opens: 6
processed: 0
requests: 5
spam_report_drops: 0
spam_reports: 0
unique_clicks: 5
unique_opens: 5
unsubscribe_drops: 0
unsubscribes: 6
name: cat4
type: category
- metrics:
blocks: 10
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 10
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
name: cat5
type: category
/v3/clients/stats:
get:
operationId: ListClientStat
summary: Retrieve email statistics by client type.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented
by client type.**
**We only store up to 7 days of email activity in our database.** By default,
500 items will be returned per request via the Advanced Stats API endpoints.
Advanced Stats provide a more in-depth view of your email statistics and the
actions taken by your recipients. You can segment these statistics by geographic
location, device type, client type, browser, and mailbox provider. For more
information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsStartDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsEndDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsAggregatedBy'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
opens: 1
unique_opens: 1
name: Gmail
type: client
- date: '2014-10-02'
stats:
- metrics:
opens: 0
unique_opens: 0
name: Gmail
type: client
/v3/clients/{client_type}/stats:
parameters:
- name: client_type
in: path
description: Specifies the type of client to retrieve stats for. Must be either
"phone", "tablet", "webmail", or "desktop".
required: true
schema:
type: string
$ref: '#/components/schemas/ClientType'
get:
operationId: GetClientStat
summary: Retrieve stats by a specific client type.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented
by a specific client type.**
**We only store up to 7 days of email activity in our database.** By default,
500 items will be returned per request via the Advanced Stats API endpoints.
### Available Client Types
- phone
- tablet
- webmail
- desktop
Advanced Stats provide a more in-depth view of your email statistics and the
actions taken by your recipients. You can segment these statistics by geographic
location, device type, client type, browser, and mailbox provider. For more
information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsStartDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsEndDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsAggregatedBy'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
opens: 1
unique_opens: 1
name: Gmail
type: client
- date: '2014-10-02'
stats:
- metrics:
opens: 0
unique_opens: 0
name: Gmail
type: client
/v3/devices/stats:
get:
operationId: ListDeviceStat
summary: Retrieve email statistics by device type.
tags:
- Stats
description: "**This endpoint allows you to retrieve your email statistics segmented\
\ by the device type.**\n\n**We only store up to 7 days of email activity\
\ in our database.** By default, 500 items will be returned per request via\
\ the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device**\
\ | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software\
\ on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail\
\ |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com.\
\ |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet\
\ | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An\
\ unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of\
\ your email statistics and the actions taken by your recipients. You can\
\ segment these statistics by geographic location, device type, client type,\
\ browser, and mailbox provider. For more information about statistics, please\
\ see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/)."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetLimit'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetOffset'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetAggregatedBy'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetStartDate'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetEndDate'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2015-10-11'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-12'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-13'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-14'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-15'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-16'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-17'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-18'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-19'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-20'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-21'
stats:
- type: device
name: Webmail
metrics:
opens: 1
unique_opens: 1
- date: '2015-10-22'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-23'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-24'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-25'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-26'
stats:
- type: device
name: Webmail
metrics:
opens: 2
unique_opens: 2
- date: '2015-10-27'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-28'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-29'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-30'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-31'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-01'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-02'
stats:
- type: device
name: Webmail
metrics:
opens: 0
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_stats_v3.yaml