Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

SendGrid can send real-time notifications about events that happen on the SendGrid system to a URL. These events include clicks, opens, unsubscribe, bounces, and many others.These events include more data than what SendGrid records and allows you to customize your own reportingis a cloud-based SMTP provider that allows you to send email without having to maintain email servers.  With the Treasure Data integration, you can easily export profile segments to Sendgrid for all of your marketing email campaigns.

Table of Contents


  • Basic Knowledge of Treasure Data.

  • Knowledge of Sendgrid JSON email template.

Requirements and Limitations

There are several rate limitations and restrictions when using the Sendgrid connector features: Mail Send and Send Test Marketing Mail.

  • The total size of your email, including attachments, must be less than 30MB.

  • The total number of recipients must no more than 1000. This includes all recipients defined within the tocc, and bcc parameters, across each object that you include in the personalizations array.

  • The total length of custom arguments must be less than 10000 bytes.

  • Unicode encoding is not supported for the from field.

  • The, and personalizations cannot include either the ; or , characters.

  • For substitution, NULL values are truncated to ““ (empty string). If the substitution is for a numeric column, it is converted to a string.

  • Because the messages are sent in a batch, we will not revert the whole session. The error messages are logged to the console, but the job will continue.

  • You MUST HAVE strong knowledge of the Sendgrid JSON email template.

  • In Mail Send operation:
    • Template ID overrides the substitution defined in the Personalization Body. 
    • Skip invalid records only applied for invalid personalization body.
  • In Send Test Marketing Mail operation:
    • Should only input Unsubscribe URL orSuppression group ID.
    • Skip invalid records applied for invalid emails.

Obtain the Sendgrid API Key

To establish the connection to the Sendgrid application you must have an API key.


  1. Navigate to Settings on the left navigation bar.
  2. Select API Keys.
  3. Copy or write down the value of the API key that you need to use for the connection to Treasure Data.

Use the TD Console to Create Your Connection

Create a New Connection

In Treasure Data, you must create and configure the data connection before running your query. As part of the data connection, you provide authentication to access the integration.

  1. Open TD Console.

  2. Navigate to Integrations Hub Catalog.

  3. Search for and select Sendgrid.

  4. Type the credentials to authenticate.

  5. Type a name for your connection. 

  6. Select Done.

Define your Query

Excerpt Include
PD:Exporting Your Query Data to Your Destination
PD:Exporting Your Query Data to Your Destination

Integration Parameters for Sendgrid

ParameterReq. or OptionalDescription
  • Send Mail
  • Send Test Marketing Mail
From EmailRequired

Type an email value in the format:


From Nameoptional
Column Name to SendRequired

For Send Test Marketing Mail. 

Input the column name of the recipient from the exported query result
Personalized Email BodyRequired

Input configured email template. Use __column_name__ to mark a substitute column/alias. All Substitute columns/aliases must be in the exported data.

For example:

{"personalizations" : [{"to": [{"email": "__email__"}], "subject": "subject test __email__", "substitutions": {"--name--": "meg"}} ]}


For example:

{"content": [
                "type": "text/plain",
                "value": "content root --name--"

Number of Recipients per API CallRequired

For each request call to Sendgrid, the connector will build the personalizations body up to this number

Min: 1, Max: 1000, default: 1000

Example with Export SQL query return 50,000 records. And with default config 1000, the connector will send 50 requests to Sendgrid, with 1000 personalizations per request

AttachmentsoptionalJSON String
Template ID


Optional for Send Mail.
If specified, this template ID will override the Substitutions in the Personalized email body.

RequiredRequired for Send Test Marketing Mail.
Unsubscribe Group ID

You can give your recipients more control over the types of emails they want to receive by letting them opt out of messages from a certain group. 

Unsubscribe Urloptional
Suppression Group IDoptionalThe method used to specify an unsubscribe group.
Mail SettingsoptionalJSON string
Tracking SettingsoptionalJSON string

Example Query

Code Block
select to_email as email from email_2_records

Optionally Schedule the Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.


Excerpt Include
PD:Scheduling Jobs Using TD Console
PD:Scheduling Jobs Using TD Console

Optionally Configure Export Results in Workflow

Within Treasure Workflow, you can specify the use of this data connector to export data.

Learn more at Using Workflows to Export Data with the TD Toolbelt.

Example Workflow for Sendgrid