SendGrid

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

Why route SendGrid through Datafly Signal

Profiles are updated from the server, not the browser. Events reach SendGrid even when a tracker blocker or a failed page unload would have dropped a client-side call, so the profile reflects what actually happened.
Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the SendGrid rate limit, and retries on 429 or transient failure rather than dropping the event.
One consent decision governs every destination. SendGrid is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

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.

Identify Custom Field IDs (optional)

Custom contact fields are keyed by field ID in SendGrid (for example e1_T). Navigate to Marketing > Contacts > Custom Fields to view them. The preset maps none; add custom_fields.<field id> mappings to the installed integration if you need them. A name that is not a field ID fails the whole request.

Configuration

Field	Type	Required	Description
`api_key`	secret	Yes	SendGrid API key with Marketing read/write scopes.

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": "general",
    "config": {
      "api_key": "SG.xxxxxxxxxxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

API endpoint

PUT https://api.sendgrid.com/v3/marketing/contacts

Allow egress to api.sendgrid.com from the network your delivery workers run on.

Event Mapping

The General preset upserts the contact (Add or Update a Contact, PUT /v3/marketing/contacts). SendGrid has no event concept on this endpoint, so the event only decides when the contact is refreshed.

Datafly event	SendGrid action
`sign_up`	Contact upsert
`identify`	Contact upsert
`purchase`	Contact upsert

Every other event is dropped, and so is any event with no email, user ID or phone (SendGrid requires one identifier per contact).

Identity

Field	Source	Handling
`email`	`email` trait, else `properties.email`	Trimmed and lower-cased. SendGrid’s primary contact key.
`external_id`	user ID	Your customer ID.
`first_name` / `last_name`	`first_name` / `last_name` traits, else properties	As sent.
`phone_number_id`	`phone` trait, else `properties.phone`	Normalised to E.164 (SendGrid requires a valid phone number).

The email and phone are sent in clear: SendGrid must have the address to send to, and does not accept hashed identifiers.

Request sent by Signal:

{
  "contacts": [
    {
      "email": "jane.doe@example.com",
      "external_id": "user-123",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number_id": "+447700900123"
    }
  ]
}

List membership and unsubscribe groups are communications permissions and are managed in SendGrid; the preset does not add contacts to lists and does not forward cookie consent. The integration’s consent categories gate delivery as for every destination.

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	A custom field mapped by name	Map custom fields by SendGrid field ID (Marketing > Contacts > Custom Fields).
Contacts missing	No identifier	Events without an email, user ID or phone are dropped.
`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.