openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Alerts API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  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: account_provisioning
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: Alerts
  description: Twilio SendGrid Alerts API.
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: test@example.com'
                  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: example@example.com
                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: test@example.com
                    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: example1@example.com
                    id: 46
                    percentage: 90
                    type: usage_limit
                    updated_at: 1451498784
                  - created_at: 1451498812
                    email_to: example2@example.com
                    frequency: monthly
                    id: 47
                    type: stats_notification
                    updated_at: 1451498812
                  - created_at: 1451520930
                    email_to: example3@example.com
                    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: example@example.com
                    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: test@example.com'
                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: example@example.com
      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: example@example.com
                    frequency: daily
                    id: 48
                    type: stats_notification
                    updated_at: 1451522691
components:
  schemas:
    Type:
      type: string
      enum:
      - stats_notification
      - usage_limit
    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.
    Type1:
      type: string
      enum:
      - usage_limit
      - stats_notification
    Type3:
      type: string
      enum:
      - usage_limit
      - stats_notification
    Type2:
      type: string
      enum:
      - usage_limit
      - stats_notification
  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
  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