Email Activity (beta)

Search for suppressions within a group **This endpoint allows you to search a suppression group for multiple suppressions.** When given a list of email addresses and a group ID, this endpoint will only return the email addresses that have been unsubscribed from the given group.

Add recipient addresses to the global suppression group. **This endpoint allows you to add one or more email addresses to the global suppressions group.**

Create a Campaign **This endpoint allows you to create a campaign.** In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.

Schedule a Campaign **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.

Send a Campaign **This endpoint allows you to immediately send an existing campaign.** Normally a POST request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.

Send a Test Campaign **This endpoint allows you to send a test campaign.** To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]

Create a Custom Field **This endpoint allows you to create a custom field.** **You can create up to 120 custom fields.**

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

Add Multiple Recipients to a List **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.

Add a Single Recipient to a List **This endpoint allows you to add a single recipient to a list.**

Add recipients **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.

Search recipients 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".

Create a Segment **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](https://en.wikipedia.org/wiki/ISO_8601) 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".

Add IPs **This endpoint is for adding a(n) IP Address(es) to your account.**

Create an IP pool **This endpoint allows you to create an IP pool.** Before you can create an IP pool, you need to activate the IP in your SendGrid account: 1. Log into your SendGrid account. 1. Navigate to **Settings** and then select **IP Addresses**. 1. Find the IP address you want to activate and then click **Edit**. 1. Check **Allow my account to send mail using this IP address**. 1. Click **Save**.

Add an IP address to a pool **This endpoint allows you to add an IP address to an IP pool.** You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. Before you can add an IP to a pool, you need to activate it in your SendGrid account: 1. Log into your SendGrid account. 1. Navigate to **Settings** and then select **IP Addresses**. 1. Find the IP address you want to activate and then click **Edit**. 1. Check **Allow my account to send mail using this IP address**. 1. Click **Save**. You can retrieve all of your available IP addresses from the "Retrieve all IP addresses" endpoint.

Start warming up an IP address **This endpoint allows you to put an IP address into warmup mode.**

Create a batch ID **This endpoint allows you to generate a new batch ID.** Once a `batch_id` is created, you can associate it with a scheduled send using the `/mail/send` endpoint. Passing the `batch_id` as a field in the `/mail/send` request body will assign the ID to the send you are creating. Once an ID is associated with a scheduled send, the send can be accessed and its send status can be modified using the `batch_id`.

v3 Mail Send The Mail Send endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). ## Helper Libraries Twilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages: * [C#](https://github.com/sendgrid/sendgrid-csharp) * [Go](https://github.com/sendgrid/sendgrid-go) * [Java](https://github.com/sendgrid/sendgrid-java) * [Node JS](https://github.com/sendgrid/sendgrid-nodejs) * [PHP](https://github.com/sendgrid/sendgrid-php) * [Python](https://github.com/sendgrid/sendgrid-python) * [Ruby](https://github.com/sendgrid/sendgrid-ruby) ## Dynamic Transactional Templates and Handlebars In order to send a dynamic template, specify the template ID with the `template_id` parameter. To specify handlebar substitutions, define your substitutions in the request JSON with this syntax: ``` "dynamic_template_data": {       "guest": "Jane Doe",       "partysize": "4",       "english": true,       "date": "April 1st, 2021"     } ``` For more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages. * [How to send an email with Dynamic Transactional Templates ](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/) * [Using Handlebars](https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/) ## Mail Body Compression Mail body compression is available to some high volume accounts. Talk to your CSM if you are interested in this functionality. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb). To use mail body compression: 1. Add a `Content-Encoding` header, with a value of `gzip`. a. `Content-Encoding: gzip` 2. Send the gzip as a data-binary. a. `--data-binary '@data.json.gz' ` ## Multiple Reply-To Emails Using `reply_to_list` allows senders to include more than one recipient email address to receive reply and/or bounce messages from the recipient of the email. ### Usage Considerations * `reply_to` is mutually exclusive with `reply_to_list`. If both are used, then the API call will be rejected. * The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter. * Each email address in the `reply_to_list` should be unique. * There is a limit of 1000 `reply_to_list` emails per mail/send request. * In SMTP calls, we will omit any invalid emails. ### Possible 400 Error Messages * `reply_to` is mutually exclusive with `reply_to_list`. * The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter. * Each email address in the `reply_to_list` should be unique. * There is a limit of X `reply_to` emails per mail/send request. * The `reply_to_list` email does not contain a valid address. * The `reply_to_list` email exceeds the maximum total length of X characters. * The `reply_to_list` email parameter is required.

Get Batched Contacts by IDs **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.

Get Contacts by Emails **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)](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) 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.

Create Segment **This endpoint allows you to create a segment.**

Bulk Delete Segments This endpoint allows you to delete segments in bulk. If the segments are used by automations or the segments do not exist in the database, the segment IDs that could not be deleted along with automation IDs that are associated to those segments will be returned.

