# Get Subusers' Engagement Quality Scores ## API Overview 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. > \[!NOTE] > > SendGrid Engagement Quality (SEQ) scores are stored for a maximum of 90 days. > \[!NOTE] > > The SendGrid Engagement Quality API is available across all [SendGrid plans](https://sendgrid.com/pricing), 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: > > * [Turn on open tracking](/docs/sendgrid/ui/account-and-settings/tracking#open-tracking). > * Send at least 1,000 messages during the previous 30 days. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/engagementquality/subusers/scores","method":"get","servers":[{"url":"https://api.sendgrid.com","description":"for global users and subusers"},{"url":"https://api.eu.sendgrid.com","description":"for EU regional subusers"}]} ``` **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 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 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**](/docs/sendgrid/api-reference/sendgrid-engagement-quality-api/overview) for more information ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"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 `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}] ``` ### Query string ```json [{"name":"limit","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000,"example":750,"default":1000},"description":"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.","refName":"#/components/parameters/SeqLimit","modelName":"__components_parameters_SeqLimit"},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"The date in YYYY-MM-DD format (UTC) for which you want to retrieve a SendGrid Engagement Quality score.","refName":"#/components/parameters/SeqDate","modelName":"__components_parameters_SeqDate"},{"name":"after_key","in":"query","required":false,"schema":{"type":"integer"},"description":"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.","refName":"#/components/parameters/SeqAfterKey","modelName":"__components_parameters_SeqAfterKey"}] ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"array","description":"An array of objects containing SendGrid Engagement Quality scores and their associated data.","items":{"title":"Score","type":"object","description":"A user's SendGrid Engagement Quality (SEQ) score for a specified date. Your SEQ score is determined by measuring several key metrics including your open rate, spam rate, and engagement recency. Your overall score allows you to quickly assess how your email program is performing at a high level. You will receive a score from `1` to `5` with a higher number representing better engagement quality. See the `metrics` property to understand how your program is performing across the input categories that determine your overall score.","required":["user_id"],"examples":[{"score":3,"username":"jdoe123","date":"2006-01-02","user_id":"180","metrics":{"engagement_recency":4,"open_rate":1,"bounce_classification":2,"bounce_rate":4,"spam_rate":4}}],"refName":"SeqScore","modelName":"SeqScore","properties":{"user_id":{"type":"string","description":"The user identifier associated with this score."},"username":{"type":"string","description":"The username associated with this score."},"date":{"type":"string","description":"The date (UTC) for which this score was calculated.","format":"date"},"score":{"type":"number","description":"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](/docs/sendgrid/ui/account-and-settings/tracking) and/or your account or Subuser has not sent at least 1,000 messages during the previous 30 days.","minimum":1,"maximum":5},"metrics":{"description":"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](/docs/sendgrid/ui/account-and-settings/tracking) and/or your account or Subuser has not sent at least 1,000 messages during the previous 30 days.","type":"object","required":["engagement_recency","open_rate","bounce_classification","bounce_rate","spam_rate"],"examples":[{"engagement_recency":4,"open_rate":1,"bounce_classification":2,"bounce_rate":4,"spam_rate":4}],"title":"","refName":"SeqMetrics","modelName":"SeqMetrics","properties":{"engagement_recency":{"type":"number","description":"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":1,"maximum":5},"open_rate":{"type":"number","description":"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":1,"maximum":5},"bounce_classification":{"type":"number","description":"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":1,"maximum":5},"bounce_rate":{"type":"number","description":"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":1,"maximum":5},"spam_rate":{"type":"number","description":"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.","minimum":1,"maximum":5}}}}}},"_metadata":{"title":"Metadata","type":"object","description":"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.","refName":"SeqMetadata","modelName":"SeqMetadata","properties":{"next_params":{"type":"object","properties":{"after_key":{"type":"string","description":"The `after_key` property represents the last processed key. If the `after_key` property is `null`, there are no more entries available."}}}}}}},"examples":{"Example 1":{"value":{"result":[{"score":2,"username":"jdoe123","date":"2021-12-31","user_id":"180","metrics":{"engagement_recency":4,"open_rate":1,"bounce_classification":2,"bounce_rate":4,"spam_rate":4}},{"date":"2021-12-31","user_id":"181"}],"_metadata":{"next_params":{"after_key":"180"}}}}}}},"refName":"#/components/responses/SeqPaginatedScores","modelName":"__components_responses_SeqPaginatedScores"}},{"responseCode":"202","schema":{"description":"A 202 is returned when the request is successfully received but a score is not calculated for requested date."}},{"responseCode":"400","schema":{"description":"Bad Request 400","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"title":"Error","type":"object","required":["message"],"description":"This object contains error details","refName":"SeqError","modelName":"SeqError","properties":{"field":{"type":"string","description":"When applicable, this property value will be the field that generated the error."},"message":{"type":"string","description":"An error message."}}}}}},"examples":{"invalid limit":{"value":{"errors":[{"field":"limit","message":"failed to parse request: \"limit\" invalid"}]}},"not provided date":{"value":{"errors":[{"field":"date","message":"failed to parse request: \"date\" must be provided"}]}},"date invalid":{"value":{"errors":[{"field":"string","message":"string"}]}},"parse after_key":{"value":{"errors":[{"field":"after_key","message":"failed to parse request: \"after_key\" invalid"}]}},"limit integer":{"value":{"errors":[{"field":"limit","message":"failed to parse request: \"limit\" must be a positive integer"}]}},"date 90d":{"value":{"errors":[{"field":"date","message":"failed to parse request: \"date\" cannot be more than 90 days in the past"}]}},"date future":{"value":{"errors":[{"field":"date","message":"failed to parse request: \"date\" cannot be in the future"}]}}}}},"refName":"#/components/responses/SeqV1SubusersScores400","modelName":"__components_responses_SeqV1SubusersScores400"}},{"responseCode":"401","schema":{"description":"401 Unauthorized","content":{"application/json":{}},"refName":"#/components/responses/SeqV1Scores401","modelName":"__components_responses_SeqV1Scores401"}},{"responseCode":"403","schema":{"description":"Forbidden"}},{"responseCode":"404","schema":{"description":"Not Found"}},{"responseCode":"500","schema":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"title":"Error","type":"object","required":["message"],"description":"This object contains error details","refName":"SeqError","modelName":"SeqError","properties":{"field":{"type":"string","description":"When applicable, this property value will be the field that generated the error."},"message":{"type":"string","description":"An error message."}}}}}},"examples":{"Example 1":{"value":{"errors":[{"message":"internal server error"}]}}}}},"refName":"#/components/responses/SeqV1Scores500","modelName":"__components_responses_SeqV1Scores500"}}] ``` Get Subusers Engagement Quality Scores ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const queryParams = { date: "2009-07-06", limit: 750, }; const request = { url: `/v3/engagementquality/subusers/scores`, method: "GET", qs: queryParams, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) params = {"limit": 750, "date": "2009-07-06"} response = sg.client.engagementquality.subusers.scores.get(query_params=params) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var queryParams = @"{'limit': 750, 'date': '2009-07-06'}"; var response = await client.RequestAsync( method: SendGridClient.Method.GET, urlPath: "engagementquality/subusers/scores", queryParams: queryParams); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.GET); request.setEndpoint("/engagementquality/subusers/scores"); request.addQueryParam("limit", "750"); request.addQueryParam("date", "2009-07-06"); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/engagementquality/subusers/scores", host) request.Method = "GET" queryParams := make(map[string]string) queryParams["limit"] = "750" queryParams["date"] = "2009-07-06" request.QueryParams = queryParams response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $query_params = json_decode('{ "limit": 750, "date": "2009-07-06" }'); try { $response = $sg->client ->engagementquality() ->subusers() ->scores() ->get(null, $query_params); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) params = JSON.parse('{ "limit": 750, "date": "2009-07-06" }') response = sg.client.engagementquality.subusers.scores.get(query_params: params) puts response.status_code puts response.headers puts response.body ``` ```bash curl -G -X GET "https://api.sendgrid.com/v3/engagementquality/subusers/scores?limit=750&date=2009-07-06" \ --header "Authorization: Bearer $SENDGRID_API_KEY" ```