# SendGrid (/integrations/sendgrid)





{/* MANUAL-CONTENT-START:intro */}

Use [SendGrid](https://sendgrid.com) in Sim to send transactional emails, work with dynamic templates and attachments, and manage marketing contacts and lists. The action reference also covers template and suppression-group operations.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

Send transactional emails with dynamic templates and attachments. Manage marketing contacts, lists, and email templates.

## Actions [#actions]

### SendGrid Send Mail [#sendgrid-send-mail]

Send an email using SendGrid API

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `from` | string | Yes | Sender email address (must be verified in SendGrid) |
  | `fromName` | string | No | Sender name |
  | `to` | string | Yes | Recipient email address |
  | `toName` | string | No | Recipient name |
  | `subject` | string | No | Email subject (required unless using a template with pre-defined subject) |
  | `content` | string | No | Email body content (required unless using a template with pre-defined content) |
  | `contentType` | string | No | Content type (text/plain or text/html) |
  | `cc` | string | No | CC email address |
  | `bcc` | string | No | BCC email address |
  | `replyTo` | string | No | Reply-to email address |
  | `replyToName` | string | No | Reply-to name |
  | `attachments` | file\[] | No | Files to attach to the email (UserFile objects) |
  | `templateId` | string | No | SendGrid template ID to use |
  | `dynamicTemplateData` | json | No | JSON object of dynamic template data |

  #### Output [#output]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the email was sent successfully |
  | `messageId` | string | SendGrid message ID |
  | `to` | string | Recipient email address |
  | `subject` | string | Email subject |
</ReferenceDetails>

### SendGrid Add Contact [#sendgrid-add-contact]

Add a new contact to SendGrid

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `email` | string | Yes | Contact email address |
  | `firstName` | string | No | Contact first name |
  | `lastName` | string | No | Contact last name |
  | `customFields` | json | No | JSON object of custom field key-value pairs (use field IDs like e1\_T, e2\_N, e3\_D, not field names) |
  | `listIds` | string | No | Comma-separated list IDs to add the contact to |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `jobId` | string | Job ID for tracking the async contact creation |
  | `email` | string | Contact email address |
  | `firstName` | string | Contact first name |
  | `lastName` | string | Contact last name |
  | `message` | string | Status message |
</ReferenceDetails>

### SendGrid Get Contact [#sendgrid-get-contact]

Get a specific contact by ID from SendGrid

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `contactId` | string | Yes | Contact ID |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Contact ID |
  | `email` | string | Contact email address |
  | `firstName` | string | Contact first name |
  | `lastName` | string | Contact last name |
  | `createdAt` | string | Creation timestamp |
  | `updatedAt` | string | Last update timestamp |
  | `listIds` | json | Array of list IDs the contact belongs to |
  | `customFields` | json | Custom field values |
</ReferenceDetails>

### SendGrid Search Contacts [#sendgrid-search-contacts]

Search for contacts in SendGrid using a query

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `query` | string | Yes | Search query (e.g., "email LIKE '%example.com%' AND CONTAINS(list\_ids, 'list-id')") |

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `contacts` | json | Array of matching contacts |
  | `contactCount` | number | Total number of contacts found |
</ReferenceDetails>

### SendGrid Delete Contacts [#sendgrid-delete-contacts]

Delete one or more contacts from SendGrid

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `contactIds` | string | Yes | Comma-separated contact IDs to delete |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `jobId` | string | Job ID for the deletion request |
</ReferenceDetails>

### SendGrid Create List [#sendgrid-create-list]

Create a new contact list in SendGrid

<ReferenceDetails>
  #### Input [#input-5]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `name` | string | Yes | List name |

  #### Output [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | List ID |
  | `name` | string | List name |
  | `contactCount` | number | Number of contacts in the list |
</ReferenceDetails>

### SendGrid Get List [#sendgrid-get-list]

Get a specific list by ID from SendGrid

<ReferenceDetails>
  #### Input [#input-6]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `listId` | string | Yes | List ID |

  #### Output [#output-6]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | List ID |
  | `name` | string | List name |
  | `contactCount` | number | Number of contacts in the list |
</ReferenceDetails>

### SendGrid List All Lists [#sendgrid-list-all-lists]

Get all contact lists from SendGrid

<ReferenceDetails>
  #### Input [#input-7]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `pageSize` | number | No | Number of lists to return per page (default: 100, max: 1000) |
  | `pageToken` | string | No | Page token from a previous response (nextPageToken) to fetch the next page |

  #### Output [#output-7]

  | Parameter | Type | Description |
  | - | - | - |
  | `lists` | json | Array of lists |
  | `nextPageToken` | string | Token to pass as pageToken to fetch the next page, if more results exist |
</ReferenceDetails>

### SendGrid Delete List [#sendgrid-delete-list]

Delete a contact list from SendGrid

<ReferenceDetails>
  #### Input [#input-8]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `listId` | string | Yes | List ID to delete |

  #### Output [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `message` | string | Success message |
</ReferenceDetails>

### SendGrid Add Contacts to List [#sendgrid-add-contacts-to-list]

Add or update contacts and assign them to a list in SendGrid (uses PUT /v3/marketing/contacts)

<ReferenceDetails>
  #### Input [#input-9]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `listId` | string | Yes | List ID to add contacts to |
  | `contacts` | json | Yes | JSON array of contact objects. Each contact must have at least: email (or phone\_number\_id/external\_id/anonymous\_id). Example: \[\{"email": "[user@example.com](mailto:user@example.com)", "first\_name": "John"}] |

  #### Output [#output-9]

  | Parameter | Type | Description |
  | - | - | - |
  | `jobId` | string | Job ID for tracking the async operation |
  | `message` | string | Status message |
</ReferenceDetails>

### SendGrid Remove Contacts from List [#sendgrid-remove-contacts-from-list]

Remove contacts from a specific list in SendGrid

<ReferenceDetails>
  #### Input [#input-10]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `listId` | string | Yes | List ID |
  | `contactIds` | string | Yes | Comma-separated contact IDs to remove from the list |

  #### Output [#output-10]

  | Parameter | Type | Description |
  | - | - | - |
  | `jobId` | string | Job ID for the request |
</ReferenceDetails>

### SendGrid Create Template [#sendgrid-create-template]

Create a new email template in SendGrid

<ReferenceDetails>
  #### Input [#input-11]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `name` | string | Yes | Template name |
  | `generation` | string | No | Template generation type (legacy or dynamic, default: dynamic) |

  #### Output [#output-11]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Template ID |
  | `name` | string | Template name |
  | `generation` | string | Template generation |
  | `updatedAt` | string | Last update timestamp |
  | `versions` | json | Array of template versions |
</ReferenceDetails>

### SendGrid Get Template [#sendgrid-get-template]

Get a specific template by ID from SendGrid

<ReferenceDetails>
  #### Input [#input-12]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `templateId` | string | Yes | Template ID |

  #### Output [#output-12]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Template ID |
  | `name` | string | Template name |
  | `generation` | string | Template generation |
  | `updatedAt` | string | Last update timestamp |
  | `versions` | json | Array of template versions |
</ReferenceDetails>

### SendGrid List Templates [#sendgrid-list-templates]

Get all email templates from SendGrid

<ReferenceDetails>
  #### Input [#input-13]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `generations` | string | No | Filter by generation (legacy, dynamic, or both) |
  | `pageSize` | number | No | Number of templates to return per page (default: 20, max: 200). When paginating with pageToken, pass the same pageSize used on the first request to keep page boundaries consistent. |
  | `pageToken` | string | No | Page token from a previous response (nextPageToken) to fetch the next page |

  #### Output [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `templates` | json | Array of templates |
  | `nextPageToken` | string | Token to pass as pageToken to fetch the next page, if more results exist |
</ReferenceDetails>

### SendGrid Delete Template [#sendgrid-delete-template]

Delete an email template from SendGrid

<ReferenceDetails>
  #### Input [#input-14]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `templateId` | string | Yes | Template ID to delete |

  #### Output [#output-14]

  No output fields.
</ReferenceDetails>

### SendGrid Create Template Version [#sendgrid-create-template-version]

Create a new version of an email template in SendGrid

<ReferenceDetails>
  #### Input [#input-15]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | SendGrid API key |
  | `templateId` | string | Yes | Template ID |
  | `name` | string | Yes | Version name |
  | `subject` | string | Yes | Email subject line |
  | `htmlContent` | string | No | HTML content of the template |
  | `plainContent` | string | No | Plain text content of the template |
  | `active` | boolean | No | Whether this version is active (default: true) |

  #### Output [#output-15]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Version ID |
  | `templateId` | string | Template ID |
  | `name` | string | Version name |
  | `subject` | string | Email subject |
  | `active` | boolean | Whether this version is active |
  | `htmlContent` | string | HTML content |
  | `plainContent` | string | Plain text content |
  | `updatedAt` | string | Last update timestamp |
</ReferenceDetails>