# SendGrid

Send email through SendGrid, with attachments and dynamic templates, and manage Marketing Campaigns contacts and lists.

## Connect SendGrid

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `sendgrid` and choose **SendGrid**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **API key · Required**: The key SendGrid shows once when you create it (SG.…).
- **Region · Optional**: Leave empty for the global API. Type eu for an EU regional subuser (api.eu.sendgrid.com).

Paste a SendGrid API key (Settings › API Keys › Create API Key). Full Access works for everything; a Restricted key needs Mail Send for sending, Marketing for contacts and lists, and Template Engine for templates.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in SendGrid

Add a **SendGrid** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Mail](https://docs.gorunner.io/apps/sendgrid#fields-f-mail): Send
- [Contact](https://docs.gorunner.io/apps/sendgrid#fields-f-contact): Create or Update · Get · Get Many · Delete
- [List](https://docs.gorunner.io/apps/sendgrid#fields-f-list): Create · Get · Get Many · Update · Remove Contacts · Delete
- [Template](https://docs.gorunner.io/apps/sendgrid#fields-f-template): Get · Get Many

To start a workflow from SendGrid, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from SendGrid can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When SendGrid says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, SendGrid is `pieceId: "sendgrid"` with `actionId: "sendgrid"`, set by `resource` and an `operation_…` field, such as `operation_contact`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### SendGrid › Mail

### Send

- **From Email · Required**: A sender address verified in SendGrid (Settings › Sender Authentication).
- **From Name · Optional**: The sender's name.
- **To · Required**: Recipient addresses, separated by commas. Everyone listed sees the others.
- **CC · Optional**: Addresses to copy, separated by commas.
- **BCC · Optional**: Addresses to copy unseen, separated by commas.
- **Reply To · Optional**: Where replies go.
- **Use a Dynamic Template · Optional**: Send a dynamic template (d-…) filled with Template Data instead of writing the content here. Off by default.
- **Template · Required**: The dynamic template. Shows when **Use a Dynamic Template** is on.
- **Template Data · Optional**: The values the template's {{handlebars}} read, such as {"first_name": "Sam", "order": {"id": 42}}. Shows when **Use a Dynamic Template** is on.
- **Subject · Optional**: The subject line. With a dynamic template, the template's own subject is used when this is empty.
- **Content Type · Optional**: Plain text, or HTML. Options: Plain text, HTML. Default: Plain text. Shows when **Use a Dynamic Template** is off.
- **Message · Required**: The email's body. Shows when **Use a Dynamic Template** is off.
- **Attachments · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). SendGrid takes at most 30 MB per message, attachments included.
- **Categories · Optional**: Up to 10 categories for SendGrid's statistics, separated by commas.
- **Send At · Optional**: Schedule the email (ISO 8601 time, at most 72 hours ahead). Empty sends now.
- **IP Pool · Optional**: The IP pool to send from (dedicated IPs only).
- **Headers · Optional**: Extra email headers, such as {"X-Order-Id": "42"}.
- **Sandbox Mode · Optional**: Have SendGrid check the request without sending anything. Off by default.

### SendGrid › Contact

### Create or Update

- **Email · Required**: The contact's email address (how SendGrid tells contacts apart).
- **First Name · Optional**
- **Last Name · Optional**
- **Add to List · Optional**: A list to add the contact to. Empty adds it to All Contacts only.
- **Address · Optional**
- **Address Line 2 · Optional**
- **City · Optional**
- **State or Region · Optional**
- **Postal Code · Optional**
- **Country · Optional**
- **Other Emails · Optional**: Up to 5 more addresses of the same person, separated by commas.
- **Custom Fields · Optional**: Values of custom fields by their id (Marketing › Custom Fields), such as {"e1_T": "Gold"}. The fields must exist already.

### Get

- **By · Required**: Find the contact by its id or its email address. Options: ID, Email. Default: ID.
- **Contact ID · Required**: The contact's id. Shows when **By** is **ID**.
- **Email · Required**: The contact's email address. Shows when **By** is **Email**.

### Get Many

- **Query · Optional**: A SendGrid SGQL condition, such as email LIKE 'sam%' AND CONTAINS(list_ids, '\<list id>'). Empty lists the most recent contacts.
- **Limit · Optional**: How many contacts to return (1–50; SendGrid returns at most the first 50 matches). Default: 50.

### Delete

- **Delete All Contacts · Optional**: Delete every contact of the account. Cannot be undone. Off by default.
- **Contact IDs · Required**: The contacts to delete, separated by commas. Shows when **Delete All Contacts** is off.

### SendGrid › List

### Create

- **Name · Required**: The list's name.

### Get

- **List · Required**: The list.
- **Include Sample Contacts · Optional**: Return up to 50 of the list's most recent contacts with it. Off by default.

### Get Many

- **Return All · Optional**: Read every list, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many lists to return (1–5000). Default: 50. Shows when **Return All** is off.

### Update

- **List · Required**: The list.
- **Name · Required**: The list's name.

### Remove Contacts

- **List · Required**: The list.
- **Contact IDs · Required**: The contacts to take off the list, separated by commas (they stay in All Contacts).

### Delete

- **List · Required**: The list.
- **Delete Its Contacts Too · Optional**: Also delete the list's contacts from the account. Off by default.

### SendGrid › Template

### Get

- **Template · Required**: The template.

### Get Many

- **Kind · Optional**: Dynamic templates (d-…), legacy ones, or both. Options: Dynamic, Legacy, Both. Default: Dynamic.
- **Return All · Optional**: Read every template, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many templates to return (1–5000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/sendgrid