Skip to main content
sendgrid icon

SendGrid Connector

SourceAPI DocsAPI ChangelogConnector Changelog

Description​

SendGrid is a cloud-based email delivery platform owned by Twilio. This component allows you to send transactional and marketing emails, manage contacts, and track email analytics.

API Documentation​

This component was built using the SendGrid API v3.

Connections​

API Key​

key: apiKey

To authenticate with SendGrid, an API key is required.

Setup Steps​

To generate an API key:

  1. Log in to the SendGrid Console
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Enter a name for the API key
  5. Select the appropriate access level:
    • Full Access - Grants all permissions (recommended for integration use)
    • Restricted Access - Grants specific permissions based on requirements
  6. Click Create & View
  7. 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
API Key Security

The API key is only displayed once upon creation. Store it securely. If the key is lost, a new one must be generated.

InputNotesExample
API Key

API Key from your SendGrid account. 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

InputNotesExample
Events

The events to track.

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
EventDescription
DeliveredMessage has been successfully delivered to the receiving server
BounceReceiving server could not or would not accept the message
DeferredReceiving server temporarily rejected the message
ProcessedMessage has been received and is ready to be delivered
DroppedMessage has been dropped (e.g., invalid header, spam content)
OpenRecipient has opened the HTML message
ClickRecipient clicked on a link within the message
Spam ReportRecipient marked the message as spam
UnsubscribeRecipient clicked the unsubscribe link
Group UnsubscribeRecipient unsubscribed from a specific group
Group ResubscribeRecipient 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:

  1. Extracts the signature and timestamp from the X-Twilio-Email-Event-Webhook-Signature and X-Twilio-Email-Event-Webhook-Timestamp headers
  2. Converts the stored public key to ECDSA format
  3. Verifies the signature against the raw request body
  4. 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⤓
Loading…

Manual Webhook​

Receive and validate webhook requests from SendGrid for manually configured webhooks. | key: webhook

You can configure a SendGrid event webhook to send information to a flow's webhook URL when an email is received.

New and Updated Messages​

Checks for new and updated messages in SendGrid's Email Activity Feed (GET /v3/messages) on a configured schedule, emitting messages whose last_event_time falls within the polling window. Webhooks (the Managed Webhook Events trigger) are the recommended primary mechanism for event delivery — this polling trigger is a fallback for historical or backfill ingestion. Requires the paid Email Activity History add-on and an API key with the Email Activity permission. SendGrid retains Email Activity for only 30 days, and events surface a few minutes after the underlying send (the trigger handles both: bootstrap is clamped to the retention window and a small overlap is subtracted from now to avoid tail-cutting in-flight events). Because the bulk Email Activity Feed exposes a single last_event_time per message (no per-event timeline), the created/updated split is best-effort: all records are emitted on the updated branch. | key: pollChangesTrigger

InputNotesExample
Connection

The SendGrid connection to use.

Show New Records

When true, newly created records (a processed event observed within the polling window) are included on the created branch. SendGrid surfaces a single last_event_time per message, so the created vs updated split is best-effort based on the event timeline.

true
Show Updated Records

When true, records whose last_event_time falls within the polling window are included on the updated branch.

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/401 and 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 - 60s to 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 to now. 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⤓
Loading…

Data Sources​

Select Webhook​

Select an event webhook from your SendGrid account. | key: selectWebhook | type: picklist

InputNotesExample
Connection

The SendGrid connection to use.

Example Payload for Select Webhook⤓
Loading…

SendGrid Contact Lists​

Fetch a picklist of contact lists from SendGrid | key: sendGridListsDataSource | type: picklist

InputNotesExample
Connection

The SendGrid connection to use.

Example Payload for SendGrid Contact Lists⤓
Loading…

Actions​

Add or Update Contact​

Add or update a contact. This can also be used to add contacts to a list. | key: addOrUpdateContact

InputNotesExample
Contacts

An array of contact objects to add or update. See SendGrid docs for contact object structure.

[
  {
    "email": "ryan.testing@example.com",
    "custom_fields": {
      "w2": "George"
    }
  },
  {
    "email": "cassie.testing@example.com",
    "first_name": "Cassie",
    "last_name": "Testing",
    "custom_fields": {
      "w1": "Human"
    }
  }
]
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⤓
Loading…

Create List​

Create a new contact list | key: createList

InputNotesExample
List Name

The name of the list to create.

My New Contact List
Connection

The SendGrid connection to use.

Example Payload for Create List⤓
Loading…

Create Webhook​

Create a new Event Webhook configuration to receive email event data. | key: createWebhook

InputNotesExample
Enabled

When true, enables the Event Webhook.

true
Events

The events to track.

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⤓
Loading…

Delete Webhook​

Delete an Event Webhook configuration. | key: deleteWebhook

InputNotesExample
Connection

The SendGrid connection to use.

Webhook ID

The ID of the webhook.

77d4a5da-7015-11ed-a1eb-0242ac120002
Example Payload for Delete Webhook⤓
Loading…

Get All Field Definitions​

Retrieve all custom field definitions with pagination support | key: getAllFieldDefinitions

InputNotesExample
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⤓
Loading…

Get All Lists​

Retrieve all contact lists with pagination support | key: getAllLists

InputNotesExample
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⤓
Loading…

Get Contacts by Emails​

