Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Get Subusers' Engagement Quality Scores



API Overview

api-overview page anchor

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(link takes you to an external page), 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:


GET/v3/engagementquality/subusers/scores

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

This operation allows you to retrieve SendGrid Engagement Quality (SEQ) scores for your Subusers or customer accounts for a specific date. A successful request with this API operation will return either a 200 or 202 response.

202

202 page anchor

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.

A 200 response will include scores for all Subusers or customer accounts belonging to the requesting parent or reseller account. The score and metrics properties will be omitted from the response if a Subuser or customer account is not eligible to receive a score for the specified date. The score property represents a Subuser or customer account'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


Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>

on-behalf-ofstring

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.

limitinteger

Specifies the number of results to be returned by the API. This parameter can be used to limit the results returned or in combination with the after_key parameter to iterate through paginated results.

Minimum: 0Maximum: 1000Default: 1000

datestring<date>required

The date in YYYY-MM-DD format (UTC) for which you want to retrieve a SendGrid Engagement Quality score.


after_keyinteger

Specifies which items to be returned by the API. When the after_key is specified, the API will return items beginning from the first item after the item specified. This parameter can be used in combination with limit to iterate through paginated results.

200202400401403404500

Example response

SchemaExample
resultarray[object]

An array of objects containing SendGrid Engagement Quality scores and their associated data.


_metadataobject

This object contains response metadata. The presence of the after_key property in the metadata indicates that some items are still outstanding and have not been retrieved. You can use the after_key value to retrieve additional items with another request.

Get Subusers Engagement Quality Scores

get-subusers-engagement-quality-scores page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_22
const client = require('@sendgrid/client');
_22
client.setApiKey(process.env.SENDGRID_API_KEY);
_22
_22
const queryParams = {
_22
"limit": 1000,
_22
"date": "2014-02-04"
_22
};
_22
_22
const request = {
_22
url: `/v3/engagementquality/subusers/scores`,
_22
method: 'GET',
_22
qs: queryParams
_22
}
_22
_22
client.request(request)
_22
.then(([response, body]) => {
_22
console.log(response.statusCode);
_22
console.log(response.body);
_22
})
_22
.catch(error => {
_22
console.error(error);
_22
});


Rate this page: