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: 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: 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 `). 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**](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