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 Single Send by ID

GET /marketing/singlesends/{id}

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.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Path Parameters

id
string
default: None
required

Responses

object
name
string

The name of the Single Send.

maxLength: 100minLength: 1
required
categories
array[string]

The categories to associate with this Single Send.

maxItems: 10uniqueItems: True
send_at
string

The ISO 8601 time at which to send the Single Send — this must be set for a future time.

format: date-time
send_to
object
list_ids
array[string]

The recipient List IDs that will receive the Single Send.

maxItems: 10
segment_ids
array[string]

The recipient Segment IDs that will receive the Single Send.

maxItems: 10
all
boolean

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
object
subject
string

The subject line of the Single Send. Do not include this field when using a design_id.

html_content
string

The HTML content of the Single Send. Do not include this field when using a design_id.

plain_content
string

The plain text content of the Single Send. Do not include this field when using a design_id.

generate_plain_content
boolean

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
string

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 or by pulling it from the design's detail page URL in the Marketing Campaigns App.

editor
string

The editor — "design" or "code" — used to modify the Single Send's design in the Marketing Campaigns App.

default: codeAllowed Values: code, design
suppression_group_id
integer or null

The ID of the Suppression Group to allow recipients to unsubscribe — you must provide this or the custom_unsubscribe_url.

custom_unsubscribe_url
string or null

The URL allowing recipients to unsubscribe — you must provide this or the suppression_group_id.

format: uri
sender_id
integer or null

The ID of the verified Sender. You can retrieve a verified Sender's ID from the "Get Verified Senders" endpoint or by pulling it from the Sender's detail page URL in the SendGrid App.

ip_pool
string or null

The name of the IP Pool from which the Single Send emails are sent.

id
string
format: uuid
required
status
string

current status of the Single Send

Allowed Values: draft, scheduled, triggered
required
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
required
warnings
array[object]
message
string
field
string
warning_id
string
{
  "name": "Example API Created Single Send",
  "id": "27c21bbf-a12c-440b-b8bf-c526975328ca",
  "status": "scheduled",
  "created_at": "2020-05-18T17:28:27.272Z",
  "send_at": "2020-06-16T00:19:55.106Z",
  "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"
    ]
  }
}
object
errors
array[object]
field
string
message
string
error_id
string
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. How could this documentation serve you better?

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