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 /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: None
page_token
string

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

default: None

Responses

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

name of the Single Send

maxLength: 100minLength: 1
abtest
object or null
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 or null

When the winner was selected

required
expiration_date
string or null

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
        
        
        
        Rate this page:

        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.

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more