{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Scheduled Sends API", "summary": "The Twilio SendGrid Scheduled Sends API allows you to cancel or pause the send of one or more emails using a batch ID.", "description": "The Twilio SendGrid Scheduled Sends API allows you to cancel or pause the send of one or more emails using a batch ID.\n\nA `batch_id` groups multiple scheduled mail send requests together with the same ID. You can cancel or pause all of the requests associated with a batch ID up to 10 minutes before the scheduled send time.\n\nSee [**Canceling a Scheduled Send**](https://docs.sendgrid.com/for-developers/sending-email/stopping-a-scheduled-send) for a guide on creating a `batch_id`, assigning it to a scheduled send, and modifying the send.\n\nSee the Mail API's batching operations to validate a `batch_id` and retrieve all scheduled sends as an array.\n\nWhen a batch is canceled, all messages associated with that batch will stay in your sending queue. When their `send_at` value is reached, they will be discarded.\n\nWhen a batch is paused, all messages associated with that batch will stay in your sending queue, even after their `send_at` value has passed. This means you can remove a pause status, and your scheduled send will be delivered once the pause is removed. Any messages left with a pause status that are more than 72 hours old will be discarded as Expired.", "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": "scheduled_sends" } }, "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/user/scheduled_sends": { "post": { "operationId": "CreateScheduledSend", "summary": "Cancel or pause a scheduled send", "tags": [ "Scheduled Sends" ], "description": "**This endpoint allows you to cancel or pause a scheduled send associated with a `batch_id`.**\n\nPassing this endpoint a `batch_id` and status will cancel or pause the scheduled send.\n\nOnce a scheduled send is set to `pause` or `cancel` you must use the \"Update a scheduled send\" endpoint to change its status or the \"Delete a cancellation or pause from a scheduled send\" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a `400` level status code.\n\nIf the maximum number of cancellations/pauses are added to a send, a `400` level status code will be returned.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Cancel or pause a scheduled send request", "type": "object", "properties": { "batch_id": { "type": "string", "description": "The batch ID is the identifier that your scheduled mail sends share.", "pattern": "^[a-zA-Z0-9]" }, "status": { "type": "string", "default": "pause", "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}", "$ref": "#/components/schemas/Status" } }, "required": [ "batch_id", "status" ], "example": { "batch_id": "YOUR_BATCH_ID", "status": "pause" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledSendStatus" } } } }, "400": { "$ref": "#/components/responses/ScheduledSends400" }, "401": { "$ref": "#/components/responses/ScheduledSends401" }, "403": { "$ref": "#/components/responses/ScheduledSends403" }, "404": { "$ref": "#/components/responses/ScheduledSends404" }, "500": { "$ref": "#/components/responses/ScheduledSends500" } } }, "get": { "operationId": "ListScheduledSend", "summary": "Retrieve all scheduled sends", "tags": [ "Scheduled Sends" ], "description": "**This endpoint allows you to retrieve all cancelled and paused scheduled send information.**\n\nThis endpoint will return only the scheduled sends that are associated with a `batch_id`. If you have scheduled a send using the `/mail/send` endpoint and the `send_at` field but no `batch_id`, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a `batch_id` to any scheduled send you may need to pause or cancel in the future.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledSendStatus" } }, "examples": { "response": { "value": [ { "batch_id": "QzZmYzLTVWIwYgYzJlM2NhNWI", "status": "cancel" }, { "batch_id": "mQzZmYzLTVlM2NhNWIwYgYzJl", "status": "cancel" } ] } } } } }, "400": { "$ref": "#/components/responses/ScheduledSends400" }, "401": { "$ref": "#/components/responses/ScheduledSends401" }, "403": { "$ref": "#/components/responses/ScheduledSends403" }, "404": { "$ref": "#/components/responses/ScheduledSends404" }, "500": { "$ref": "#/components/responses/ScheduledSends500" } } } }, "/v3/user/scheduled_sends/{batch_id}": { "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetScheduledSend", "summary": "Retrieve scheduled send", "tags": [ "Scheduled Sends" ], "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "title": "Retrieve scheduled send response", "items": { "$ref": "#/components/schemas/ScheduledSendStatus" } }, "examples": { "response": { "value": [ { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", "status": "cancel" }, { "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", "status": "pause" } ] } } } } }, "400": { "$ref": "#/components/responses/ScheduledSends400" }, "401": { "$ref": "#/components/responses/ScheduledSends401" }, "403": { "$ref": "#/components/responses/ScheduledSends403" }, "404": { "$ref": "#/components/responses/ScheduledSends404" }, "500": { "$ref": "#/components/responses/ScheduledSends500" } } }, "patch": { "operationId": "UpdateScheduledSend", "summary": "Update a scheduled send", "tags": [ "Scheduled Sends" ], "description": "**This endpoint allows you to update the status of a scheduled send for the given `batch_id`.**\n\nIf you have already set a `cancel` or `pause` status on a scheduled send using the \"Cancel or pause a scheduled send\" endpoint, you can update it's status using this endpoint. Attempting to update a status once it has been set with the \"Cancel or pause a scheduled send\" endpoint will result in a `400` error.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The status you would like the scheduled send to have.", "$ref": "#/components/schemas/Status1" } }, "required": [ "status" ], "example": { "status": "pause" } } } } }, "responses": { "204": { "description": "" }, "400": { "$ref": "#/components/responses/ScheduledSends400" }, "401": { "$ref": "#/components/responses/ScheduledSends401" }, "403": { "$ref": "#/components/responses/ScheduledSends403" }, "404": { "$ref": "#/components/responses/ScheduledSends404" }, "500": { "$ref": "#/components/responses/ScheduledSends500" } } }, "delete": { "operationId": "DeleteScheduledSend", "summary": "Delete a cancellation or pause from a scheduled send", "tags": [ "Scheduled Sends" ], "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nScheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "400": { "$ref": "#/components/responses/ScheduledSends400" }, "401": { "$ref": "#/components/responses/ScheduledSends401" }, "403": { "$ref": "#/components/responses/ScheduledSends403" }, "404": { "$ref": "#/components/responses/ScheduledSends404" }, "500": { "$ref": "#/components/responses/ScheduledSends500" } } } } }, "components": { "schemas": { "ScheduledSendStatus": { "title": "User Scheduled Send status", "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", "status": "pause" }, "type": "object", "properties": { "batch_id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-\\_]" }, "status": { "type": "string", "description": "The status of the scheduled send.", "$ref": "#/components/schemas/Status2" } }, "required": [ "batch_id", "status" ] }, "MailBatchId": { "title": "Mail Batch ID", "type": "object", "properties": { "batch_id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-\\_]" } }, "required": [ "batch_id" ], "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" } }, "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." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "Status": { "type": "string", "enum": [ "pause", "cancel" ] }, "Status1": { "type": "string", "enum": [ "cancel", "pause" ] }, "Status2": { "type": "string", "enum": [ "cancel", "pause" ] } }, "responses": { "ScheduledSends400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ScheduledSends401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ScheduledSends403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ScheduledSends404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ScheduledSends500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "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": "Scheduled Sends", "description": "Twilio SendGrid Scheduled Sends API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }