Twilio SendGrid Alerts API

openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Alerts API
  summary: The Twilio SendGrid Alerts API allows you to specify an email address to
    receive notifications regarding your email usage or statistics.
  description: 'The Twilio SendGrid Alerts API allows you to specify an email address
    to receive notifications regarding your email usage or statistics. You can set
    up alerts to be sent to a specific email address on a recurring basis, whether
    for informational purposes or when specific account actions occur.


    For most alerts, you can choose to have the alert sent to you as needed, hourly,
    daily, weekly, or monthly. The information contained in your alert will be for
    the last period of the alert. For example, if you choose weekly for the statistics
    alert, you will receive the statistics for the last week.'
  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: alerts
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/alerts:
    post:
      operationId: CreateAlert
      summary: Create a new Alert
      tags:
      - Alerts
      description: '**This endpoint allows you to create a new alert.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: 'The type of alert you want to create. Can be either
                    usage_limit or stats_notification.

                    Example: usage_limit'
                  $ref: '#/components/schemas/Type'
                email_to:
                  type: string
                  description: 'The email address the alert will be sent to.

                    Example: [email protected]'
                  format: email
                  nullable: true
                frequency:
                  type: string
                  description: 'Required for stats_notification. How frequently the
                    alert will be sent.

                    Example: daily'
                percentage:
                  type: integer
                  description: 'Required for usage_limit. When this usage threshold
                    is reached, the alert will be sent.

                    Example: 90'
              required:
              - type
              - email_to
              example:
                type: stats_notification
                email_to: [email protected]
                frequency: daily
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was created.
                  email_to:
                    type: string
                    description: The email address that the alert will be sent to.
                    format: email
                  frequency:
                    type: string
                    description: If the alert is of type stats_notification, this
                      indicates how frequently the stats notifications will be sent.
                      For example, "daily", "weekly", or "monthly".
                  id:
                    type: integer
                    description: The ID of the alert.
                  type:
                    type: string
                    description: The type of alert.
                  updated_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was last
                      modified.
                  percentage:
                    type: integer
                    description: If the alert is of type `usage_limit`, this indicates
                      the percentage of email usage that must be reached before the
                      alert will be sent.
                required:
                - created_at
                - email_to
                - id
                - type
                - updated_at
              examples:
                response:
                  value:
                    created_at: 1451520930
                    email_to: [email protected]
                    frequency: daily
                    id: 48
                    type: stats_notification
                    updated_at: 1451520930
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: ListAlert
      summary: Retrieve all alerts
      tags:
      - Alerts
      description: '**This endpoint allows you to retrieve all of your alerts.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                description: The list of alerts.
                items:
                  type: object
                  properties:
                    created_at:
                      type: integer
                      description: A Unix timestamp indicating when the alert was
                        created.
                    email_to:
                      type: string
                      description: The email address that the alert will be sent to.
                    id:
                      type: integer
                      description: The ID of the alert.
                    percentage:
                      type: integer
                      description: If the alert is of type usage_limit, this indicates
                        the percentage of email usage that must be reached before
                        the alert will be sent.
                    type:
                      type: string
                      description: The type of alert.
                      $ref: '#/components/schemas/Type1'
                    updated_at:
                      type: integer
                      description: A Unix timestamp indicating when the alert was
                        last modified.
                    frequency:
                      type: string
                      description: If the alert is of type stats_notification, this
                        indicates how frequently the stats notifications will be sent.
                        For example, "daily", "weekly", or "monthly".
                  required:
                  - created_at
                  - email_to
                  - id
                  - type
              examples:
                response:
                  value:
                  - created_at: 1451498784
                    email_to: [email protected]
                    id: 46
                    percentage: 90
                    type: usage_limit
                    updated_at: 1451498784
                  - created_at: 1451498812
                    email_to: [email protected]
                    frequency: monthly
                    id: 47
                    type: stats_notification
                    updated_at: 1451498812
                  - created_at: 1451520930
                    email_to: [email protected]
                    frequency: daily
                    id: 48
                    type: stats_notification
                    updated_at: 1451520930
  /v3/alerts/{alert_id}:
    parameters:
    - name: alert_id
      in: path
      description: The ID of the alert you would like to retrieve.
      required: true
      schema:
        type: integer
    get:
      operationId: GetAlert
      summary: Retrieve a specific alert
      tags:
      - Alerts
      description: '**This endpoint allows you to retrieve a specific alert.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was created.
                  email_to:
                    type: string
                    description: The email address that the alert will be sent to.
                  frequency:
                    type: string
                    description: 'If the alert is of type stats_notification, this
                      indicates how frequently the stats notifications will be sent.
                      For example: "daily", "weekly", or "monthly".'
                  id:
                    type: integer
                    description: The ID of the alert.
                  type:
                    type: string
                    description: The type of alert.
                    $ref: '#/components/schemas/Type2'
                  updated_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was last
                      modified.
                  percentage:
                    type: integer
                    description: If the alert is of type usage_limit, this indicates
                      the percentage of email usage that must be reached before the
                      alert will be sent.
                required:
                - created_at
                - email_to
                - id
                - type
                - updated_at
              examples:
                response:
                  value:
                    created_at: 1451520930
                    email_to: [email protected]
                    frequency: daily
                    id: 48
                    type: stats_notification
                    updated_at: 1451520930
    delete:
      operationId: DeleteAlert
      summary: Delete an alert
      tags:
      - Alerts
      description: '**This endpoint allows you to delete an alert.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
    patch:
      operationId: UpdateAlert
      summary: Update an alert
      tags:
      - Alerts
      description: '**This endpoint allows you to update an alert.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email_to:
                  type: string
                  description: 'The new email address you want your alert to be sent
                    to.

                    Example: [email protected]'
                frequency:
                  type: string
                  description: 'The new frequency at which to send the stats_notification
                    alert.

                    Example: monthly'
                percentage:
                  type: integer
                  description: 'The new percentage threshold at which the usage_limit
                    alert will be sent.

                    Example: 90'
              example:
                email_to: [email protected]
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was created.
                  email_to:
                    type: string
                    description: The email address that the alert will be sent to.
                  frequency:
                    type: string
                    description: 'If the alert is of type stats_notification, this
                      indicates how frequently the stats notifications will be sent.
                      For example: "daily", "weekly", or "monthly".'
                  id:
                    type: integer
                    description: The ID of the alert.
                  type:
                    type: string
                    description: The type of alert.
                    $ref: '#/components/schemas/Type3'
                  updated_at:
                    type: integer
                    description: A Unix timestamp indicating when the alert was last
                      modified.
                  percentage:
                    type: integer
                    description: If the alert is of type usage_limit, this indicates
                      the percentage of email usage that must be reached before the
                      alert will be sent.
                required:
                - created_at
                - email_to
                - id
                - type
                - updated_at
              examples:
                response:
                  value:
                    created_at: 1451520930
                    email_to: [email protected]
                    frequency: daily
                    id: 48
                    type: stats_notification
                    updated_at: 1451522691
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field
                  that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text
                  or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
    Type:
      type: string
      enum:
      - stats_notification
      - usage_limit
    Type1:
      type: string
      enum:
      - usage_limit
      - stats_notification
    Type2:
      type: string
      enum:
      - usage_limit
      - stats_notification
    Type3:
      type: string
      enum:
      - usage_limit
      - stats_notification
  responses: {}
  parameters:
    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: Alerts
  description: Twilio SendGrid Alerts API.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid