On this page

Updates to the new SendGrid Legacy API

Twilio is rolling these updates in increments. Look for an email with the subject line [System Upgrade] Upcoming Improvements to Your Twilio SendGrid Legacy Marketing Campaigns Experience. That email message outlines when these updates apply to your account.

This release updated the following resources in the Campaigns, Lists, Recipients, and Segments collections. It also adds a new collection: Exports.

Updates to the Campaigns resources

Create a campaign

Updates capabilities of these resources: POST /v3/campaigns and PATCH /v3/campaigns/{campaign_id}.

This update converts the substitution tag format from [[ sender_field ]], [% recipient_field %], or <% unsubscribe_field %> to {{ field_name }}.

Updates text of some error messages. Examples include those in the following table:

Previous error message	Updated error message
title can't be blank	title cannot be empty string
title is too long (maximum is 100 characters)	title cannot have more than 100 characters
categories exceeds 10 category limit	cannot have more than 10 categories
html_content exceeds the 1MB limit	Omitted from response, still applies
plain_content exceeds the 1MB limit	Omitted from response, still applies
sender_id does not exist	must be a validated sender identity
sender_id is not a verified sender identity	must be a validated sender identity
list_ids do not all exist	invalid list id: `<id>`
segment_ids do not all exist	invalid segment id: `<id>`
The ip pool you provided is invalid	must be a validated IP Pool: `<id>`
suppression_group_id does not exist	[ suppression_group_id ] must be a valid id
Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.	must have either a custom unsubscribe url or suppression group id, not both
The JSON you have submitted cannot be parsed.	json could not be unmarshalled
You've reached your limit of 250 campaigns. Please delete one or more and try again.	you have reached your 10000 Single Sends limit

Schedule a Campaign

Updates text of some error messages from this resource: POST /v3/campaigns/{campaign_id}/schedules.

Examples include those in the following table:

Previous error message	Updated error message
subject can't be blank	[ subject ] No value has been set for this field, this field must have a valid value to schedule the single send. For more details, please view the documentation at https://www.twilio.com/docs/sendgrid/api-reference/single-sends/create-single-send
sender_id can't be blank	must be a validated sender identity
plain_content can't be blank, please provide plain text or html content	Removed
You must select at least 1 segment or 1 list to send to.	Removed
An [unsubscribe] tag in both your html and plain content is required to send a campaign.	Removed
The unsubscribe tag is added to both contents automatically when editing a new campaign	Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. Must have either a custom unsubscribe url or suppression group id to schedule
You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing	This error is no longer present, sends past the allotment are billed as an overage

Updates to the Lists resources

Retrieve all lists

Adds pagination query parameters to this resource: GET /v3/contactdb/lists.

Adds the page_size query parameters with a default value of 5000.
Adds the page query parameters with a default value of 1.

Retrieve all recipients on a List

Removes pagination query parameters from this resource: GET /v3/contactdb/lists/{list_id}/recipients.

You can't set page size and page number query parameters.
The endpoint shows the last 50 contacts added to the list.
To get all contacts in one list or overall, use the /v3/contactdb/exports endpoints.

Delete multiple lists

Ends validation of "in use" campaign lists for this resource: DELETE /v3/contactdb/lists.

Don't delete a list that a campaign scheduled for later.
If the list no longer exists, sending a mail fails.

Updates to the Recipients resources

Retrieve recipients

Removes pagination query parameters from this resource: GET /v3/contactdb/recipients

This resource ignores page_size and page query parameters.
The endpoint shows the last 50 uploaded contacts.
To get all contacts in one list or overall, use the export resources.
The last_emailed, last_clicked, last_opened don't populate. To query contacts using these fields, use the Segments functionality.

Add recipients

Adds limits requests to this resource: POST /v3/contactdb/recipients:

Limits length of the recipient array to 100,000 per request.
Limits value length for first_name and last_name reserved fields to 50 characters.
Limits custom field value length to 1,000 characters.

Updates to the Segment resources

Create a segment

Updates the capabilities of this resource: POST /v3/contactdb/segments.

Adds a limit of 200 segments.
Denies updates of a new segment until five minutes after creation or last update.

Added Export resources

This covers a new collection that offers functionality present in the New Marketing Campaigns API.

Export contacts

Adds a new resource: POST /v3/contactdb/exports

This works like the Export Contacts resource with one difference. The lists.ID and segments.ID properties return integers, not strings.

Get export status

Adds a new resource: GET /v3/contactdb/exports/{export_id}.

This works like the Export Contacts Status resource with one difference. The lists.ID and segments.ID properties return integers, not strings.

Get all existing exports

Adds a new resource: GET /v3/contactdb/exports.

This resource works like the Get All Existing Exports resource with one difference. The lists.ID and segments.ID properties return integers, not strings.