Retrieve contacts by their email addresses. | key: getContactsByEmails

InputNotesExample
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⤓
Loading…

Get Import Status​

Check the status of a contact import job | key: getImportStatus

InputNotesExample
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⤓
Loading…

Get List by ID​

Retrieve a specific contact list by its ID | key: getListById

InputNotesExample
Include Sample Contacts

When true, includes a sample of contacts in the response.

false
List ID

The ID of the list to retrieve.

ca3f4b4f-13a5-4321-9876-a1b2c3d4e5f6
Connection

The SendGrid connection to use.

Example Payload for Get List by ID⤓
Loading…

Get Webhook​

Retrieve an Event Webhook configuration by ID. | key: getWebhook

InputNotesExample
Connection

The SendGrid connection to use.

Webhook ID

The ID of the webhook.

77d4a5da-7015-11ed-a1eb-0242ac120002
Example Payload for Get Webhook⤓
Loading…

Initiate Contacts Import​

Initiates a CSV contact import. Returns a URL and headers for uploading the CSV file. | key: initiateContactsImport

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

[
  null,
  "w1",
  "_rf1"
]
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⤓
Loading…

List Webhooks​

List all Event Webhook configurations. | key: listWebhooks

InputNotesExample
Connection

The SendGrid connection to use.

Example Payload for List Webhooks⤓
Loading…

Raw Request​

Send raw HTTP request to SendGrid | key: rawRequest

InputNotesExample
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​

Send a single email to one or more recipients | key: sendEmail

InputNotesExample
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 you would like the attachment to be displayed.

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 sender's email address.

sender@example.com
From Name

The sender's name.

John Doe
HTML

The optional HTML body of the email.

Hello from <b>Acme!</b>
Multiple Attachments

Provide an array of attachments to send with the email. See SendGrid API documentation for more information.

{"content":"<base64 encoded content>","disposition":"inline","filename":"reports.csv","type":"text/csv","content_id":"12345"}
Personalizations

You can use this field to overwrite multiple properties of the email. For examples of which properties to use, checkout the SendGrid docs: https://docs.sendgrid.com/for-developers/sending-email/personalizations

[
  {
    "to": [
      {
        "email": "john@example.com"
      }
    ],
    "send_at": 1600188812
  },
  {
    "to": [
      {
        "email": "jane@example.com"
      }
    ],
    "send_at": 1600275471
  }
]
Reply To Email

Email To Reply To.

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 email subject line.

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 text body of the email.

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⤓
Loading…

Send Email with Dynamic Template​

Send an email using a SendGrid dynamic template with complex nested JSON data | key: sendEmailWithDynamicTemplate

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

{
  "store": {
    "name": "Acme Store",
    "code": "ACME01",
    "url": "https://store.example.com",
    "supportEmail": "support@acmestore.com"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+1-555-123-4567",
    "customerId": "CUST-12345"
  }
}
From Email

The sender's email address.

sender@example.com
From Name

The sender's name.

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.

[
  {
    "to": [
      {
        "email": "john@example.com"
      }
    ],
    "send_at": 1600188812
  },
  {
    "to": [
      {
        "email": "jane@example.com"
      }
    ],
    "send_at": 1600275471
  }
]
Reply To Email

Email To Reply To.

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 ID of the dynamic template to use.

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⤓
Loading…

Send Multiple Emails​

Send a separate email to each recipient | key: sendMultipleEmails

InputNotesExample
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 you would like the attachment to be displayed.

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 sender's email address.

sender@example.com
From Name

The sender's name.

John Doe
HTML

The optional HTML body of the email.

Hello from <b>Acme!</b>
Multiple Attachments

Provide an array of attachments to send with the email. See SendGrid API documentation for more information.

{"content":"<base64 encoded content>","disposition":"inline","filename":"reports.csv","type":"text/csv","content_id":"12345"}
Personalizations

You can use this field to overwrite multiple properties of the email. For examples of which properties to use, checkout the SendGrid docs: https://docs.sendgrid.com/for-developers/sending-email/personalizations

[
  {
    "to": [
      {
        "email": "john@example.com"
      }
    ],
    "send_at": 1600188812
  },
  {
    "to": [
      {
        "email": "jane@example.com"
      }
    ],
    "send_at": 1600275471
  }
]
Reply To Email

Email To Reply To.

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 email subject line.

Hello from Acme!
Text

The text body of the email.

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⤓
Loading…

Test Webhook​

Test an Event Webhook by sending a fake event notification. | key: testWebhook

InputNotesExample
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⤓
Loading…

Toggle Signature Verification​

Enable or disable signature verification for an Event Webhook. | key: toggleSignatureVerification

InputNotesExample
Enable Signature Verification

When true, enables signature verification for webhook requests.

true
Connection

The SendGrid connection to use.

Webhook ID

The ID of the webhook.

77d4a5da-7015-11ed-a1eb-0242ac120002
Example Payload for Toggle Signature Verification⤓
Loading…

Update Webhook​

Update an existing Event Webhook configuration. | key: updateWebhook

InputNotesExample
Enabled

When true, enables the Event Webhook.

true
Events

The events to track.

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 ID of the webhook.

77d4a5da-7015-11ed-a1eb-0242ac120002
Example Payload for Update Webhook⤓
Loading…

Changelog​

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