Twilio SendGrid Engagement Quality API

openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Engagement Quality API
  summary: The SendGrid Engagement Quality (SEQ) API allows you to retrieve metrics
    that define the quality of your email program.
  description: "The SendGrid Engagement Quality (SEQ) API allows you to retrieve metrics\
    \ that define the quality of your email program.\n\nAn SEQ score is correlated\
    \ with:\n- The quality of the data in a sender\u2019s program.\n- How \u201Cwanted\u201D\
    \ the sender's email is by their recipients.\n\nBecause \u201Cwanted\u201D 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."
  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: seq
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
paths:
  /v3/engagementquality/scores:
    get:
      summary: Get Engagement Quality Scores
      tags:
      - Engagement Quality
      operationId: ListEngagementQualityScore
      description: '**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**](https://docs.sendgrid.com/api-reference/sendgrid-engagement-quality-api/overview)
        for more information'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      - in: query
        name: from
        description: The starting date in YYYY-MM-DD format (UTC) for which you want
          to retrieve scores.
        schema:
          type: string
          format: date
          example: '2006-01-02'
        required: true
      - in: query
        name: to
        description: The ending date in YYYY-MM-DD format (UTC) for which you want
          to retrieve scores.
        schema:
          type: string
          format: date
          example: '2006-01-02'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/SeqV1Scores200'
        '202':
          $ref: '#/components/responses/SeqV1Scores202'
        '400':
          $ref: '#/components/responses/SeqV1Scores400'
        '401':
          $ref: '#/components/responses/SeqV1Scores401'
        '500':
          $ref: '#/components/responses/SeqV1Scores500'
  /v3/engagementquality/subusers/scores:
    get:
      summary: Get Subusers' Engagement Quality Scores
      tags:
      - Engagement Quality
      operationId: ListSubuserEngagementQualityScore
      description: '**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**](https://docs.sendgrid.com/api-reference/sendgrid-engagement-quality-api/overview)
        for more information'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      - $ref: '#/components/parameters/SeqLimit'
      - $ref: '#/components/parameters/SeqDate'
      - $ref: '#/components/parameters/SeqAfterKey'
      responses:
        '200':
          $ref: '#/components/responses/SeqPaginatedScores'
        '202':
          description: A 202 is returned when the request is successfully received
            but a score is not calculated for requested date.
        '400':
          $ref: '#/components/responses/SeqV1SubusersScores400'
        '401':
          $ref: '#/components/responses/SeqV1Scores401'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          $ref: '#/components/responses/SeqV1Scores500'
components:
  schemas:
    SeqMetrics:
      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](https://docs.sendgrid.com/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
      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
      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: ''
    SeqScore:
      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.
      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](https://docs.sendgrid.com/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:
          $ref: '#/components/schemas/SeqMetrics'
      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
    SeqMetadata:
      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.
      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.
    SeqError:
      title: Error
      type: object
      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.
      required:
      - message
      description: This object contains error details
  responses:
    SeqPaginatedScores:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: array
                description: An array of objects containing SendGrid Engagement Quality
                  scores and their associated data.
                items:
                  $ref: '#/components/schemas/SeqScore'
              _metadata:
                $ref: '#/components/schemas/SeqMetadata'
            required:
            - result
          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'
    SeqV1Scores200:
      description: 200 OK
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: array
                description: An array of objects containing SendGrid Engagement Quality
                  scores and their associated data.
                items:
                  $ref: '#/components/schemas/SeqScore'
          examples:
            '200':
              value:
                result:
                - score: 2
                  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
            200 partial results:
              value:
                result:
                - score: 2
                  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
                - date: '2006-01-03'
                  user_id: '180'
    SeqV1Scores202:
      description: 202 Accepted
      content:
        application/json: {}
    SeqV1Scores400:
      description: Bad Request 400
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/SeqError'
          examples:
            from must be provided:
              value:
                errors:
                - field: from
                  message: 'failed to parse request: "from" must be provided'
            to must be provided:
              value:
                errors:
                - field: to
                  message: 'failed to parse request: "to" must be provided'
            from invalid:
              value:
                errors:
                - field: from
                  message: 'failed to parse request: "from" invalid'
            to invalid:
              value:
                errors:
                - field: to
                  message: 'failed to parse request: "to" invalid'
            from cannot be more than 90 days in the past:
              value:
                errors:
                - field: from
                  message: 'failed to parse request: "from" cannot be more than 90
                    days in the past'
            to cannot be more than 90 days in the past:
              value:
                errors:
                - field: to
                  message: 'failed to parse request: "to" cannot be more than 90 days
                    in the past'
            from cannot come after to:
              value:
                errors:
                - field: to
                  message: 'failed to parse request: "from" cannot come after "to"'
            to cannot be in the future:
              value:
                errors:
                - field: to
                  message: 'failed to parse request: "to" cannot be in the future'
    SeqV1Scores500:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/SeqError'
          examples:
            Example 1:
              value:
                errors:
                - message: internal server error
    SeqV1Scores401:
      description: 401 Unauthorized
      content:
        application/json: {}
    SeqV1SubusersScores400:
      description: Bad Request 400
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/SeqError'
          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'
  parameters:
    SeqAfterKey:
      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.
    SeqLimit:
      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.
    SeqDate:
      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.
    OnBehalfOf:
      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 <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**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of)
        for more information.'
      required: false
      schema:
        type: string
  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: Engagement Quality
  description: Twilio SendGrid Engagement Quality API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid