Twilio SendGrid

Run better email campaigns on SendGrid with up-to-date customer data from your data warehouse

Supported syncing

Type	Description	Supported Sync Modes	API Reference
Contacts	Sync data from any source to Contacts in SendGrid	Upsert	Contacts docs
Mail	Trigger one-to-one transactional emails for each record in your data model	Triggered Sends (one row = one email)	Mail Send API

For more information about sync modes, refer to the sync modes docs.

Connect to SendGrid

Go to the Destinations overview page and click the Add destination button. Select SendGrid and click Continue. You can then authenticate Hightouch to SendGrid by entering a SendGrid API Key.

To create an API Key in SendGrid, follow the steps outlined in the SendGrid documentation.

Permissions

The permissions the API key needs depend on what you plan on syncing.

Sync Type	Required Permissions (Full Access)	Optional Permissions (Read Access)
Contacts	`Marketing`	-
Mail	`Mail Send`	`Template Engine` (for email template), `Suppressions` (for unsubscribe groups)

Once you've set up your SendGrid destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the SendGrid destination you want to sync to.

Syncing contacts

Upsert is the only available sync mode for the SendGrid destination. Use this sync mode to update existing contacts and insert new ones into SendGrid.

Record matching

To match rows from your model to contacts in SendGrid, you need to select the model column that contains your contacts' email.

SendGrid's email field is case-sensitive. Make sure the emails in your model follow a case convention, for example, all lowercase, to avoid duplicate contacts. For example, if your model has contact data for the email addresses john@example.com and John@example.com, this would create two separate contacts.

Field mapping

You can sync columns from your model to SendGrid default and custom fields.

Sending mail

Mail syncs send one transactional email per row in your model using SendGrid's Mail Send API. Enter the email address, and optionally the name, that emails should be sent from. Then choose whether to send with a SendGrid template or with content you provide in the sync. You can also select an unsubscribe group so recipients can opt out of similar emails.

Personalization fields

Map columns from your model, or static values, to the fields SendGrid uses to personalize each email.

Field	Description
To	The recipient's email address. Required.
CC and BCC	Additional recipients. Map a column that contains an array of email addresses, or a single email address from a string column or a static value.
Send At	When SendGrid should send the email. If you leave this unmapped, SendGrid sends the email immediately.
Custom Arguments	An object of key-value pairs SendGrid attaches to the email for tracking and analytics.
Headers	An object of custom email headers.
Substitutions	Template syncs only. Key-value pairs that fill the placeholders in your template.
Subject	Custom content syncs only. The subject line for the email.
Content	Custom content syncs only. The body of the email.
Content Type	Custom content syncs only. The MIME type of the body, for example `text/html`. Defaults to `text/plain`.

To copy the same address on every email, for example a shared team inbox, map BCC or CC to a static value containing that email address. You don't need an array column to send to a single recipient.

Mail and tracking settings

Under Advanced options, you can bypass SendGrid's list, spam, bounce, and unsubscribe management, add a custom footer, and enable sandbox mode. You can also turn on click, open, subscription, and Google Analytics tracking. These options map to the mail_settings and tracking_settings objects in the Mail Send API.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

Invalid list id

When you run a sync to SendGrid for the first time, Hightouch creates a new contact list. You can find this list on the Contact Lists page in your SendGrid workspace. If you delete this contact list, future sync runs will reject all rows with the invalid list id error.

To resolve this issue, create a new sync. This allows Hightouch to create a new contact list, which must exist for the sync to run successfully.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.