{ "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.\n\nFor 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.\nExample: usage_limit", "$ref": "#/components/schemas/Type" }, "email_to": { "type": "string", "description": "The email address the alert will be sent to.\nExample: test@example.com", "format": "email", "nullable": true }, "frequency": { "type": "string", "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily" }, "percentage": { "type": "integer", "description": "Required for usage_limit. When this usage threshold is reached, the alert will be sent.\nExample: 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.\nExample: test@example.com" }, "frequency": { "type": "string", "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly" }, "percentage": { "type": "integer", "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 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" } }