> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.sendgrid.com/api-reference/contacts/add-or-update-a-contact) |
| **Mail** | Trigger one-to-one transactional emails for each record in your data model | Triggered Sends (one row = one email) | [Mail Send API](https://docs.sendgrid.com/api-reference/mail-send/mail-send) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to SendGrid

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) 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](https://docs.sendgrid.com/ui/account-and-settings/api-keys#creating-an-api-key).

#### 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) |

## Sync configuration

Once you've set up your SendGrid destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) 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**.

> [!NOTE]
>
> 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](https://docs.sendgrid.com/api-reference/mail-send/mail-send). 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`. |

> [!NOTE]
>
> 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

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

## Common errors

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