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. A 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.
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.
A 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.
Single 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).
The 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.**
Please 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.
This 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.**
Returns 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.**
To first retrieve all your Single Sends'' IDs, you can make a GET request
to the `/marketing/singlensends` endpoint.
Please 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.**
You only need to pass the properties you want to update. Any blank or missing
properties will remain unaltered.
This 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.**
You 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.**
To first retrieve all your Single Sends'' IDs, you can make a GET request
to the `/marketing/singlensends` endpoint.
Please 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.**
To 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.**
Making 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.**
This 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
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_mc_singlesends_v3.yaml