Menu

Single Sends

A Single Send is a one-time nonautomated 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.

The Single Sends API allows you to create, retrieve, update, delete, schedule, and deliver your Single Sends. There are also endpoints for searching and statistics to help you maintain and alter your Single Sends as you learn more and further develop your campaigns.

The Single Sends API changed on May 6, 2020. Please check the SendGrid Knowledge Center for updates and instructions here: https://sendgrid.com/docs/for-developers/sending-email/single-sends-2020-update/

Get All Single Sends

Get All Single Sends

GET /marketing/singlesends

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.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Query String

page_size
integer

number of results to return

default: 100minimum: 0
page_token
string

token corresponding to a specific page of results, as provided by metadata

Responses

object
result
array[object]
id
string
format: uuid
name
string

name of the Single Send

maxLength: 100minLength: 1
abtest
object
type
string

What differs between the A/B tests

Allowed Values: subject, content
required
winner_criteria
string

How the winner will be decided

Allowed Values: open, click, manual
required
test_percentage
integer

What percentage of your recipient will be included in your A/B testing

required
duration
string

How long the A/B Testing will last

required
winning_template_id
string

Winner of the A/B Test

required
winner_selected_at
string

When the winner was selected

required
expiration_date
string

Last day to select an A/B Test Winner

required
status
string

current status of the Single Send

Allowed Values: draft, scheduled, triggered
categories
array[string]

categories to associate with this Single Send

maxItems: 10uniqueItems: True
send_at
string

the ISO 8601 time at which to send the Single Send; must be in future

format: date-time
is_abtest
boolean

true if the Single Send's AB Test functionality has been toggled on

updated_at
string

the ISO 8601 time at which the Single Send was last updated

format: date-time
created_at
string

the ISO 8601 time at which the Single Send was created

format: date-time
_metadata
object
prev
string
format: uri
self
string
format: uri
next
string
format: uri
count
integer
minimum: 0
object
errors
array[object]
field
string
message
string
error_id
string

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.