Menu

Expand
Rate this page:

Marketing Campaign Stats

The Marketing Campaigns Stats endpoints allow you to retrieve stats for both Automations and Single Sends.

Note: These endpoints provide stats for Marketing Campaigns only. For stats related to event tracking, please see the Stats section under Event Tracking below.

Get Single Send Stats by ID

GET /v3/marketing/stats/singlesends/{id}

Base url: https://api.sendgrid.com

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.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Path Parameters

id
string
default: None
required

Query String

aggregated_by
string

Dictates how the stats are time-sliced. Currently, "total" and "day" are supported.

default: total
start_date
string

Format: YYYY-MM-DD. If this parameter is included, the stats' start date is included in the search.

default: 2021-01-01
required
end_date
string

Format: YYYY-MM-DD.If this parameter is included, the stats' end date is included in the search.

default: 2021-12-31
timezone
string

IANA Area/Region string representing the timezone in which the stats are to be presented, e.g., "America/Chicago".

default: UTC
page_size
integer

The number of elements you want returned on each page.

default: 50
page_token
string

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.

default: None
group_by
array

A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.

default: None

Responses

object
results
array[object]
required
id
string

This is the ID of the Single Dend you require stats for.

format: uuid
ab_variation
string

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

default: a14dcc63-d651-4c57-9826-4a3705f5c78dformat: uuid
ab_phase
string

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

default: allAllowed Values: send, test, all
aggregation
string

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
object
bounce_drops
integer
required
bounces
integer
required
clicks
integer
required
delivered
integer
required
invalid_emails
integer
required
opens
integer
required
requests
integer
required
spam_report_drops
integer
required
spam_reports
integer
required
unique_clicks
integer
required
unique_opens
integer
required
unsubscribes
integer
required
_metadata
object
required
prev
string

The URL of the previous page of results. If this field isn't present, you're at the start of the list.

format: uri
self
string

The URL of the current page of results.

format: uri
next
string

The URL of the next page of results. If this field isn't present, you're at the end of the list.

format: uri
count
number

The number of items in the entire list, i.e., across all pages.

object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
No response body.
        
        
        
        Rate this page:

        Need some help?

        We all do sometimes. Get help now from the Twilio SendGrid Support Team.

        Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

              
              
              

              Thank you for your feedback!

              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              Refer us and get $10 in 3 simple steps!

              Step 1

              Get link

              Get a free personal referral link here

              Step 2

              Give $10

              Your user signs up and upgrade using link

              Step 3

              Get $10

              1,250 free SMSes
              OR 1,000 free voice mins
              OR 12,000 chats
              OR more