Create a Sender Identity **This endpoint allows you to create a new sender identity.** *You may create up to 100 unique sender identities.* Sender identities are required to be verified before use. If your domain has been authenticated, a new sender identity will auto verify on creation. Otherwise an email will be sent to the `from.email`.

Create Single Send **This endpoint allows you to create a new Single Send.** Please note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object.

Duplicate Single Send **This endpoint allows you to duplicate an existing Single Send using its Single Send ID.** Duplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint. If you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text “Copy of ” prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including “Copy of ”, will be trimmed if the name exceeds this limit.

Get Single Sends Search **This endpoint allows you to search for Single Sends based on specified criteria.** You can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields. For example, if you want to search for all Single Sends that are "drafts" or "scheduled" and also associated with the category "shoes," your request body may look like the example below. ```javascript { "status": [ "draft", "scheduled" ], "categories": [ "shoes" ], } ```

Send a Test Marketing Email **This endpoint allows you to send a test marketing email to a list of email addresses**. Before sending a marketing message, you can test it using this endpoint. You may specify up to **10 contacts** in the `emails` request body field. You must also specify a `template_id` and include either a `from_address` or `sender_id`. You can manage your templates with the [Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates) or the [Transactional Templates API](https://sendgrid.api-docs.io/v3.0/transactional-templates). > Please note that this endpoint works with Dynamic Transactional Templates only. Legacy Transactional Templates will not be delivered. For more information about managing Dynamic Transactional Templates, see [How to Send Email with Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). You can also test your Single Sends in the [Twilio SendGrid Marketing Campaigns UI](https://mc.sendgrid.com/single-sends).

Export Contacts **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.

Search Contacts **Use this endpoint to locate contacts**. The request body's `query` field accepts valid [SGQL](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) 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.

Create Custom Field Definition **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.**

Create List **This endpoint creates a new contacts list.** Once you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list. A link to the newly created object is in `_metadata`.

Create Segment **The Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this [form]({https://docs.google.com/forms/d/e/1FAIpQLSd5zwC9dRk8lAp1oTWjdGc-aSY69flW_7wnutvKBhpUluSnfQ/viewform)** Segment `name` has to be unique. A user can not create a new segment with an existing segment name.

Create a Sender Identity **This endpoint allows you to create a new sender identity.** You may create up to 100 unique sender identities.

Create an SSO Certificate **This endpoint allows you to create an SSO certificate.**

Create an SSO Integration **This endpoint allows you to create an SSO integration.**

Create SSO Teammate **This endpoint allows you to create an SSO Teammate.** The email provided for this user will also function as the Teammate’s username.

Create Subuser **This endpoint allows you to create a new subuser.**

Create monitor settings

Create a transactional template. **This endpoint allows you to create a transactional template.**

Duplicate a transactional template. **This endpoint allows you to duplicate a transactional template.**

Create a new transactional template version. **This endpoint allows you to create a new version of a template.**

Activate a transactional template version. **This endpoint allows you to activate a version of one of your templates.**

Cancel or pause a scheduled send **This endpoint allows you to cancel or pause a scheduled send associated with a `batch_id`.** Passing this endpoint a `batch_id` and status will cancel or pause the scheduled send. Once a scheduled send is set to `pause` or `cancel` you must use the "Update a scheduled send" endpoint to change its status or the "Delete a cancellation or pause from a scheduled send" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a `400` level status code. If the maximum number of cancellations/pauses are added to a send, a `400` level status code will be returned.

Test Event Notification Settings **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. >**Tip**: Retry logic for this endpoint differs from other endpoints, which use a rolling 24-hour retry. If your web server does not return a 2xx response type, we will retry a POST request until we receive a 2xx response or the maximum time of 10 minutes has expired.

Create a parse setting **This endpoint allows you to create a new inbound parse setting.** Creating an Inbound Parse setting requires two pieces of information: a `url` and a `hostname`. The `hostname` must correspond to a domain authenticated by Twilio SendGrid on your account. If you need to complete domain authentication, you can use the [Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth) or the "Authenticate a domain" endpoint. See "[How to Set Up Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/)" for instructions. Any email received by the `hostname` will be parsed when you complete this setup. You must also add a Twilio SendGrid MX record to this domain's DNS records. See "[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)" for full instructions. The `url` represents a location where the parsed message data will be delivered. Twilio SendGrid will make an HTTP POST request to this `url` with the message data. The `url` must be publicly reachable, and your application must return a `200` status code to signal that the message data has been received.

Request CSV This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice. This request will kick off a backend process to generate a CSV file. Once generated, the worker will then send an email for the user download the file. The link will expire in 3 days. The CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours (rate limit may change). This endpoint is similar to the GET Single Message endpoint - the only difference is that /download is added to indicate that this is a CSV download requests but the same query is used to determine what the CSV should contain.

Resend Sender Identity Verification **This enpdoint allows you to resend a sender identity verification email.**

Invite teammate **This endpoint allows you to invite a Teammate to your account via email.** You can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function. **Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date.

Resend teammate invite **This endpoint allows you to resend a Teammate invitation.** Teammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.