SendGrid

SendGrid (Twilio) is a transactional and marketing email platform with high-deliverability infrastructure and a marketing automation suite (SendGrid Marketing Campaigns).

⚠️

This integration is currently in alpha. Configuration and behaviour may change. This integration covers contact list / Marketing Campaigns sync. For one-off transactional emails, use SendGrid’s Mail Send API directly.

Prerequisites

Complete these steps in SendGrid before configuring Signal.

Access your SendGrid account

Create an API Key

Navigate to Settings > API Keys and click Create API Key. Configure:

Name: e.g. “Datafly Signal”.
Permissions: select Restricted Access and grant at minimum:
- Marketing → Read, Write (contacts, lists, custom fields).
Click Create & View.
Copy the API Key immediately — it will not be shown again.

Find or create a Marketing List (optional)

If you want all Signal-identified contacts added to a specific list, navigate to Marketing > Contacts > Lists. Note the List ID of the target list.

Identify Custom Field IDs (optional)

Custom contact fields have numeric IDs in SendGrid. Navigate to Marketing > Contacts > Custom Fields to view them. Signal can map Datafly traits to these.

Configuration

Field	Type	Required	Description
`api_key`	secret	Yes	SendGrid API key with Marketing read/write scopes.
`default_list_id`	string	No	List ID to auto-add identified contacts to.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find SendGrid under the Marketing Automation category.
Click Install, and fill in the required fields.
Click Install Integration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/sendgrid/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SendGrid",
    "variant": "default",
    "config": {
      "api_key": "SG.xxxxxxxxxxxxxxxxxxxx",
      "default_list_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

Datafly Event	SendGrid Concept	Notes
`page`	Custom field update	Last page URL written to a custom field for segmentation.
`Product Viewed`	Custom field update	Last product ID stored as a custom field.
`Order Completed`	Contact upsert with revenue	Contact updated with `last_purchase_at`, `lifetime_value`.
`identify`	Contact upsert	Email and traits sent via `PUT /v3/marketing/contacts`.

Identity

Field	Source	Notes
`email`	`traits.email`	SendGrid’s primary contact key.
`first_name`	`traits.first_name`	Standard contact field.
`last_name`	`traits.last_name`	Standard contact field.
`phone_number`	`traits.phone`	Optional contact field.
`external_id`	`user_id` from `datafly.identify()`	Stable cross-reference to your customer ID (stored as a custom field).

SendGrid events should be sent under the marketing consent category. SendGrid maintains its own unsubscribe groups — Signal forwards CMP consent state so workflows can update opt-in/opt-out status as needed.

Verify it’s working

Trigger a test identify event from your website.
In SendGrid, navigate to Marketing > Contacts and search for the test contact by email.
Open the contact to view custom field values and list membership.
In Signal, check Live Events to confirm delivery with a 202 response status (SendGrid upserts are asynchronous).

Troubleshooting

Symptom	Possible Cause	Resolution
`401 Unauthorized`	Invalid API key or missing scopes	Verify the key in Settings > API Keys and ensure Marketing read/write permissions are granted.
Contact upsert pending	Asynchronous processing	SendGrid contact upserts return 202 and process asynchronously — allow a few minutes before checking.
Custom field error	Field ID mismatch	Confirm the custom field IDs in Marketing > Contacts > Custom Fields.
`429 Too Many Requests`	Rate limit exceeded	SendGrid enforces per-account contact-upsert limits. Signal retries automatically.

Visit SendGrid Marketing Campaigns API documentation for full reference.