Skip to main content
SendGrid logo

SendGrid

Overview​

SendGrid is a powerful email communication platform that empowers businesses to send engaging and personalized emails at scale. Integrate SendGrid with Superblocks to elevate your email marketing and communication capabilities. Effortlessly send personalized emails, automate email campaigns, and analyze email performance to optimize your outreach.

Setting up SendGrid​

Create an access token

To get started you'll need a SendGrid API key. To create an API key:

  1. Log in to SendGrid
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Select Full Access, Restricted Access, or Billing Access
  5. Click Create & View
  6. Copy the API key to configure your integration's connection

Learn more about SendGrid API Authentication.

Add integration

Once you have an access token, you're ready to set up your Superblocks integration.

  1. In the web app, navigate to the Integrations page
  2. Click on the SendGrid tile
  3. Name the integration
  4. Paste your credentials into the relevant fields
  5. Optionally, add more configurations to set credentials for different environments
  6. Click Create
success

SendGrid connected Now you can use SendGrid in any Application, Workflow, or Scheduled Job.

Use SendGrid in APIs​

Once your SendGrid integration is created, you can start creating steps in Application backend APIs, Workflows, and Scheduled Jobs to call SendGrid API actions. SendGrid actions are REST requests. To learn more about REST requests in Superblocks, see the Building REST requests guide.

Supported actions​

Send mail

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 contacts

**This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. This list will then be sorted by email address. The full contact count is also returned. Please note that pagination of the contacts has been deprecated. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Add or update a contact

**This endpoint allows the [upsert](https://en.wiktionary.org/wiki/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.

Delete contacts

**This endpoint can be used to delete one or more contacts**. The query parameter `ids` must set to a comma-separated list of contact IDs for bulk contact deletion. The query parameter `delete_all_contacts` must be set to `"true"` to delete **all** contacts. You must set either `ids` or `delete_all_contacts`. Deletion jobs are processed asynchronously. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Get total contact count

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

Get a contact by ID

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

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.

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

Import contacts

**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](https://en.wikipedia.org/wiki/Gzip). 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.

Import contacts status

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

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.

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 all lists

**This endpoint returns an array of all of your contact lists.**

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

Get list's contact count

**This endpoint returns the number of contacts on a specific list.**

Get a list by ID

**This endpoint returns data about a specific list.** Setting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address. The full contact count is also returned.

Update list

**This endpoint updates the name of a list.**

Delete a list

**This endpoint allows you to deletes a specific list.** Optionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts.

Remove contacts from a list

**This endpoint allows you to remove contacts from a given list.** The contacts will not be deleted. Only their list membership will be changed.

Get all automation stats

**This endpoint allows you to retrieve stats for all your Automations.** By default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Get automation stats by ID

**This endpoint allows you to retrieve stats for a single Automation using its ID.** Multiple Automation IDs can be retrieved using the "Get All Automation Stats" endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation specified. You may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.

Get automation click tracking stats by ID

**This endpoint lets you retrieve click-tracking stats for a single Automation**. The stats returned list the URLs embedded in your Automation and the number of clicks each one received. Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. You can retrieve a specific page of responses with the `page_token` query string parameter.

Export automation stats

**This endpoint allows you to export Automation stats as CSV data**. You can specify one Automation or many: include as many Automation IDs as you need, separating them with commas, as the value of the `ids` query string paramter. The data is returned as plain text response but in CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a `.csv` file.

Filter all messages

Filter all messages to search your Email Activity. All queries must be [URL encoded](https://meyerweb.com/eric/tools/dencoder/), and use the following format: `query={query_type}="{query_content}"` Once URL encoded, the previous query will look like this: `query=type%3D%22query_content%22` For example, to filter by a specific email, use the following query: `query=to_email%3D%22example%40example.com%22` Visit our [Query Reference section](https://docs.sendgrid.com/for-developers/sending-email/getting-started-email-activity-api#query-reference) to see a full list of basic query types and examples.

Filter messages by ID

Get all of the details about the specified message.

Request a CSV

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.

Download a CSV

**This endpoint will return a presigned URL that can be used to download the CSV that was requested from the "Request a CSV" endpoint.**

Retrieve global email statistics

**This endpoint allows you to retrieve all of your global email statistics between a given date range.** Parent accounts can see either aggregated stats for the parent account or aggregated stats for a subuser specified in the `on-behalf-of` header. Subuser accounts will see only their own stats.

Retrieve email statistics by country and state/province.

**This endpoint allows you to retrieve your email statistics segmented by country and state/province.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).

Retrieve email statistics by device type.

**This endpoint allows you to retrieve your email statistics segmented by the device type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. ## Available Device Types | **Device** | **Description** | **Example** | |---|---|---| | Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. | | Webmail | A web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. | | Phone | A smart phone. | iPhone, Android, Blackberry, etc. | Tablet | A tablet computer. | iPad, android based tablet, etc. | | Other | An unrecognized device. | Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve email statistics by client type.

**This endpoint allows you to retrieve your email statistics segmented by client type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).

Retrieve stats by a specific client type.

**This endpoint allows you to retrieve your email statistics segmented by a specific client type.** **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. ## Available Client Types - phone - tablet - webmail - desktop Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).
and 17 more

Generic HTTP Request​

Every SaaS integration in Superblocks comes with a built in Generic HTTP Request Action. This is a powerful action you can use to call SendGrid API endpoints not in the Superblocks supported actions.

To use this action simply add the method, path, required query parameters, and body for the desired endpoint.

info

Learn more about REST requests in Superblocks in our Building REST requests guide.

Generic HTTP Requests use the authentication set up and base URL you've configured for your integration, making it an easy for your team to extend Superblocks Integrations to meet their needs.