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