SendGrid Spam Reports API

openapi: 3.2.0
info:
  title: Twilio SendGrid Suppressions Spam Reports API
  summary: The Twilio SendGrid Suppressions API allows you to manage your Suppressions or Unsubscribes and Suppression or Unsubscribe groups.
  description: The Twilio SendGrid Suppressions API allows you to manage your Suppressions or Unsubscribes and Suppression or Unsubscribe groups.
  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: suppressions
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Spam Reports
  description: 'Twilio SendGrid Suppressions API: Spam Reports operations'
paths:
  /v3/suppression/spam_reports:
    get:
      operationId: ListSpamReport
      summary: Retrieve all spam reports
      tags:
      - Spam Reports
      description: '**This endpoint allows you to retrieve a paginated list of all spam reports.**


        You can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.'
      parameters:
      - name: start_time
        in: query
        description: The start of the time range when a spam report was created (inclusive). This is a unix timestamp.
        schema:
          type: integer
      - name: end_time
        in: query
        description: The end of the time range when a spam report was created (inclusive). This is a unix timestamp.
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - $ref: '#/components/parameters/EmailPartialMatch'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpamReportsResponse'
              examples:
                response:
                  value:
                  - created: 1443651141
                    email: user1@example.com
                    ip: 10.63.202.100
                  - created: 1443651154
                    email: user2@example.com
                    ip: 10.63.202.100
    delete:
      operationId: DeleteSpamReports
      summary: Delete spam reports
      tags:
      - Spam Reports
      description: '**This endpoint allows you to delete your spam reports.**


        Deleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our bypass filters to deliver messages to otherwise suppressed addresses when exceptions are required.


        There are two options for deleting spam reports:


        1. You can delete all spam reports by setting the `delete_all` field to `true` in the request body.

        2. You can delete a list of select spam reports by specifying the email addresses in the `emails` array of the request body.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                  description: Indicates if you want to delete all email addresses on the spam report list.
                emails:
                  type: array
                  description: A list of specific email addresses that you want to remove from the spam report list.
                  items:
                    type: string
              example:
                delete_all: false
                emails:
                - example1@example.com
                - example2@example.com
      responses:
        '204':
          description: ''
  /v3/suppression/spam_reports/{email}:
    parameters:
    - name: email
      in: path
      description: The email address of a specific spam report that you want to retrieve.
      required: true
      schema:
        type: string
        format: email
    get:
      operationId: GetSpamReport
      summary: Retrieve a specific spam report
      tags:
      - Spam Reports
      description: '**This endpoint allows you to retrieve a specific spam report by email address.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpamReportsResponse'
              examples:
                response:
                  value:
                  - created: 1454433146
                    email: test1@example.com
                    ip: 10.89.32.5
    delete:
      operationId: DeleteSpamReport
      summary: Delete a specific spam report
      tags:
      - Spam Reports
      description: '**This endpoint allows you to delete a specific spam report by email address.**


        Deleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our bypass filters to deliver messages to otherwise suppressed addresses when exceptions are required.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
components:
  parameters:
    PaginationCommonLimit:
      name: limit
      in: query
      required: false
      description: '`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is 500 items per page.'
      schema:
        type: integer
        minimum: 1
        maximum: 500
    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>`). It is important to use the Base URL that corresponds to the region of the account or Subuser you specify in the `on-behalf-of` header. 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
    EmailPartialMatch:
      name: email
      in: query
      description: Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as `salesdepartment@example.com` or `sales@example.com`.  You can also use `%25` as a wildcard. For example, `%25market` returns records containing email addresses with the string 'market' anywhere in the email address, and `%25market%25tree` returns records containing email addresses with the string 'market' followed by the string 'tree'. Any reserved characters should be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters), e.g., the `@` symbol should be encoded as `%40`.
      required: false
      schema:
        type: string
    PaginationCommonOffset:
      name: offset
      in: query
      required: false
      description: The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    SpamReportsResponse:
      title: Spam Reports Response
      type: array
      items:
        type: object
        properties:
          created:
            type: integer
            description: A Unix timestamp that indicates when the recipient marked your message as spam.
          email:
            type: string
            description: The email address of the recipient that marked your message as spam.
            format: email
          ip:
            type: string
            description: The IP address that the message was sent from.
        required:
        - created
        - email
        - ip
      example:
      - created: 1443651141
        email: user1@example.com
        ip: 10.63.202.100
      - created: 1443651154
        email: user2@example.com
        ip: 10.63.202.100
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid