This endpoint allows the upsert (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower.

Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact’s ID or confirm your contacts have been updated or added, you can use the “Get Contacts by Emails” endpoint.

Please note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the “Create Custom Field Definition” endpoint.

You will see a job_id in the response to your request. This can be used to check the status of your upsert job. To do so, please use the “Import Contacts Status” endpoint.

If the contact already exists in the system, any entries submitted via this endpoint will update the existing contact. The contact to update will be determined only by the email field and any fields omitted from the request will remain as they were. A contact’s ID cannot be used to update the contact.

The email field will be changed to all lower-case. If a contact is added with an email that exists but contains capital letters, the existing contact with the all lower-case email will be updated.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint is used to retrieve a set of contacts identified by their IDs.

This can be more efficient endpoint to get contacts than making a series of individual GET requests to the “Get a Contact by ID” endpoint.

You can supply up to 100 IDs. Pass them into the ids field in your request body as an array or one or more strings.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint returns the total number of contacts you have stored.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Use this endpoint to retrieve details of all current exported jobs.

It will return an array of objects, each of which records an export job in flight or recently completed.

Each object’s export_type field will tell you which kind of export it is and its status field will indicate what stage of processing it has reached. Exports which are ready will be accompanied by a urls field which lists the URLs of the export’s downloadable files — there will be more than one if you specified a maximum file size in your initial export request.

Use this endpoint if you have exports in flight but do not know their IDs, which are required for the “Export Contacts Status” endpoint.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Use this endpoint to export lists or segments of contacts.

If you would just like to have a link to the exported list sent to your email set the notifications.email option to true in the POST payload.

If you would like to download the list, take the id that is returned and use the “Export Contacts Status” endpoint to get the urls. Once you have the list of URLs, make a GET request to each URL provided to download your CSV file(s).

You specify the segements and or/contact lists you wish to export by providing the relevant IDs in, respectively, the segment_ids and list_ids fields in the request body.

The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body file_type field to json or csv.

You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint can be used to check the status of a contact export job.

To use this call, you will need the id from the “Export Contacts” call.

If you would like to download a list, take the id that is returned from the “Export Contacts” endpoint and make an API request here to get the urls. Once you have the list of URLs, make a GET request on each URL to download your CSV file(s).

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.

Imports take place asynchronously: the endpoint returns a URL (upload_uri) and HTTP headers (upload_headers) which can subsequently be used to PUT a file of contacts to be imported into our system.

Uploaded CSV files may also be gzip-compressed.

In either case, you must include the field file_type with the value csv in your request body.

The field_mappings paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (null) or remapped to the contact field.

For example, if field_mappings is set to [null, "w1", "_rf1"], this means skip column 0, map column 1 to the custom field with the ID w1, and map column 2 to the reserved field with the ID _rf1. See the “Get All Field Definitions” endpoint to fetch your custom and reserved field IDs to use with field_mappings.

Once you recieve the response body you can then initiate a second API call where you use the supplied URL and HTTP header to upload your file. For example:

curl --upload-file "file/path.csv" "URL_GIVEN" -H 'HEADER_GIVEN'

If you’d like to monitor the status of your import job, use the job_id and the “Import Contacts Status” endpoint.
Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint can be used to check the status of a contact import job.

Use the job_id from the “Import Contacts,” “Add or Update a Contact,” or “Delete Contacts” endpoints as the id in the path parameter.

If there is an error with your PUT request, download the errors_url file and open it to view more details.

The job status field indicates whether the job is pending, completed, errored, or failed.

Pending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finshed with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support.

The results object will have fields depending on the job type.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Use this endpoint to locate contacts.

The request body’s query field accepts valid SGQL for searching for a contact.

Because contact emails are stored in lower case, using SGQL to search by email address requires the provided email address to be in lower case. The SGQL lower() function can be used for this.

Only the first 50 contacts that meet the search criteria will be returned.

If the query takes longer than 20 seconds, a 408 Request Timeout status will be returned.

Formatting the created_at and updated_at values as Unix timestamps is deprecated. Instead they are returned as ISO format as string.
Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint allows you to retrieve up to 100 contacts matching the searched email address(es), including any alternate_emails.

Email addresses are unique to a contact, meaning this endpoint can treat an email address as a primary key to search by. The contact object associated with the address, whether it is their email or one of their alternate_emails will be returned if matched.

Email addresses in the search request do not need to match the case in which they’re stored, but the email addresses in the result will be all lower case. Empty strings are excluded from the search and will not be returned.

This endpoint should be used in place of the “Search Contacts” endpoint when you can provide exact email addresses and do not need to include other Segmentation Query Language (SGQL) filters when searching.

If you need to access a large percentage of your contacts, we recommend exporting your contacts with the “Export Contacts” endpoint and filtering the results client side.

This endpoint returns a 200 status code when any contacts match the address(es) you supplied. When searching multiple addresses in a single request, it is possible that some addresses will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the email address(es) that are not found.

This endpoint returns a 404 status code when no contacts are found for the provided email address(es).

A 400 status code is returned if any searched addresses are invalid.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint returns the full details and all fields for the specified contact.

The “Get Contacts by Emails” endpoint can be used to get the ID of a contact.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

This endpoint allows you to retrieve all custom fields.

This endpoint allows you to create a custom field.

You can create up to 120 custom fields.

This endpoint allows you to delete a custom field by ID.

This endpoint allows you to retrieve a custom field by ID.

This endpoint allows you to list all fields that are reserved and can’t be used for custom field names.

This endpoint allows you to delete multiple recipient lists.

This endpoint allows you to retrieve all of your recipient lists. If you don’t have any lists, an empty array will be returned.

This endpoint allows you to create a list for your recipients.

This endpoint allows you to delete a specific recipient list with the given ID.

This endpoint allows you to retrieve a single recipient list.

This endpoint allows you to update the name of one of your recipient lists.

This endpoint allows you to retrieve all recipients on the list with the given ID.

This endpoint allows you to add multiple recipients to a list.

Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints.

This endpoint allows you to delete a single recipient from a list.

This endpoint allows you to add a single recipient to a list.

This endpoint allows you to deletes one or more recipients.

The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.

This endpoint allows you to retrieve all of your Marketing Campaigns recipients.

Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of
the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.

This endpoint allows you to update one or more recipients.

The body of an API call to this endpoint must include an array of one or more recipient objects.

It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.

This endpoint allows you to add a Marketing Campaigns recipient.

You can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides.

The rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second.

This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.

You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.

This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.

This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.

field_name:

• is a variable that is substituted for your actual custom field name from your recipient.
• Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)
• If field_name is a ‘reserved’ date field, such as created_at or updated_at, the system will internally convert
  your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to
  Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through
  Mon, 02 Feb 2015 23:59:59 GMT.

