{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Marketing Campaigns Single Sends API", "summary": "The Twilio SendGrid Single Sends API allows you to create, manage, and send Single Sends.", "description": "The Twilio SendGrid Single Sends API allows you to create, manage, and send Single Sends. You can also search Single Sends and retrieve statistics about them to help you maintain, alter, and further develop your campaigns.\n\nA Single Send is a one-time non-automated email message delivered to a list or segment of your audience. A Single Send may be sent immediately or scheduled for future delivery.\n\nSingle Sends can serve many use cases, including promotional offers, engagement campaigns, newsletters, announcements, legal notices, or policy updates. You can also create and manage Single Sends in the [Marketing Campaigns application user interface](https://mc.sendgrid.com/single-sends).\n\nThe Single Sends API changed on May 6, 2020. See [**Single Sends 2020 Update**](https://docs.sendgrid.com/for-developers/sending-email/single-sends-2020-update) for more information.", "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": "mc_singlesends" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "The Twilio SendGrid v3 API" } ], "paths": { "/v3/marketing/singlesends": { "post": { "operationId": "CreateSingleSend", "summary": "Create Single Send", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to create a new Single Send.**\n\nPlease note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object.\n\nThis endpoint will create a draft of the Single Send but will not send it or schedule it to be sent. Any `send_at` property value set with this endpoint will prepopulate the Single Send's send date. However, the Single Send will remain an unscheduled draft until it's updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI.", "requestBody": { "$ref": "#/components/requestBodies/SinglesendRequestBody" }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendResponse" }, "examples": { "response": { "value": { "name": "Example API Created Single Send", "id": "27c21bbf-a12c-440b-b8bf-c526975328ca", "status": "scheduled", "created_at": "2020-05-18T17:28:27.272Z", "categories": [ "unique opens" ], "email_config": { "subject": "", "html_content": "", "plain_content": "", "generate_plain_content": true, "editor": "code", "suppression_group_id": null, "custom_unsubscribe_url": null, "sender_id": null, "ip_pool": null }, "send_to": { "list_ids": [ "f2fe66a1-43f3-4e3a-87b1-c6a600d805f0" ] } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "get": { "operationId": "ListSingleSend", "summary": "Get All Single Sends", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to retrieve all your Single Sends.**\n\nReturns all of your Single Sends with condensed details about each, including the Single Sends' IDs. For more details about an individual Single Send, pass the Single Send's ID to the `/marketing/singlesends/{id}` endpoint.", "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer" } }, { "name": "page_token", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SinglesendResponseShort" } }, "_metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "delete": { "operationId": "DeleteSingleSends", "summary": "Bulk Delete Single Sends", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a DELETE request is permanent, and your Single Sends will not be recoverable after deletion.", "parameters": [ { "name": "ids", "in": "query", "description": "Single Send IDs to delete", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } }, "/v3/marketing/singlesends/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "DuplicateSingleSend", "summary": "Duplicate Single Send", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to duplicate an existing Single Send using its Single Send ID.**\n\nDuplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint.\n \nIf you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text \u201cCopy of \u201d prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including \u201cCopy of \u201d, will be trimmed if the name exceeds this limit.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name of the duplicate Single Send. If you choose to leave the name field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text 'Copy of ' prepended to it. The end of the new Single Send name, including 'Copy of ', will be trimmed if the name exceeds the character limit." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendResponse" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "patch": { "operationId": "UpdateSingleSend", "summary": "Update Single Send", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to update a Single Send using a Single Send ID.**\n\nYou only need to pass the properties you want to update. Any blank or missing properties will remain unaltered.\n\nThis endpoint will update a draft of the Single Send but will not send it or schedule it to be sent. Any `send_at` property value set with this endpoint will prepopulate the Single Send's send date. However, the Single Send will remain an unscheduled draft until it's updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI.", "requestBody": { "$ref": "#/components/requestBodies/SinglesendRequestBody" }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "get": { "operationId": "GetSingleSend", "summary": "Get Single Send by ID", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to retrieve details about one Single Send using a Single Send ID.**\n\nYou can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendResponse" }, "examples": { "response": { "value": { "name": "single-send-1", "id": "2f6dec81-43b9-4c67-a890-3a38cb63b54a", "status": "scheduled", "created_at": "2020-12-13T16:24:42.013Z", "send_to": { "segment_ids": [ "dad84de3-bec4-4e04-b132-2cbfd4bb3789", "7dce758d-1155-4102-88d2-ca65565ac98b" ], "all": true } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "delete": { "operationId": "DeleteSingleSend", "summary": "Delete Single Send by ID", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to delete one Single Send using a Single Send ID.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a `DELETE` request is permanent, and your Single Send will not be recoverable after deletion.", "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } }, "/v3/marketing/singlesends/{id}/schedule": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "ScheduleSingleSend", "summary": "Schedule Single Send", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to send a Single Send immediately or schedule it to be sent at a later time.**\n\nTo send your message immediately, set the `send_at` property value to the string `now`. To schedule the Single Send for future delivery, set the `send_at` value to your desired send time in [ISO 8601 date time format](https://www.iso.org/iso-8601-date-and-time-format.html) (`yyyy-MM-ddTHH:mm:ssZ`).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "send_at": { "type": "string", "description": "The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/).", "format": "date-time" } }, "required": [ "send_at" ], "example": { "send_at": "3752-01-28T23:21:52.575Z" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "send_at": { "type": "string", "description": "The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/).", "format": "date-time" }, "status": { "type": "string", "$ref": "#/components/schemas/Status" } } }, "examples": { "response": { "value": { "send_at": "3752-01-28T23:21:52.575Z", "status": "scheduled" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } }, "delete": { "operationId": "DeleteScheduledSingleSend", "summary": "Delete Single Send Schedule", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to cancel a scheduled Single Send using a Single Send ID.**\n\nMaking a DELETE request to this endpoint will cancel the scheduled sending of a Single Send. The request will not delete the Single Send itself. Deleting a Single Send can be done by passing a DELETE request to `/marketing/singlesends/{id}`.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendSchedule" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } }, "/v3/marketing/singlesends/categories": { "get": { "operationId": "ListCategory", "summary": "Get All Categories", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to retrieve all the categories associated with your Single Sends.**\n\nThis endpoint will return your latest 1,000 categories.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "uniqueItems": true, "maxItems": 1000, "description": "list of latest one thousand unique categories associated with all Single Sends in ascending order", "items": { "type": "string" } } } }, "examples": { "response": { "value": { "categories": [ "equipment", "shoes", "sports" ] } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } }, "/v3/marketing/singlesends/search": { "post": { "operationId": "SearchSingleSend", "summary": "Get Single Sends Search", "tags": [ "Single Sends" ], "description": "**This endpoint allows you to search for Single Sends based on specified criteria.**\n\nYou can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields.\n\nFor example, if you want to search for all Single Sends that are \"drafts\" or \"scheduled\" and also associated with the category \"shoes,\" your request body may look like the example below.\n\n```javascript\n{\n \"status\": [\n \"draft\",\n \"scheduled\"\n ],\n \"categories\": [\n \"shoes\"\n ],\n}\n```", "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer" } }, { "name": "page_token", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendSearch" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SinglesendResponseShort" } }, "_metadata": { "$ref": "#/components/schemas/Metadata" } } }, "examples": { "response": { "value": { "result": [ { "id": "df25ffdf-6a96-458a-9419-6d87d3094c6b", "name": "single-send-1", "status": "triggered", "categories": [ "shoes" ], "is_abtest": true, "abtest": null, "updated_at": "3263-04-09T09:05:08.193Z", "created_at": "4739-10-29T07:11:32.476Z", "send_at": "2471-05-31T15:46:18.797Z" } ], "_metadata": { "self": "https://a/nwNSrPSWt7d", "prev": "https://a/P0Enoayd", "next": "https://a/DYEsTUDww9-", "count": 1 } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } } }, "components": { "schemas": { "SinglesendSearch": { "title": "singlesend_search", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "leading and trailing wildcard search on name of the Single Send" }, "status": { "type": "array", "description": "current status of the Single Send", "uniqueItems": true, "items": { "type": "string", "$ref": "#/components/schemas/Items" } }, "categories": { "type": "array", "description": "categories to associate with this Single Send, match any single send that has at least one of the categories", "uniqueItems": true, "items": { "type": "string" } } } }, "SinglesendRequest": { "title": "singlesend_request", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name of the Single Send." }, "categories": { "type": "array", "uniqueItems": true, "maxItems": 10, "description": "The categories to associate with this Single Send.", "items": { "type": "string" } }, "send_at": { "type": "string", "description": "Set this property to an ISO 8601 formatted date-time when you would like to send the Single Send. Please note that any `send_at` property value set with this endpoint will prepopulate the send date in the SendGrid user interface (UI). However, the Single Send will remain an unscheduled draft until it's updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI. Additionally, the `now` keyword is a valid `send_at` value only when using the Schedule Single Send endpoint. Setting this property to `now` with this endpoint will cause an error.", "format": "date-time", "nullable": true }, "send_to": { "type": "object", "properties": { "list_ids": { "type": "array", "description": "The recipient List IDs that will receive the Single Send.", "maxItems": 50, "items": { "type": "string", "format": "uuid" } }, "segment_ids": { "type": "array", "description": "The recipient Segment IDs that will receive the Single Send.", "maxItems": 10, "items": { "type": "string", "format": "uuid" } }, "all": { "type": "boolean", "description": "Set to `true` to send to All Contacts. If set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent to recipients.", "default": false } } }, "email_config": { "type": "object", "properties": { "subject": { "type": "string", "description": "The subject line of the Single Send. Do not include this field when using a `design_id`." }, "html_content": { "type": "string", "description": "The HTML content of the Single Send. Do not include this field when using a `design_id`." }, "plain_content": { "type": "string", "description": "The plain text content of the Single Send. Do not include this field when using a `design_id`." }, "generate_plain_content": { "type": "boolean", "description": "If set to `true`, `plain_content` is always generated from `html_content`. If set to false, `plain_content` is not altered.", "default": true }, "design_id": { "type": "string", "description": "A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design's ID from the [\"List Designs\" endpoint](https://docs.sendgrid.com/api-reference/designs-api/list-designs) or by pulling it from the design's detail page URL in the Marketing Campaigns App." }, "editor": { "type": "string", "description": "The editor \u2014 `\"design\"` or `\"code\"` \u2014 used to modify the Single Send's design in the Marketing Campaigns App.", "default": "code", "$ref": "#/components/schemas/Editor" }, "suppression_group_id": { "description": "The ID of the Suppression Group to allow recipients to unsubscribe \u2014 you must provide this or the `custom_unsubscribe_url`.", "nullable": true, "type": "integer" }, "custom_unsubscribe_url": { "description": "The URL allowing recipients to unsubscribe \u2014 you must provide this or the `suppression_group_id`.", "format": "uri", "nullable": true, "type": "string" }, "sender_id": { "description": "The ID of the verified Sender. You can retrieve a verified Sender's ID from the [\"Get Verified Senders\" endpoint](https://www.twilio.com/docs/sendgrid/api-reference/sender-verification/get-all-verified-senders) or by pulling it from the Sender's detail page URL in the SendGrid App.", "nullable": true, "type": "integer" }, "ip_pool": { "description": "The name of the IP Pool from which the Single Send emails are sent.", "nullable": true, "type": "string" } } } }, "required": [ "name" ] }, "SinglesendSchedule": { "title": "singlesend-schedule", "type": "object", "properties": { "send_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/)." }, "status": { "type": "string", "$ref": "#/components/schemas/Status1" } }, "required": [ "send_at" ] }, "SinglesendResponse": { "title": "singlesend_response", "type": "object", "properties": { "id": { "type": "string", "description": "The unique ID for the Single Send.", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name of the Single Send." }, "status": { "type": "string", "description": "The current status of the Single Send. The status may be `draft`, `scheduled`, or `triggered`.", "$ref": "#/components/schemas/Status2" }, "categories": { "type": "array", "uniqueItems": true, "maxItems": 10, "description": "The categories associated with this Single Send.", "items": { "type": "string" } }, "send_at": { "type": "string", "description": "An ISO 8601 formatted date-time when the Single Send is set to be sent. Please note that any `send_at` property value will have no effect while the Single Send `status` is `draft`. You must update the Single Send with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI to schedule it.", "format": "date-time", "nullable": true }, "send_to": { "type": "object", "properties": { "list_ids": { "type": "array", "description": "The IDs of each contact list to which the Single Send will be sent.", "maxItems": 50, "items": { "type": "string", "format": "uuid" } }, "segment_ids": { "type": "array", "description": "The IDs of each segment to which the Single Send will be sent.", "maxItems": 10, "items": { "type": "string", "format": "uuid" } }, "all": { "type": "boolean", "description": "If this property is set to `true`, the Single Send will be sent to all of your contacts. If it's set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent.", "default": false } } }, "updated_at": { "type": "string", "description": "the ISO 8601 time at which the Single Send was last updated.", "format": "date-time" }, "created_at": { "type": "string", "description": "the ISO 8601 time at which the Single Send was created.", "format": "date-time" }, "email_config": { "type": "object", "properties": { "subject": { "type": "string", "description": "The subject line of the Single Send. This property is not used when a `design_id` value is set." }, "html_content": { "type": "string", "description": "The HTML content of the Single Send. This property is not used when a `design_id` value is set." }, "plain_content": { "type": "string", "description": "The plain text content of the Single Send. This property is not used when a `design_id` value is set." }, "generate_plain_content": { "type": "boolean", "description": "If this property is set to `true`, `plain_content` is always generated from `html_content`. If it's set to false, `plain_content` is not altered.", "default": true }, "design_id": { "type": "string", "description": "A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design's ID from the [**List Designs** endpoint](https://docs.sendgrid.com/api-reference/designs-api/list-designs) or by pulling it from the design's detail page URL in the Marketing Campaigns App." }, "editor": { "type": "string", "description": "The editor, `design` or `code`, used to modify the Single Send's design in the Marketing Campaigns application user interface.", "default": "code", "$ref": "#/components/schemas/Editor1" }, "suppression_group_id": { "description": "The ID of the Suppression Group to allow recipients to unsubscribe. You must provide a `suppression_group_id` or the `custom_unsubscribe_url` with your Single Send.", "nullable": true, "type": "integer" }, "custom_unsubscribe_url": { "description": "The URL allowing recipients to unsubscribe. You must provide a `custom_unsubscribe_url` or a `suppression_group_id` with your Single Send.", "format": "uri", "nullable": true, "type": "string" }, "sender_id": { "description": "The ID of the verified sender from whom the Single Send will be sent. You can retrieve a verified sender's ID from the [**Get Verified Senders** endpoint](https://www.twilio.com/docs/sendgrid/api-reference/sender-verification/get-all-verified-senders) or by pulling it from the sender's detail page URL in the SendGrid App.", "nullable": true, "type": "integer" }, "ip_pool": { "description": "The name of the IP Pool from which the Single Send emails are sent.", "nullable": true, "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" }, "warning_id": { "type": "string" } } } } } }, "SinglesendResponseShort": { "title": "singlesend_response_short", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "name of the Single Send" }, "abtest": { "$ref": "#/components/schemas/AbTestSummary" }, "status": { "type": "string", "description": "current status of the Single Send", "$ref": "#/components/schemas/Status3" }, "categories": { "type": "array", "uniqueItems": true, "maxItems": 10, "description": "categories to associate with this Single Send", "items": { "type": "string" } }, "send_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/)." }, "is_abtest": { "type": "boolean", "description": "true if the Single Send's AB Test functionality has been toggled on" }, "updated_at": { "type": "string", "description": "the ISO 8601 time at which the Single Send was last updated", "format": "date-time" }, "created_at": { "type": "string", "description": "the ISO 8601 time at which the Single Send was created", "format": "date-time" } }, "required": [ "id", "name", "abtest", "status", "categories", "is_abtest", "updated_at", "created_at" ] }, "AbTestSummary": { "title": "abTest_summary", "properties": { "type": { "type": "string", "description": "What differs between the A/B tests", "$ref": "#/components/schemas/Type" }, "winner_criteria": { "type": "string", "description": "How the winner will be decided", "$ref": "#/components/schemas/WinnerCriteria" }, "test_percentage": { "type": "integer", "description": "What percentage of your recipient will be included in your A/B testing" }, "duration": { "type": "string", "description": "How long the A/B Testing will last" }, "winning_template_id": { "type": "string", "description": "Winner of the A/B Test" }, "winner_selected_at": { "description": "When the winner was selected", "nullable": true, "type": "string" }, "expiration_date": { "description": "Last day to select an A/B Test Winner", "nullable": true, "type": "string" } }, "required": [ "type", "winner_criteria", "test_percentage", "duration", "winning_template_id", "winner_selected_at", "expiration_date" ], "nullable": true, "type": "object" }, "Metadata": { "title": "_metadata", "type": "object", "properties": { "prev": { "type": "string", "format": "uri" }, "self": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "count": { "type": "integer", "minimum": 0 } } }, "Status": { "type": "string", "enum": [ "scheduled" ] }, "Items": { "type": "string", "enum": [ "draft", "scheduled", "triggered" ] }, "Editor": { "type": "string", "enum": [ "code", "design" ] }, "Status1": { "type": "string", "enum": [ "draft", "scheduled", "triggered" ] }, "Status2": { "type": "string", "enum": [ "draft", "scheduled", "triggered" ] }, "Editor1": { "type": "string", "enum": [ "code", "design" ] }, "Status3": { "type": "string", "enum": [ "draft", "scheduled", "triggered" ] }, "Type": { "type": "string", "enum": [ "subject", "content" ] }, "WinnerCriteria": { "type": "string", "enum": [ "open", "click", "manual" ] } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": { "SinglesendRequestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglesendRequest" } } } } }, "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": "Single Sends", "description": "Twilio SendGrid Marketing Campaigns Single Sends API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }