The SendGrid Engagement Quality (SEQ) API allows you to retrieve metrics that define the quality of your email program.
An SEQ score is correlated with:
The quality of the data in a sender's program.
How "wanted" the sender's email is by their recipients.
Because "wanted" email and deliverability are closely related, a higher SEQ metric is correlated with greater deliverability. This means the higher your SEQ score, the more likely you are to land in your recipients' inboxes. See the SEQ Overview page to understand SEQ, how it's calculated, and how you can address your score. The SEQ endpoints allow you to retrieve your scores and scores for your Subusers.
(information)
Info
SendGrid Engagement Quality (SEQ) scores are stored for a maximum of 90 days.
(information)
Info
The SendGrid Engagement Quality API is available across all SendGrid plans, including the free tier. If the API does not return a score, it's likely that you have not enabled open tracking, or your account is not meeting the activity threshold required to generate a score.
To receive an SEQ score, the SendGrid account or Subuser must:
Send at least 1,000 messages during the previous 30 days.
Operation overview
GET/v3/engagementquality/scores
Base url: https://api.sendgrid.com (for global users and subusers)
Base url: https://api.eu.sendgrid.com (for EU regional subusers)
This operation allows you to retrieve your SendGrid Engagement Quality (SEQ) scores for a specified date range.
A successful request with this API operation will return either a 200 or 202 response.
202
This operation returns a 202 response when SendGrid does not yet have scores available for the specified date range. Scores are calculated asynchronously from requests to this endpoint. This means a score may be available for the specified date at a later time, but a score is not available at the time of your API request.
200
A 200 response will include all available scores beginning on the from and ending on the to dates specified. The score and metrics properties will be omitted from the response for any days in which the user is not eligible to receive a score.
The score property represents a user's overall engagement quality. The metrics property provides additional scores for the input categories that contribute to that overall score. All scores range from 1 to 5 with a higher number representing better engagement quality.
See SendGrid Engagement Quality Overview for more information
Operation details
Authentication
Headers
Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
on-behalf-ofstring
Optional
The on-behalf-of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID (e.g., on-behalf-of: account-id <account-id>). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., on-behalf-of: <subuser-username>). See On Behalf Of for more information.
Query string
Property nameTypeRequiredDescription
fromstring<date>required
The starting date in YYYY-MM-DD format (UTC) for which you want to retrieve scores.
tostring<date>required
The ending date in YYYY-MM-DD format (UTC) for which you want to retrieve scores.
The date (UTC) for which this score was calculated.
scorenumber
Your SendGrid Engagement Quality Score. The score property will be omitted when a score is unknown. A score may be unknown if you have not turned on open tracking and/or your account or Subuser has not sent at least 1,000 messages during the previous 30 days.
Minimum: 1Maximum: 5
metricsobject
A collection of metrics representing your engagement score across multiple indicators such as your open rate, spam rate, and bounce rate. Each metric is assigned a score from 1 to 5 with a higher score representing better engagement quality for that particular metric. The metrics property will be omitted when a score is unknown. A score may be unknown if you have not turned on open tracking and/or your account or Subuser has not sent at least 1,000 messages during the previous 30 days.
Indicates whether or not you are sending to an engaged audience. Engagement recency is determined by factors such as how regularly your messages are being opened and clicked. Your score will range from 1 to 5 with a higher score representing better engagement quality.
Minimum: 1Maximum: 5
open_ratenumber
Indicates the degree to which your audience is opening your messages. Your score will range from 1 to 5 with a higher score representing a better open rate and better engagement quality.
Minimum: 1Maximum: 5
bounce_classificationnumber
Indicates the degree to which mailbox providers are rejecting your mail due to reputation issues or content that looks like spam. Your score is calculated based on a ratio of these specific types of bounces to your total processed email. Your score will range from 1 to 5 with a higher score representing a lower percentage of bounces and better engagement quality.
Minimum: 1Maximum: 5
bounce_ratenumber
Indicates if you are attempting to send too many messages to addresses that don't exist. This score is determined by calculating your permanent bounces (bounces to invalid mailboxes). Your score will range from 1 to 5 with a higher score representing fewer bounces and better engagement quality.
Minimum: 1Maximum: 5
spam_ratenumber
Indicates if your messages are generating excessive spam complaints from recipients. This score is determined by calculating the number of recipients who open your mail and then mark it as spam. Your score will range from 1 to 5 with a higher score representing fewer spam reports and better engagement quality.