Email Activity (beta)

This endpoint allows you to create a new API Key for the user.

To create your initial SendGrid API Key, you should use the SendGrid App. Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.

There is a limit of 100 API Keys on your account.

A JSON request body containing a name property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a 403 status will be returned.

Though the name field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body.

It is not necessary to pass a scopes field to the API when creating a key, but you should be aware that omitting the scopes field from your request will create a key with “Full Access” permissions by default.

See the API Key Permissions List for all available scopes. An API key’s scopes can be updated after creation using the “Update API keys” endpoint.

This endpoint allows you to create a new alert.

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:

• usage_limit allows you to set the threshold at which an alert will be sent.
• stats_notification allows you to set how frequently you would like to receive email statistics reports. For example, “daily”, “weekly”, or “monthly”.

For more information about alerts, please see our Alerts documentation.

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.

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.

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.

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.

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”]

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.

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.

This endpoint allows you to create an SSO certificate.

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.

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.

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 allows you to create a custom field.

You can create up to 120 custom fields.

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

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 add a single recipient to a list.

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 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 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 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 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.

This endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs.

Like duplicating one of your existing designs, you are not required to pass any data in the body of a request to this endpoint. If you choose to leave the name field blank, your duplicate will be assigned the name of the design it was copied from with the text “Duplicate: “ prepended to it. This name change is only a convenience, as the duplicate design will be assigned a unique ID that differentiates it from your other designs. You can retrieve the IDs for Twilio SendGrid pre-built designs using the “List SendGrid Pre-built Designs” endpoint.

You can modify your duplicate’s name at the time of creation by passing an updated value to the name field when making the initial request.
More on retrieving design IDs can be found above.

This endpoint allows you to duplicate one of your existing designs.

Modifying an existing design is often the easiest way to create something new.

You are not required to pass any data in the body of a request to this endpoint. If you choose to leave the name field blank, your duplicate will be assigned the name of the design it was copied from with the text “Duplicate: “ prepended to it. This name change is only a convenience, as the duplicate will be assigned a unique ID that differentiates it from your other designs.

You can modify your duplicate’s name at the time of creation by passing an updated value to the name field when making the initial request.
More on retrieving design IDs can be found below.

This endpoint allows you to authenticate a domain.

If you are authenticating a domain for a subuser, you have two options:

1. Use the “username” parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain.
2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.

This endpoint allows you to associate a specific authenticated domain with a subuser.

Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent’s domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.

This endpoint allows you to add an IP address to an authenticated domain.

This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.

This endpoint allows you to validate an email address.

This endpoint is used to share DNS records with a colleagues

Use this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding.

What type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records.

If you pass a link_id to this endpoint, the generated email will supply the DNS records necessary to complete Link Branding setup. If you pass a domain_id to this endpoint, the generated email will supply the DNS records needed to complete Domain Authentication. Passing both IDs will generate an email with the records needed to complete both setup steps.

You can retrieve all your domain IDs from the returned id fields for each domain using the “List all authenticated domains” endpoint. You can retrieve all of your link IDs using the “Retrieve all branded links” endpoint.

This endpoint allows you to add one or more allowed IP addresses.

To allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an id that can be used to remove the address. You can retrieve the ID associated with an IP using the “Retrieve a list of currently allowed IPs” endpoint.

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

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.
2. Navigate to Settings and then select IP Addresses.
3. Find the IP address you want to activate and then click Edit.
4. Check Allow my account to send mail using this IP address.
5. Click Save.

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.
2. Navigate to Settings and then select IP Addresses.
3. Find the IP address you want to activate and then click Edit.
4. Check Allow my account to send mail using this IP address.
5. Click Save.

You can retrieve all of your available IP addresses from the “Retrieve all IP addresses” endpoint.

This endpoint allows you to put an IP address into warmup mode.

This endpoint allows you to create a new branded link.

To create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain.

You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request.

This endpoint allows you to validate a branded link.

You can submit this request as one of your subusers if you include their ID in the on-behalf-of header in the request.

This endpoint allows you to associate a branded link with a subuser account.

Link branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent’s link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the Subuser Management page of the Twilio SendGrid App.

This endpoint creates a new contacts list.

Once you create a list, you can use the UI to trigger an automation every time you add a new contact to the list.

A link to the newly created object is in _metadata.

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.

Helper Libraries

Twilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:

• C#
• Go
• Java
• Node JS
• PHP
• Python
• 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
• 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.

This endpoint allows you to set up reverse DNS.

This endpoint allows you to validate a reverse DNS record.

Always check the valid property of the response’s validation_results.a_record object. This field will indicate whether it was possible to validate the reverse DNS record. If the validation_results.a_record.valid is false, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid.

If validity couldn’t be determined, you can check the value of validation_results.a_record.reason to find out why.

You can retrieve the IDs associated with all your reverse DNS records using the “Retrieve all reverse DNS records” endpoint.

This endpoint allows you to create a segment.

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.

The Segmentation V2 API is currently in private beta. If you’d like to be added to the beta, please fill out this form

Segment name has to be unique. A user can not create a new segment with an existing segment name.

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 or the Transactional Templates API.

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.

You can also test your Single Sends in the Twilio SendGrid Marketing Campaigns UI.

This endpoint allows you to create a new sender identity.

You may create up to 100 unique sender identities.

This enpdoint allows you to resend a sender identity verification email.

This endpoint allows you to create a new Sender Identify.

Upon successful submission of a POST request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the from_email field. You must complete the verification process using the sent email to fully verify the sender.

If you need to resend the verification email, you can do so with the Resend Verified Sender Request, /resend/{id}, endpoint.

If you need to authenticate a domain rather than a Single Sender, see the Domain Authentication API.

This endpoint allows you to resend a verification email to a specified Sender Identity.

Passing the id assigned to a Sender Identity to this endpoint will resend a verification email to the from_address associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason.

You can retrieve the IDs associated with Sender Identities by passing a “Get All Verified Senders” endpoint.

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.

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 or the “Authenticate a domain” endpoint. See “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” 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.

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.

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.

{
  "status": [
    "draft",
    "scheduled"
  ],
  "categories": [
    "shoes"
  ],
}

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.

This endpoint allows you to create an SSO integration.

This endpoint allows you to create an SSO Teammate.

The email provided for this user will also function as the Teammate’s username.

This endpoint allows you to create a new subuser.

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

This endpoint allows you to add email addresses to an unsubscribe group.

If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.

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.

This endpoint allows you to create a new suppression group.

To add an email address to the suppression group, create a Suppression.

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.

This endpoint allows you to resend a Teammate invitation.

Teammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.

This endpoint allows you to create a transactional template.

This endpoint allows you to duplicate a transactional template.

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

This endpoint allows you to activate a version of one of your templates.

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.