Search using segment conditions without actually creating a segment. Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.

Valid operators for create and update depend on the type of the field for which you are searching.

• Dates:
  • "eq", "ne", "lt" (before), "gt" (after)
    • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
  • "empty", "not_empty"
  • "is within"
    • You may use an ISO 8601 date format or the # of days.
• Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value), "empty", "not_empty"
• Numbers: "eq", "lt", "gt", "empty", "not_empty"
• Email Clicks and Opens: "eq" (opened), "ne" (not opened)

Field values must all be a string.

Search conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier. The condition value should be a string containing the id of a completed campaign.

Search conditions list may contain multiple conditions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".

This endpoint allows you to delete a single recipient with the given ID from your contact database.

Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.

This endpoint allows you to retrieve a single recipient by ID from your contact database.

This endpoint allows you to retrieve the lists that a given recipient belongs to.

Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.

This endpoint allows you to check the upload status of a Marketing Campaigns recipient.

This endpoint allows you to retrieve all of your segments.

This endpoint allows you to create a new segment.

Valid operators for create and update depend on the type of the field for which you are searching.

Dates

• “eq”, “ne”, “lt” (before), “gt” (after)
  • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
• “empty”, “not_empty”
• “is within”
  • You may use an ISO 8601 date format or the # of days.

Text

• “contains”
• “eq” (is/equals - matches the full field)
• “ne” (is not/not equals - matches any field where the entire field is not the condition value)
• “empty”
• “not_empty”

Numbers

• “eq” (is/equals)
• “lt” (is less than)
• “gt” (is greater than)
• “empty”
• “not_empty”

Email Clicks and Opens

• “eq” (opened)
• “ne” (not opened)

All field values must be a string.

Conditions using “eq” or “ne” for email clicks and opens should provide a “field” of either clicks.campaign_identifier or opens.campaign_identifier.
The condition value should be a string containing the id of a completed campaign.

The conditions list may contain multiple conditions, joined by an “and” or “or” in the “and_or” field.

The first condition in the conditions list must have an empty “and_or”, and subsequent conditions must all specify an “and_or”.

This endpoint allows you to delete a segment from your recipients database.

You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.

This endpoint allows you to retrieve a single segment with the given ID.

This endpoint allows you to update a segment.

This endpoint allows you to retrieve all of the recipients in a segment with the given ID.

This endpoint retrieves all defined Custom Fields and Reserved Fields.

This endpoint creates a new custom field definition.

Custom field definitions are created with the given name and field_type. Although field names are stored in a case-sensitive manner, all field names must be case-insensitively unique. This means you may create a field named CamelCase or camelcase, but not both. Additionally, a Custom Field name cannot collide with any Reserved Field names. You should save the returned id value in order to update or delete the field at a later date. You can have up to 120 custom fields.

The custom field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (_). Custom fields can only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database.

Note: Creating a custom field that begins with a number will cause issues with sending in Marketing Campaigns.

This endpoint deletes a defined Custom Field.

You cand delete only Custom Fields; Reserved Fields cannot be deleted.

This endopoint allows you to update a defined Custom Field.

Only your Custom fields can be modified; Reserved Fields cannot be updated.

This endpoint allows you to retrieve a list of designs already stored in your Design Library.

A GET request to /designs will return a list of your existing designs. This endpoint will not return the pre-built Twilio SendGrid designs. Pre-built designs can be retrieved using the /designs/pre-builts endpoint, which is detailed below.

By default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the page_size query parameter.

This endpoint allows you to create a new design.

You can add a new design by passing data, including a string of HTML email content, to /designs. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to Cross-Platform Email Design.

The Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the Design and Code Editor documentation.

Because the /designs endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI.