SendGrid Connector
Description
SendGrid is a cloud-based email delivery platform owned by Twilio. This component allows sending transactional and marketing emails, managing contacts, and tracking email analytics.
API Documentation
This component was built using the SendGrid API v3.
Connections
API Key
key: apiKeyTo authenticate with SendGrid, an API key is required.
Prerequisites
- A SendGrid account
Setup Steps
To generate an API key:
- Log in to the SendGrid Console
- Navigate to Settings > API Keys
- Click Create API Key
- Enter a name for the API key
- Select the appropriate access level:
- Full Access - Grants all permissions (recommended for integration use)
- Restricted Access - Grants specific permissions based on requirements
- Click Create & View
- Copy the API key value (it will only be displayed once)
For more information about creating API keys, refer to the SendGrid API Keys documentation.
Configure the Connection
- Enter the API key into the API Key field in the connection configuration
The API key is only displayed once upon creation. Store it securely. If the key is lost, a new one must be generated.
| Input | Notes | Example |
|---|---|---|
| API Key | The SendGrid API key used for authentication. Generate one in Settings > API Keys. Learn more | SG.1a2b3c4d5e6f7g8h.9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z |
Triggers
Managed Webhook Events
Receive event webhook notifications from SendGrid. Automatically creates and manages a webhook subscription when the instance is deployed, and removes the subscription when the instance is deleted. | key: eventWebhook
| Input | Notes | Example |
|---|---|---|
| Events | The email event types to subscribe to. Selected events trigger webhook notifications when they occur. | delivered |
| Friendly Name | A friendly name to help differentiate between multiple webhooks. | My Event Webhook |
| Connection | The SendGrid connection to use. |
The Event Webhook trigger can manage SendGrid event webhook subscriptions for an instance. Unlike traditional webhook setups that require manual configuration in the SendGrid dashboard, this trigger handles the entire webhook lifecycle.
When the trigger is used in a flow:
- On Instance Deploy: The trigger automatically creates a webhook endpoint in the SendGrid account pointing to the instance's unique webhook URL. If a webhook with the same ID already exists in the stored state, it updates the existing webhook instead of creating a duplicate. The trigger also automatically enables signature verification and stores the public key for validating incoming requests.
- On Instance Deletion: The trigger automatically removes the webhook endpoint from the SendGrid account.
Event Types
Configure the trigger to receive notifications for the following email events:
Event Types
| Event | Description |
|---|---|
| Delivered | Message has been successfully delivered to the receiving server |
| Bounce | Receiving server could not or would not accept the message |
| Deferred | Receiving server temporarily rejected the message |
| Processed | Message has been received and is ready to be delivered |
| Dropped | Message has been dropped (e.g., invalid header, spam content) |
| Open | Recipient has opened the HTML message |
| Click | Recipient clicked on a link within the message |
| Spam Report | Recipient marked the message as spam |
| Unsubscribe | Recipient clicked the unsubscribe link |
| Group Unsubscribe | Recipient unsubscribed from a specific group |
| Group Resubscribe | Recipient resubscribed to a specific group |
Enable the specific events to monitor by configuring the corresponding inputs when setting up the trigger.
Signature Verification
The trigger automatically verifies the authenticity of incoming webhook requests using SendGrid's ECDSA signature verification. When the webhook is created during instance deployment, signature verification is enabled and the public key is stored in the instance state.
For each incoming request, the trigger:
- Extracts the signature and timestamp from the
X-Twilio-Email-Event-Webhook-SignatureandX-Twilio-Email-Event-Webhook-Timestampheaders - Converts the stored public key to ECDSA format
- Verifies the signature against the raw request body
- Rejects requests with invalid signatures to prevent spoofing
This ensures that only genuine requests from SendGrid are processed by the flow.
Configuration
When configuring the Event Webhook trigger, specify:
- SendGrid Connection: The authenticated SendGrid API connection
- Friendly Name: A descriptive name to help differentiate between multiple webhooks
- Event Type Toggles: Enable the specific events to monitor (Delivered, Bounce, Open, Click, etc.)
Returned Data
The trigger returns the webhook payload containing an array of email events:
Example Payload
{
"payload": {
"headers": {
"Content-Type": "application/json;charset=utf-8",
"X-Twilio-Email-Event-Webhook-Signature": "MEQCIExampleSignatureBase64...",
"X-Twilio-Email-Event-Webhook-Timestamp": "1700000000"
},
"body": {
"data": [
{
"email": "user@example.com",
"event": "delivered",
"timestamp": 1700000000,
"sg_event_id": "ZGVsaXZlcmVkLTAtMTIzNDU2NzgtRXhhbXBsZQ==",
"sg_message_id": "ExampleMessageId123.recvd-abc123",
"response": "250 2.0.0 OK DMARC:Pass",
"category": ["Marketing", "Newsletter"],
"tls": 1
}
]
}
}
}
For complete event payload schemas, see the SendGrid Event Webhook Reference.
Example Payload for Managed Webhook Events⤓
New and Updated Messages
Checks for new and updated messages in SendGrid on a configured schedule. | key: pollChangesTrigger
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. | |
| Show New Records | When true, newly created records (a | true |
| Show Updated Records | When true, records whose | true |
The New and Updated Messages trigger polls SendGrid's Email Activity Feed (GET /v3/messages) on a configured schedule and emits messages whose last_event_time falls within the polling window.
When To Use This Trigger vs The Event Webhook Trigger
Webhooks are the recommended primary mechanism for receiving SendGrid email events. The Managed Webhook Events trigger (eventWebhook) handles subscription lifecycle and signature verification automatically.
This polling trigger is a fallback for historical or backfill ingestion scenarios:
- When a flow needs to catch up on events that occurred before a webhook subscription existed.
- When integrating with environments where outbound webhooks from SendGrid cannot reach the flow (firewalled, on-premise, etc.).
- When verifying or reconciling webhook-delivered events against the authoritative Email Activity Feed.
For new event-driven flows, prefer the Event Webhook trigger.
Requirements
- An API key with the Email Activity permission.
- The paid Email Activity History add-on enabled on the SendGrid account. Without it, the endpoint returns a
403/401and the trigger surfaces a clear runtime error.
How It Works
The trigger maintains a single ISO 8601 cursor (lastPolledAt) in polling state. Each run sends a SQL-like query:
last_event_time BETWEEN "<fromIso>" AND "<toIso>"
The window is constructed using three safeguards:
- 30-day retention clamp: SendGrid retains Email Activity for 30 days. On bootstrap (no prior cursor), or when the persisted cursor is older than 30 days, the lower bound is clamped to
now - 30d. Older events are not available from the feed. - 60-second eventual-consistency overlap: events surface in the feed a few minutes after the underlying send. The upper bound is set to
now - 60sto avoid tail-cutting events that are still propagating. The next poll re-scans the overlap, providing at-least-once delivery. - 6-hour window-walking step on truncation: the feed caps responses at 1000 records per request and the SendGrid query DSL does not expose
ORDER BY. When a response is truncated (1000 records returned), the cursor advances by a fixed 6-hour step instead of jumping tonow. This deterministically drains a backlog without dropping records in the un-fetched tail of the window.
Returned Data
The trigger returns separate arrays for created and updated records. Because of the feed limitation described above, created is always empty and all matching records are placed in updated. Fields shown are representative. The full response object includes additional properties.
Example Response (Polling)
{
"payload": {
"body": {
"data": {
"created": [],
"updated": [
{
"msg_id": "abc12345.recvd-67890-XYZ-1-1234567-1.0",
"from_email": "sender@example.com",
"to_email": "user@example.com",
"subject": "Hello from Acme!",
"status": "delivered",
"last_event_time": "2026-05-27T14:30:00Z",
"opens_count": 0,
"clicks_count": 0,
"api_key_id": "abc12345defg67890hijkXYZ",
"template_id": "d-exampletemplateid1234567890abcdef"
}
]
}
}
}
}
For the full message schema, see the SendGrid Email Activity Feed reference.
Example Payload for New and Updated Messages⤓
Webhook
Receives and validates webhook requests from SendGrid for manually configured webhook subscriptions. | key: webhook
A SendGrid event webhook can be configured to send information to a flow's webhook URL when an email is received.
Example Payload for Webhook⤓
Data Sources
Select Contact Lists
Fetches a list of contact lists from SendGrid. | key: sendGridListsDataSource | type: picklist
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. |
Example Payload for Select Contact Lists⤓
Select Webhook
Selects an event webhook from a SendGrid account. | key: selectWebhook | type: picklist
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. |
Example Payload for Select Webhook⤓
Actions
Add or Update Contact
Adds or updates a contact. Can also be used to add contacts to a list. | key: addOrUpdateContact
| Input | Notes | Example |
|---|---|---|
| Contacts | An array of contact objects to add or update. See SendGrid docs for contact object structure. | |
| List IDs | Comma-separated IDs of the lists to add the contact to. These lists must already exist. | ca3f4b4f-13a5-4321-9876-a1b2c3d4e5f6,d7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2 |
| Connection | The SendGrid connection to use. |
Example Payload for Add or Update Contact⤓
Create List
Creates a new contact list. | key: createList
| Input | Notes | Example |
|---|---|---|
| List Name | The display name for the new contact list. | My New Contact List |
| Connection | The SendGrid connection to use. |
Example Payload for Create List⤓
Create Webhook
Creates a new Event Webhook configuration to receive email event data. | key: createWebhook
| Input | Notes | Example |
|---|---|---|
| Enabled | When true, enables the Event Webhook. | true |
| Events | The email event types to subscribe to. Selected events trigger webhook notifications when they occur. | delivered |
| Friendly Name | A friendly name to help differentiate between multiple webhooks. | My Event Webhook |
| Connection | The SendGrid connection to use. | |
| Webhook URL | The URL where SendGrid will send event data. | https://example.com/webhook |
Example Payload for Create Webhook⤓
Delete Webhook
Deletes an Event Webhook configuration. | key: deleteWebhook
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. | |
| Webhook ID | The unique identifier for the Event Webhook configuration. | 77d4a5da-7015-11ed-a1eb-0242ac120002 |
Example Payload for Delete Webhook⤓
Get All Field Definitions
Retrieves all custom field definitions with pagination support. | key: getAllFieldDefinitions
| Input | Notes | Example |
|---|---|---|
| Fetch All | When true, fetches all pages of results using pagination. | false |
| Page Size | Number of results to return per page (max 100). | 10 |
| Page Token | Token for fetching the next or previous page of results. | |
| Connection | The SendGrid connection to use. |
Example Payload for Get All Field Definitions⤓
Get All Lists
Retrieves all contact lists with pagination support. | key: getAllLists
| Input | Notes | Example |
|---|---|---|
| Fetch All | When true, fetches all pages of results using pagination. | false |
| Page Size | Number of results to return per page (max 100). | 10 |
| Page Token | Token for fetching the next or previous page of results. | |
| Connection | The SendGrid connection to use. |
Example Payload for Get All Lists⤓
Get Contacts by Emails
Retrieves contacts by their email addresses. | key: getContactsByEmails
| Input | Notes | Example |
|---|---|---|
| Emails | Comma-separated email addresses to search for. | john.doe@example.com,jane.smith@example.com |
| Connection | The SendGrid connection to use. |
Example Payload for Get Contacts by Emails⤓
Get Import Status
Checks the status of a contact import job. | key: getImportStatus
| Input | Notes | Example |
|---|---|---|
| Job ID | The job ID returned from Import Contacts, Add/Update Contact, or Delete Contacts operations. | f8a7b6c5-d4e3-f2a1-b0c9-d8e7f6a5b4c3 |
| Connection | The SendGrid connection to use. |
Example Payload for Get Import Status⤓
Get List by ID
Retrieves a specific contact list by its ID. | key: getListById
| Input | Notes | Example |
|---|---|---|
| Include Sample Contacts | When true, includes a sample of contacts in the response. | false |
| List ID | The unique identifier for the contact list to retrieve. | ca3f4b4f-13a5-4321-9876-a1b2c3d4e5f6 |
| Connection | The SendGrid connection to use. |
Example Payload for Get List by ID⤓
Get Webhook
Retrieves an Event Webhook configuration by ID. | key: getWebhook
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. | |
| Webhook ID | The unique identifier for the Event Webhook configuration. | 77d4a5da-7015-11ed-a1eb-0242ac120002 |
Example Payload for Get Webhook⤓
Initiate Contacts Import
Initiates a CSV contact import. Returns a URL and headers for uploading the CSV file. | key: initiateContactsImport
| Input | Notes | Example |
|---|---|---|
| Field Mappings | An array of field definition IDs to map the uploaded CSV columns. Use null to skip a column. Get IDs from 'Get All Field Definitions' action. | |
| Is Compressed | When true, indicates that the CSV file will be gzip-compressed. | false |
| List IDs | Comma-separated IDs of the lists to add the contact to. These lists must already exist. | ca3f4b4f-13a5-4321-9876-a1b2c3d4e5f6,d7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2 |
| Connection | The SendGrid connection to use. |
Example Payload for Initiate Contacts Import⤓
List Webhooks
Lists all Event Webhook configurations. | key: listWebhooks
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. |
Example Payload for List Webhooks⤓
Raw Request
Sends a raw HTTP request to SendGrid. | key: rawRequest
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. | |
| Data | The HTTP body payload to send to the URL. | {"exampleKey": "Example Data"} |
| File Data | File Data to be sent as a multipart form upload. | [{key: "example.txt", value: "My File Contents"}] |
| File Data File Names | File names to apply to the file data inputs. Keys must match the file data keys above. | |
| Form Data | The Form Data to be sent as a multipart form upload. | [{"key": "Example Key", "value": new Buffer("Hello World")}] |
| Header | A list of headers to send with the request. | User-Agent: curl/7.64.1 |
| Max Retry Count | The maximum number of retries to attempt. Specify 0 for no retries. | 0 |
| Method | The HTTP method to use. | |
| Query Parameter | A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2. | |
| Response Type | The type of data you expect in the response. You can request json, text, or binary data. | json |
| Retry On All Errors | If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors. | false |
| Retry Delay (ms) | The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled. | 0 |
| Timeout | The maximum time that a client will await a response to its request | 2000 |
| URL | Input the path only (/templates), The base URL is already included (https://api.sendgrid.com/v3). For example, to connect to https://api.sendgrid.com/v3/templates, only /templates is entered in this field. | /templates |
| Use Exponential Backoff | Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored. | false |
Send Email
Sends a single email to one or more recipients. | key: sendEmail
| Input | Notes | Example |
|---|---|---|
| BCC | The recipient's email address, or a comma-separated list of recipient email addresses to BCC. | john.doe@example.com,jane.smith@example.com |
| CC | The recipient's email address, or a comma-separated list of recipient email addresses to CC. | john.doe@example.com,jane.smith@example.com |
| Attachment Content | Provide attachment data to send with the email. The 'File Name' field is required when using this input and should reference the data output from a previous action. | |
| Content ID | Provide the content Id of the attachment. This value is only required when you select 'inline'. | 12345 |
| Disposition | Specifies how the attachment is displayed. Use 'inline' for embedded content or 'attachment' for a downloadable file. | inline |
| File Name | Provide a name for the file to attach. The 'Attachment Content' field is required when using this input. | reports.csv |
| File Type | The MIME type of the content you are attaching. | text/plain |
| From Email | The verified sender email address that appears in the 'From' field. Must be a verified sender in SendGrid. | sender@example.com |
| From Name | The display name that appears alongside the sender email address in the recipient's inbox. | John Doe |
| HTML | The HTML-formatted content of the email. When provided, takes priority over the plain-text body in clients that support HTML rendering. | Hello from <b>Acme!</b> |
| Multiple Attachments | Provide an array of attachments to send with the email. See SendGrid API documentation for more information. | |
| Personalizations | Allows overwriting multiple properties of the email such as recipients, subject, and send time per recipient. See SendGrid personalizations docs for examples. | |
| Reply To Email | The email address recipients see when they reply. Only used when different from the sender address. | support@example.com |
| Reply To Name | Name to reply to. This field is only required when you provide a value for Reply To Email. | John Doe |
| Connection | The SendGrid connection to use. | |
| Subject | The subject line displayed in the recipient's inbox. Supports UTF-8 encoding. | Hello from Acme! |
| Subscription Tracking | When true, inserts a subscription management link at the bottom of the text and HTML bodies of your email. | false |
| Text | The plain-text content of the email, used as a fallback when HTML is not supported by the recipient's email client. | Here's the body of a notification. |
| To | The recipient's email address, or a comma-separated list of recipient email addresses. | john.doe@example.com,jane.smith@example.com |
Example Payload for Send Email⤓
Send Email with Dynamic Template
Sends an email using a SendGrid dynamic template with complex nested JSON data. | key: sendEmailWithDynamicTemplate
| Input | Notes | Example |
|---|---|---|
| BCC | The recipient's email address, or a comma-separated list of recipient email addresses to BCC. Will be ignored if 'Personalizations' is provided. | john.doe@example.com,jane.smith@example.com |
| CC | The recipient's email address, or a comma-separated list of recipient email addresses to CC. Will be ignored if 'Personalizations' is provided. | john.doe@example.com,jane.smith@example.com |
| Dynamic Template Data | The data to be used for the dynamic template. Supports complex nested JSON structures including arrays and objects for order confirmations, customer data, and more. | |
| From Email | The verified sender email address that appears in the 'From' field. Must be a verified sender in SendGrid. | sender@example.com |
| From Name | The display name that appears alongside the sender email address in the recipient's inbox. | John Doe |
| Personalizations | Advanced: Provide a personalizations array to send different variations to different recipients. When provided, this will override 'To', 'CC', and 'BCC' inputs. Each personalization will automatically include the dynamic template data. | |
| Reply To Email | The email address recipients see when they reply. Only used when different from the sender address. | support@example.com |
| Reply To Name | Name to reply to. This field is only required when you provide a value for Reply To Email. | John Doe |
| Connection | The SendGrid connection to use. | |
| Template ID | The unique identifier for the dynamic template. Found in the SendGrid dashboard under Email API > Dynamic Templates. | 1234567890 |
| To | The recipient's email address, or a comma-separated list of recipient email addresses. Required if 'Personalizations' is not provided. Will be ignored if 'Personalizations' is provided. | john.doe@example.com,jane.smith@example.com |
Example Payload for Send Email with Dynamic Template⤓
Send Multiple Emails
Sends a separate email to each recipient. | key: sendMultipleEmails
| Input | Notes | Example |
|---|---|---|
| BCC | The recipient's email address, or a comma-separated list of recipient email addresses to BCC. | john.doe@example.com,jane.smith@example.com |
| CC | The recipient's email address, or a comma-separated list of recipient email addresses to CC. | john.doe@example.com,jane.smith@example.com |
| Attachment Content | Provide attachment data to send with the email. The 'File Name' field is required when using this input and should reference the data output from a previous action. | |
| Content ID | Provide the content Id of the attachment. This value is only required when you select 'inline'. | 12345 |
| Disposition | Specifies how the attachment is displayed. Use 'inline' for embedded content or 'attachment' for a downloadable file. | inline |
| File Name | Provide a name for the file to attach. The 'Attachment Content' field is required when using this input. | reports.csv |
| File Type | The MIME type of the content you are attaching. | text/plain |
| From Email | The verified sender email address that appears in the 'From' field. Must be a verified sender in SendGrid. | sender@example.com |
| From Name | The display name that appears alongside the sender email address in the recipient's inbox. | John Doe |
| HTML | The HTML-formatted content of the email. When provided, takes priority over the plain-text body in clients that support HTML rendering. | Hello from <b>Acme!</b> |
| Multiple Attachments | Provide an array of attachments to send with the email. See SendGrid API documentation for more information. | |
| Personalizations | Allows overwriting multiple properties of the email such as recipients, subject, and send time per recipient. See SendGrid personalizations docs for examples. | |
| Reply To Email | The email address recipients see when they reply. Only used when different from the sender address. | support@example.com |
| Reply To Name | Name to reply to. This field is only required when you provide a value for Reply To Email. | John Doe |
| Connection | The SendGrid connection to use. | |
| Subject | The subject line displayed in the recipient's inbox. Supports UTF-8 encoding. | Hello from Acme! |
| Text | The plain-text content of the email, used as a fallback when HTML is not supported by the recipient's email client. | Here's the body of a notification. |
| To | The recipient's email address, or a comma-separated list of recipient email addresses. | john.doe@example.com,jane.smith@example.com |
Example Payload for Send Multiple Emails⤓
Test Webhook
Tests an Event Webhook by sending a fake event notification. | key: testWebhook
| Input | Notes | Example |
|---|---|---|
| Connection | The SendGrid connection to use. | |
| Test URL | The URL where the test event will be sent. | https://example.com/test-webhook |
Example Payload for Test Webhook⤓
Toggle Signature Verification
Enables or disables signature verification for an Event Webhook. | key: toggleSignatureVerification
| Input | Notes | Example |
|---|---|---|
| Enable Signature Verification | When true, enables signature verification for webhook requests. | true |
| Connection | The SendGrid connection to use. | |
| Webhook ID | The unique identifier for the Event Webhook configuration. | 77d4a5da-7015-11ed-a1eb-0242ac120002 |
Example Payload for Toggle Signature Verification⤓
Update Webhook
Updates an existing Event Webhook configuration. | key: updateWebhook
| Input | Notes | Example |
|---|---|---|
| Enabled | When true, enables the Event Webhook. | true |
| Events | The email event types to subscribe to. Selected events trigger webhook notifications when they occur. | delivered |
| Friendly Name | A friendly name to help differentiate between multiple webhooks. | My Event Webhook |
| Connection | The SendGrid connection to use. | |
| Webhook URL | The URL where SendGrid will send event data. | https://example.com/webhook |
| Webhook ID | The unique identifier for the Event Webhook configuration. | 77d4a5da-7015-11ed-a1eb-0242ac120002 |
Example Payload for Update Webhook⤓
Changelog
2026-07-15
Resolved Send Email and Send Multiple Emails action issue related to sending a message without attachments.
2026-06-04
Added the New and Updated Messages polling trigger that retrieves email activity events from the SendGrid Email Activity Feed
2026-04-30
Updated spectral version
2026-03-31
Various modernizations and documentation updates
2026-03-16
Improved input field documentation with formatted URL links for better readability
2026-02-26
Added inline data source for webhooks to enable dynamic dropdown selection
2026-01-27
Added the Managed Webhook Events trigger to receive event webhook notifications from SendGrid. It will automatically create and manage a webhook subscription when an instance is deployed, and removes the subscription when the instance is deleted.
2025-06-18
Added an inline data source for Contacts and Lists to enhance list selection capabilities
2025-05-27
Added list management and contact import support for improved email campaign management