Single Sends 2020 Update

Action required to ensure successful create, read, and update operations using the Single Sends API.

The Single Sends API has changed. Please check this page for updates and instructions.

To improve your experience when working with the Single Sends API, Twilio SendGrid has streamlined the API’s request and response formats. You will be able to pass all the required information to create a Single Send in one request, eliminating the need to first create a template.

However, these improvements will require modifications to your current code. We’re aware that unplanned work for our customers may be less than ideal. To ease this transition we have released the updated API while continuing to provide the existing API at a new root path for a limited time.

This strategy provides you with two options.

  1. First Option: Make necessary integration changes now.
  2. Second Option: Direct API calls to a new temporary path detailed below, allowing time for integration changes.

Option 1

Beginning May 6, 2020

Customer action:

Make the necessary API integration changes immediately.

Updated API available at:

https://api.sendgrid.com/v3/marketing/singlesends

All requests to the /marketing/singlesends root path must use the updated request format beginning May 6, 2020. Any requests to /marketing/singlesends using the existing Single Sends format will result in a 400-level error.

This first option may not be possible for your development schedule. If you require more time to make this migration, the existing Single Sends API functionality will continue to be available at the marketing/campaigns root path until June, 6 2020. To take advantage of this temporary new path, see the details in Option 2 below.

Option 2

May 6, 2020 – June 6, 2020

Customer action part 1:

Move all Single Sends API requests from the /marketing/singlesends root path to the /marketing/campaigns root path.

Existing API available at:

https://api.sendgrid.com/v3/marketing/campaigns

The existing Single Sends API is currently available at the root path marketing/campaigns. You can optionally direct all requests using the existing API format to this new root path.

Customer action part 2:

Update code to use the new Single Sends request and response body format. Requests in the new format should be made to the /marketing/singlesends root path.

Updated API available at:

https://api.sendgrid.com/v3/marketing/singlesends

Beginning May 6, 2020 the updated API will be available at the root path /marketing/singlesends. At that time, you can begin work to migrate to the new API. If you have not done so already, you can point existing API integrations to the /marketing/campaigns root path through June 6, 2020 while you complete the work.

The existing Single Sends API functionality will be fully removed on June 6, 2020. This means you must fully migrate your API integrations to the updated API before this date. Availability of the existing API at /marketing/campaigns is meant to provide you with a month to fully migrate your code to the New Single Sends API only and should not be relied on after.

API request and response bodies

The new Single Sends API request and response bodies have been refined to contain only five top level fields: name, categories, send_at, send_to, and email_config. Both send_to and email_config are object types containing additional fields.

The email_config field provides the ability to send data that would currently be associated with a template. Rather than first creating a template and then passing a template ID to the Single Sends create endpoint, all template data can be passed in the initial request using the fields in the email_config object.

The table below provides a list of all available fields for both the existing API and updated API. Notes are made where fields have been reorganized in the schema. A full API reference will be made available on May 6, 2020.

Single Sends API fields

Field: Existing Single Sends API

Field: Updated Single Sends API

Notes

Response or Request Field

Data Type

name

name

Both

string

categories

categories

Both

array[string]

sender_id

sender_id

Moved to email_config: sender_id

Both

integer

status

status

Response

string

custom_unsubscribe_url

email_config: custom_unsubscribe_url

Moved to email_config: custom_unsubscribe_url

Both

string

id

id

Response

string

suppression_group_id

id

Moved to email_config: suppression_group_id

Both

integer

filter: list_ids

send_to: list_ids

Moved to send_to: list_ids

Both

array[string]

filter: send_to_all

send_to: all

Moved to send_to: all

Both

boolean

send_at

send_at

Both

string

template_id

NA

string

updated_at

updated_at

Response

string

created_at

created_at

Response

string

ip_pool

email_config: ip_pool

Moved to email_config: ip_pool

Both

string

NA

send_to: segment_ids

Both

array[string]

NA

email_config: subject

Both

string

NA

email_config: html_content

Both

string

NA

email_config: plain_content

Both

string

NA

email_config: generate_plain_content

Both

boolean

NA

email_config: design_id

Request

string

NA

email_config: editor

Both

string

See a mistake? Edit this page