SendGrid Email
Send templated transactional emails through SendGrid dynamic templates. Each synced row sends one personalized email to the recipient, with per-recipient values injected into the template.
This destination is distinct from the SendGrid destination, which syncs contacts to Marketing Campaigns lists. Use SendGrid Email when you want to send email, not manage list membership.
Prerequisites
- A SendGrid account with a dynamic template created (Email API → Dynamic Templates). The template ID starts with
d-. - A SendGrid API key (starts with
SG.) with the Mail Send permission. This is a separate scope from Marketing Campaigns permissions. - A verified sender: the From Email must be a verified Single Sender or an address on an authenticated domain in SendGrid.
Authentication
SendGrid Email uses API Key authentication.
- In SendGrid, go to Settings > API Keys.
- Create a new API key with the Mail Send permission (Restricted Access → enable Mail Send is sufficient).
- Copy the key (starts with
SG.). - Paste it into the API Key field in Zeotap.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Region | Select | Yes | SendGrid data center for Mail Send: United States (US) (api.sendgrid.com, default) or Europe (EU) (api.eu.sendgrid.com). See Data Residency below. |
| From Email | Text | Yes | Sender email address. Must be a verified Single Sender or on an authenticated domain. |
| From Name | Text | No | Display name for the sender. |
| Reply-To | Text | No | Reply-To email address. Defaults to From Email if not set. |
Additional destination-level settings — tracking and a custom footer — are under Deliverability.
Target Settings
These set the send parameters for the destination. Each can be overridden per sync and per journey send-to-destination tile — so a single SendGrid Email destination (one API key and sender identity) can drive different templates or categories across syncs and journeys. Set a base value on the destination; leave a sync’s or tile’s override blank to inherit it.
The Dynamic Template ID can be picked from a searchable dropdown of your account’s template names — Zeotap stores the corresponding d-… id. You can still type an id manually if a template isn’t listed.
| Field | Type | Required | Description |
|---|---|---|---|
| Dynamic Template ID | Text | Yes | SendGrid dynamic template ID (starts with d-). Find it under Email API → Dynamic Templates. |
| Categories | Text | No | Comma-separated SendGrid categories (max 10) for grouping and stats. |
| Sandbox Mode | Toggle | No | Validate requests without delivering email. Useful for testing. |
| Unsubscribe Group | Select | No | SendGrid unsubscribe (suppression) group associated with the email, so recipients can opt out of this category. Pick from your account’s groups (Marketing → Unsubscribe Groups). |
| Always send (bypass suppressions) | Toggle | No | Send even to suppressed addresses. Use only for true transactional mail (password resets, receipts). |
| IP Pool | Select | No | Send from a specific SendGrid IP pool. Leave blank for the account default. |
| Bypass spam / bounce / unsubscribe management | Toggle | No | Granular suppression bypass (each honors the other two lists). Cannot be combined with “Always send (bypass suppressions)”. |
| Google Analytics tracking | Toggle | No | Append UTM parameters to links. Reveals UTM Source / Medium / Campaign / Term / Content fields. |
Deliverability
These destination-level settings apply to every email from this destination. When a toggle is off, your SendGrid account default applies.
| Field | Type | Description |
|---|---|---|
| Click tracking | Toggle | Rewrite links to track clicks. |
| Open tracking | Toggle | Insert an open-tracking pixel. |
| Subscription tracking | Toggle | Append a SendGrid-managed unsubscribe link. |
| Add footer | Toggle | Append a footer (HTML and/or text) to every email. |
Scheduling
Map a column to the Send At field to schedule each email individually. Values may be unix seconds or RFC3339 timestamps and must be no more than 72 hours in the future; rows outside that window fail individually without affecting the rest of the batch.
Recipient & metadata mapping
Beyond the recipient email, you can map columns to these SendGrid fields in the field mapping:
| Field | Description |
|---|---|
| CC / BCC | Additional recipients — a single email, comma-separated list, or array column. |
| Custom Arguments | A JSON-object column (string→string) carried with the email for Event-Webhook correlation and analytics. You can build the object property-by-property: map each source column to the Custom Arguments (or Headers) destination and give it a property key (e.g. order_id). All such mappings combine into one object — no pre-shaped JSON column required. |
| Headers | A JSON-object column (string→string) of custom email headers. You can build the object property-by-property: map each source column to the Headers destination and give it a property key. All such mappings combine into one object — no pre-shaped JSON column required. |
Data Residency
SendGrid Email supports both the US and EU data centers, selected via the Region field:
- United States (US) — sends through
api.sendgrid.com(the global endpoint). - Europe (EU) — sends through
api.eu.sendgrid.com, keeping recipient PII, email content, and event data within the EU.
Selecting EU points Zeotap at the EU endpoint, but full EU data residency also requires configuration on the SendGrid side:
- Send from an EU regional subuser. Sending with a parent or global subuser key defaults to the global endpoint even against the EU host.
- A dedicated EU IP address.
- EU-pinned domain authentication (SPF, DKIM, and domain verification configured for the EU region).
Use an API key that belongs to your EU regional subuser when Region is set to EU.
Supported Operations
Sync Modes: Insert
Audience Sync Modes: Add
Each row (or audience member) triggers one email send. SendGrid Email is send-only — it does not support update, upsert, mirror, or remove operations.
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| Recipient email address |
Template Variables
The subject and body come from your SendGrid dynamic template. Zeotap populates the template’s {{placeholder}} variables from your mapped fields:
emailis reserved for the recipient address and is not passed as a template variable.- An optional
name(orfirst_name+last_name) field sets the recipient display name. - Every other mapped field becomes a template variable. A field mapped to
first_namefills{{first_name}}in the template; a field mapped toorder_idfills{{order_id}}.
Mapped field names must match the {{placeholder}} names in your template exactly.
Default Destination Fields
email, name, first_name, last_name, send_at, cc, bcc, custom_args, headers
send_at, cc, bcc, custom_args, and headers are routed to their SendGrid fields (see Scheduling and Recipient & metadata mapping); every other mapped field becomes a template variable.
How It Works
- Emails are sent via the SendGrid Mail Send API. Each recipient is a separate personalization carrying its own template variables.
- Recipients are batched up to 1,000 per request (SendGrid’s per-request limit). Larger syncs are split into multiple requests automatically.
- A successful send returns HTTP 202 (queued) — this confirms SendGrid accepted the email, not that it was delivered. Track delivery in the SendGrid Activity Feed or via the Event Webhook.
- Each send includes a
row_idcustom argument so you can correlate delivery events back to the source record in your Event Webhook.
Rate Limits
The Mail Send endpoint is governed by your SendGrid plan’s sending volume rather than a fixed request-rate limit. Zeotap automatically backs off and retries on rate-limit (429) and server (5xx) responses.
Troubleshooting
Authentication failed / 403 — sender not verified
The most common cause is an unverified sender. The From Email must be a verified Single Sender or on an authenticated domain. Verify it under Settings > Sender Authentication in SendGrid.
401 — API key missing Mail Send scope
A Marketing Campaigns key cannot send email. Create a key with the Mail Send permission. This is a different scope from the contact-sync (Marketing) destination.
Invalid template ID
The template ID must start with d- (a dynamic template). Legacy templates and Marketing Campaigns single sends are not supported. Copy the ID from Email API → Dynamic Templates.
Template variables not rendering
If {{placeholder}} text appears literally in the delivered email, the mapped field name does not match the template variable name. Ensure your field mappings use the exact placeholder keys (case-sensitive) defined in the template.
413 — payload too large
A single request must stay under 30 MB. Very large per-row template data can exceed this before the 1,000-recipient limit. Reduce the size of mapped fields feeding the template.
Emails queued but not delivered
A 202 response means SendGrid accepted the email for delivery. If recipients don’t receive it, check the SendGrid Activity Feed for bounces, blocks, or spam reports, and confirm your domain authentication is complete.