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


Requirements and Limitations

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

Obtain the Sendgrid API Key

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

Your application, mail client, or website can all use API (Application Programming Interface) keys to authenticate access to SendGrid services. We suggest that you use API keys for connecting to all of SendGrid’s services. They are the preferred alternative to using a username and password because an API key can be revoked at any time without having to change your username and password. 

Sendgrid API keys include the following:

Within Sendgrid:

  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

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

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.

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


    database: sendgrid_db

  td>: marketing_test_mail.sql
  database: ${td.database}
  result_connection: meg_sendgrid_auth
  	type: sendgrid
	action: send_mail
    from_name: lee 
  	personalized_template: |
          "personalizations": [{
                                 "to": [{
                                          "email": "__email__"
                                 "subject": "Subject in personalization __email__",
                                 "substitutions": {
                                   "--name--": "substitution value"
  	content: |
	    {"content": [
                "type": "text/plain",
                "value": "Hello --name--"
    batch_size: 1000 	
    unsubscribe_group_id: null
    attachment: null 
    mail_settings: null 
    tracking_settings: null  

#for send_test_marketing_mail
    type: sendgrid
    action: send_test_marketing_mail
    from_name: lee
    receiver_column_name: email
    template_id_send_testing: d-d86cc2d8bxx4400e903adf052e53d55a
    unsubscribe_url: null
    suppression_group_id: null