The Marketing Campaigns Stats API allows you to retrieve statistics for both Automations and Single Sends. The statistics provided include bounces, clicks, opens, and more. You can export stats in CSV format for use in other applications. You can also retrieve Marketing Campaigns stats in the [Marketing Campaigns application user interface](https://mc.sendgrid.com/). This API provides statistics for Marketing Campaigns only.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Marketing Campaigns Statistics API
summary: The Marketing Campaigns Stats API allows you to retrieve statistics for
both Automations and Single Sends. The statistics provided include bounces, clicks,
opens, and more.
description: 'The Marketing Campaigns Stats API allows you to retrieve statistics
for both Automations and Single Sends. The statistics provided include bounces,
clicks, opens, and more. You can export stats in CSV format for use in other applications.
You can also retrieve Marketing Campaigns stats in the [Marketing Campaigns application
user interface](https://mc.sendgrid.com/).
This API provides statistics for Marketing Campaigns only. For stats related to
event tracking, please see the [Stats API](https://docs.sendgrid.com/api-reference/stats).'
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: mc_stats
servers:
- url: https://api.sendgrid.com
description: The Twilio SendGrid v3 API
paths:
/v3/marketing/stats/automations:
get:
operationId: ListAutomationStat
summary: Get All Automation Stats
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for all your Automations.**
By default, all of your Automations will be returned, but you can specify
a selection by passing in a comma-separated list of Automation IDs as the
value of the query string parameter `automation_ids`.
Responses are paginated. You can limit the number of responses returned per
batch using the `page_size` query string parameter. The default is 25, but
you can specify a value between 1 and 50.
You can retrieve a specific page of responses with the `page_token` query
string parameter.'
parameters:
- name: automation_ids
in: query
description: This endpoint returns all automation IDs if no `automation_ids`
are specified.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 25
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutomationsResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v3/marketing/stats/automations/{id}:
parameters:
- name: id
in: path
description: 'The ID of the Automation for which you want to retrieve statistics. '
required: true
schema:
type: string
get:
operationId: GetAutomationStat
summary: Get Automation Stats by ID
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for a single Automation
using its ID.**
Multiple Automation IDs can be retrieved using the "Get All Automation Stats"
endpoint. Once you have an ID, this endpoint will return detailed stats for
the single automation specified.
You may constrain the stats returned using the `start_date` and `end_date`
query string parameters. You can also use the `group_by` and `aggregated_by`
query string parameters to further refine the stats returned.'
parameters:
- $ref: '#/components/parameters/AutomationQueryParamsGroupBy'
- $ref: '#/components/parameters/AutomationQueryParamsStepId'
- $ref: '#/components/parameters/AggregatedByBaseProps'
- $ref: '#/components/parameters/StartDateBaseProps'
- $ref: '#/components/parameters/EndDateBaseProps'
- $ref: '#/components/parameters/TimezoneBaseProps'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutomationsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
/v3/marketing/stats/automations/{id}/links:
parameters:
- name: id
in: path
description: 'The ID of the Automation you want to get click tracking stats
for. '
required: true
schema:
type: string
format: uuid
get:
operationId: ListClickTrackingStat
summary: Get Automation Click Tracking Stats by ID
tags:
- Stats
description: '**This endpoint lets you retrieve click-tracking stats for a single
Automation**.
The stats returned list the URLs embedded in your Automation and the number
of clicks each one received.'
parameters:
- $ref: '#/components/parameters/AutomationQueryParamsGroupBy'
- $ref: '#/components/parameters/AutomationQueryParamsStepId'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutmoationsLinkStatsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v3/marketing/stats/automations/export:
get:
operationId: ExportAutomationStat
summary: Export Single Send Stats
tags:
- Stats
description: '**This endpoint allows you to export Single Send stats as .CSV
data**.
You can specify one Single Send or many: include as many Single Send IDs as
you need, separating them with commas, as the value of the `ids` query string
parameter.
The data is returned as plain text response but in .CSV format, so your application
making the call can present the information in whatever way is most appropriate,
or just save the data as a .csv file.'
parameters:
- name: ids
in: query
description: The IDs of Single Sends for which to export stats.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 50
- name: timezone
in: query
description: The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones)
string representing the timezone in which the stats are to be presented;
i.e. `"America/Chicago"`. This parameter changes the timezone format only;
it does not alter which stats are returned.
schema:
type: string
default: UTC
responses:
'200':
description: ''
content:
application/json:
schema:
type: string
description: CSV data
'400':
description: ''
/v3/marketing/stats/singlesends:
get:
operationId: ListSingleSendStat
summary: Get All Single Sends Stats
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for all your Single
Sends.**
By default, all of your Single Sends will be returned, but you can specify
a selection by passing in a comma-separated list of Single Send IDs as the
value of the query string parameter `singlesend_ids`.
Responses are paginated. You can limit the number of responses returned per
batch using the `page_size` query string parameter. The default is 25, but
you specify a value between 1 and 50.
You can retrieve a specific page of responses with the `page_token` query
string parameter.'
parameters:
- name: singlesend_ids
in: query
description: This endpoint returns all Single Send IDs if no IDs are included
in `singlesend_ids`.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 25
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsResponse'
'400':
$ref: '#/components/responses/Stats400'
/v3/marketing/stats/singlesends/{id}:
parameters:
- name: id
in: path
description: The ID of Single Send for which you want to retrieve stats.
required: true
schema:
type: string
get:
operationId: GetSingleSendStat
summary: Get Single Send Stats by ID
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for an individual
Single Send using a Single Send ID.**
Multiple Single Send IDs can be retrieved using the "Get All Single Sends
Stats" endpoint. Once you have an ID, this endpoint will return detailed stats
for the Single Send specified.
You may constrain the stats returned using the `start_date` and `end_date`
query string parameters. You can also use the `group_by` and `aggregated_by`
query string parameters to further refine the stats returned.'
parameters:
- $ref: '#/components/parameters/AggregatedByBaseProps'
- $ref: '#/components/parameters/StartDateBaseProps'
- $ref: '#/components/parameters/EndDateBaseProps'
- $ref: '#/components/parameters/TimezoneBaseProps'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
- $ref: '#/components/parameters/SinglesendQueryParamsGroupBy'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
/v3/marketing/stats/singlesends/{id}/links:
parameters:
- name: id
in: path
description: The ID of Single Send for which you want to retrieve link stats.
required: true
schema:
type: string
get:
operationId: ListSingleSendTrackingStat
summary: Get Single Send Click Tracking Stats by ID
tags:
- Stats
description: '**This endpoint lets you retrieve click-tracking stats for one
Single Send**.
The stats returned list the URLs embedded in the specified Single Send and
the number of clicks each one received.'
parameters:
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
- $ref: '#/components/parameters/SinglesendQueryParams2GroupBy'
- $ref: '#/components/parameters/SinglesendQueryParams2VariationId'
- $ref: '#/components/parameters/SinglesendQueryParams2PhaseId'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsLinkStatsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
content:
application/json:
schema:
type: object
/v3/marketing/stats/singlesends/export:
get:
operationId: ExportSingleSendStat
summary: Export Single Send Stats
tags:
- Stats
description: '**This endpoint allows you to export Single Send stats as .CSV
data**.
You can specify one Single Send or many: include as many Single Send IDs as
you need, separating them with commas, as the value of the `ids` query string
parameter.
The data is returned as plain text response but in .CSV format, so your application
making the call can present the information in whatever way is most appropriate,
or just save the data as a .csv file.'
parameters:
- name: ids
in: query
description: The IDs of Single Sends for which to export stats.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 50
- name: timezone
in: query
description: The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones)
string representing the timezone in which the stats are to be presented;
i.e. `"America/Chicago"`. This parameter changes the timezone format only;
it does not alter which stats are returned.
schema:
type: string
default: UTC
responses:
'200':
description: ''
content:
application/json:
schema:
type: string
description: CSV data
'400':
description: ''
components:
schemas:
AutomationsResponse:
title: AutomationsResponse
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
description: This is the ID of the Automation you are requesting stats
for.
format: uuid
aggregation:
type: string
description: This describes the time unit to which the stat is rolled
up. It is based on the `aggregated_by` parameter included in the
request. It can be "total" or the date (in YYYY-MM-DD format) the
stats are for.
default: total
step_id:
type: string
description: This is the ID of the step if the stats were requested
to be grouped by `step_id`.
default: all
stats:
$ref: '#/components/schemas/Metrics'
required:
- id
- aggregation
- step_id
_metadata:
$ref: '#/components/schemas/Metadata'
required:
- results
AutmoationsLinkStatsResponse:
title: AutmoationsLinkStatsResponse
type: object
properties:
results:
type: array
description: ''
items:
type: object
properties:
url:
type: string
description: This is the URL of the link clicked. If `{{custom_fields}}`
are part of the URL, they will be included.
format: uri
url_location:
type: integer
description: This is the location of the link clicked in each Automation
step. Links are located according to their position within the message;
the topmost link has index `0`.
minimum: 0
step_id:
type: string
description: This is the ID of the step if the stats were requested
to be grouped by `step_id`.
format: uuid
clicks:
type: integer
minimum: 1
description: The number of clicks on this particular link.
required:
- url
- step_id
- clicks
total_clicks:
type: integer
_metadata:
$ref: '#/components/schemas/LinkTrackingMetadata'
required:
- results
- total_clicks
- _metadata
SinglesendsResponse:
title: SinglesendsResponse
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
description: This is the ID of the Single Send you require stats for.
format: uuid
ab_variation:
type: string
default: a14dcc63-d651-4c57-9826-4a3705f5c78d
description: This is the A/B variation of the Single Send stat returned.
If the `group_by` parameter doesn't include `ab_variation` in the
request, then the value is "all".
format: uuid
ab_phase:
type: string
default: all
description: This is the A/B phase of the Single Send stat returned.
If the `group_by` parameter doesn't include `ab_phase` in the request,
then the value is "all".
$ref: '#/components/schemas/AbPhase'
aggregation:
type: string
description: This describes the time unit to which the stat is rolled
up. It is based on the `aggregated_by` parameter included in the
request. It can be "total" or the date (in YYYY-MM-DD format) the
stats are for.
default: total
stats:
$ref: '#/components/schemas/Metrics'
required:
- id
- ab_variation
- ab_phase
_metadata:
$ref: '#/components/schemas/Metadata'
required:
- results
- _metadata
SinglesendsLinkStatsResponse:
title: SinglesendsLinkStatsResponse
type: object
properties:
results:
type: array
description: This is the index of the link's location in the email contents.
items:
type: object
properties:
url:
type: string
description: This is the URL of the link clicked. If `{{custom_fields}}`
are part of the URL, they will be included.
format: uri
url_location:
type: integer
description: This is the location of the link clicked in each Single
Send A/B variation, or in the Single Send itself if there are no
variations. Links are numbered from the top down; the topmost link
is index `0`.
minimum: 0
ab_variation:
type: string
description: This is the A/B variation of the Single Send stat returned.
It is set to `"all"` if the `ab_variation` query parameter was not
set in the request and `group_by` doesn't contain `ab_variation`.
format: uuid
ab_phase:
type: string
description: This is the A/B phase of the Single Send stat returned.
If the `ab_phase` query parameter was not provided, it will return
`"all"`.
$ref: '#/components/schemas/AbPhase1'
clicks:
type: integer
minimum: 1
description: the number of clicks on this particular link
required:
- url
- ab_variation
- ab_phase
- clicks
_metadata:
$ref: '#/components/schemas/LinkTrackingMetadata'
total_clicks:
type: integer
required:
- results
- _metadata
Metrics:
title: metrics
type: object
properties:
bounce_drops:
type: integer
bounces:
type: integer
clicks:
type: integer
delivered:
type: integer
invalid_emails:
type: integer
opens:
type: integer
requests:
type: integer
spam_report_drops:
type: integer
spam_reports:
type: integer
unique_clicks:
type: integer
unique_opens:
type: integer
unsubscribes:
type: integer
required:
- bounce_drops
- bounces
- clicks
- delivered
- invalid_emails
- opens
- requests
- spam_report_drops
- spam_reports
- unique_clicks
- unique_opens
- unsubscribes
Metadata:
title: metadata
type: object
properties:
prev:
type: string
format: uri
description: The URL of the previous page of results. If this field isn't
present, you're at the start of the list.
self:
type: string
format: uri
description: The URL of the current page of results.
next:
type: string
format: uri
description: The URL of the next page of results. If this field isn't present,
you're at the end of the list.
count:
type: number
description: The number of items in the entire list, i.e., across all pages.
LinkTrackingMetadata:
title: link tracking metadata
type: object
properties:
prev:
type: string
format: uri
description: The URL of the previous page of results. If this field isn't
present, you're at the start of the list.
self:
type: string
format: uri
description: The URL of the current page of results.
next:
type: string
format: uri
description: The URL of the next page of results. If this field isn't present,
you're at the end of the list.
count:
type: number
description: The number of items in the entire list, i.e., across all pages.
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: An error message.
field:
description: When applicable, this property value will be the field
that generated the error.
nullable: true
type: string
help:
type: object
description: When applicable, this property value will be helper text
or a link to documentation to help you troubleshoot the error.
id:
type: string
description: When applicable, this property value will be an error ID.
example:
errors:
- field: field_name
message: error message
AbPhase:
type: string
enum:
- send
- test
- all
AbPhase1:
type: string
enum:
- send
- test
- all
Items:
type: string
enum:
- step_id
AggregatedBy:
type: string
enum:
- day
- total
Items1:
type: string
enum:
- ab_variation
- ab_phase
Items2:
type: string
enum:
- ab_variation
- ab_phase
AbPhaseId:
type: string
enum:
- test
- send
responses:
Stats400:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
PaginationPageSize:
name: page_size
in: query
description: The number of elements you want returned on each page.
schema:
type: integer
minimum: 1
maximum: 50
default: 25
PaginationPageToken:
name: page_token
in: query
description: The stats endpoints are paginated. To get the next page, call the
passed `_metadata.next` URL. If `_metadata.prev` doesn't exist, you're at
the first page. Similarly, if `_metadata.next` is not present, you're at the
last page.
schema:
type: string
AutomationQueryParamsGroupBy:
name: group_by
in: query
description: Automations can have multiple steps. Including `step_id` as a `group_by`
metric allows further granularity of stats.
style: form
explode: false
schema:
type: array
items:
type: string
$ref: '#/components/schemas/Items'
AutomationQueryParamsStepId:
name: step_ids
in: query
description: Comma-separated list of `step_ids` that you want the link stats
for.
style: form
explode: false
schema:
type: array
items:
type: string
format: uuid
uniqueItems: true
AggregatedByBaseProps:
name: aggregated_by
in: query
description: Dictates how the stats are time-sliced. Currently, `"total"` and
`"day"` are supported.
schema:
type: string
default: total
$ref: '#/components/schemas/AggregatedBy'
StartDateBaseProps:
name: start_date
in: query
description: 'Format: `YYYY-MM-DD`. If this parameter is included, the stats''
start date is included in the search.'
schema:
type: string
format: date
default: '2021-01-01'
EndDateBaseProps:
name: end_date
in: query
description: 'Format: `YYYY-MM-DD`.If this parameter is included, the stats''
end date is included in the search.'
schema:
type: string
format: date
default: '2021-12-31'
TimezoneBaseProps:
name: timezone
in: query
description: '[IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones)
string representing the timezone in which the stats are to be presented, e.g.,
"America/Chicago".'
schema:
type: string
default: UTC
SinglesendQueryParamsGroupBy:
name: group_by
in: query
description: A/B Single Sends have multiple variation IDs and phase IDs. Including
these additional fields allows further granularity of stats by these fields.
style: form
explode: false
schema:
type: array
items:
type: string
$ref: '#/components/schemas/Items1'
SinglesendQueryParams2GroupBy:
name: group_by
in: query
description: A/B Single Sends have multiple variation IDs and phase IDs. Including
these additional fields allows further granularity of stats by these fields.
style: form
explode: false
schema:
type: array
items:
type: string
$ref: '#/components/schemas/Items2'
SinglesendQueryParams2VariationId:
name: ab_variation_id
in: query
schema:
type: string
format: uuid
SinglesendQueryParams2PhaseId:
name: ab_phase_id
in: query
schema:
type: string
$ref: '#/components/schemas/AbPhaseId'
examples: {}
requestBodies: {}
headers: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Twilio SendGrid requires you to authenticate with its APIs using
an API key. The API key must be sent as a bearer token in the Authorization
header.
tags:
- name: Stats
description: Twilio SendGrid Marketing Campaigns Stats API
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid