SendGrid

This connector uses the SendGrid v3 REST API.

Setup:

1. Sign in to SendGrid (or via Twilio's console — SendGrid is part of Twilio since 2019) → Settings → API Keys → Create API Key.
2. Pick Restricted Access and grant at least: Mail Send (Full Access), Template Engine (Read), Stats (Read), Suppressions (Read), Marketing > Contacts (Read+Write), Marketing > Lists (Read+Write). Full Access also works but follows least-privilege poorly.
3. Copy the key — it's shown ONCE. Set SENDGRID_API_KEY to it.
4. (Optional) If your account is on the EU datacenter (GDPR data residency), set SENDGRID_BASE_URL to https://api.eu.sendgrid.com. Default is the global https://api.sendgrid.com.

Authentication: Bearer token (Authorization: Bearer ${SENDGRID_API_KEY}).

Sender authentication first! SendGrid will silently quarantine emails from un-verified senders. Before sending production mail, verify either:

• Single Sender (quick, for low volume): Settings → Sender Authentication → Verify a Single Sender. SendGrid emails a verification link.
• Domain Authentication (recommended for any real volume): Settings → Sender Authentication → Authenticate Your Domain. Adds CNAME records to your DNS. The from.email in sendgrid_send_mail must match an authenticated sender, otherwise emails will be silently rejected or marked as spam.

Mail send body model: SendGrid uses a message-level + per-recipient model. The personalizations array lets you send N customized versions in one API call (each with its own to, subject, substitutions). For a simple 'send the same email to one person' call, use a single personalization with one to.

Content order matters: when sending both plain-text and HTML, list text/plain BEFORE text/html in the content array per RFC 2046.

Templates (dynamic): SendGrid's modern templates are Dynamic Templates (Handlebars-based). To send one, omit subject/content, set template_id at the message level, and pass dynamic_template_data per personalization. The legacy Transactional Templates use substitutions and are still supported but deprecated.

Categories (≤10 per email, alphanumeric + underscore): tag your sends to group them in Stats. The adapter accepts categories at the top of sendgrid_send_mail.

Suppression precedence: bounces, blocks, invalid emails, spam reports, and unsubscribes all live in the suppression group. Even a perfectly authenticated message to a suppressed address won't deliver. Use sendgrid_list_bounces and remove with sendgrid_delete_bounce (not exposed here — bounce removal must be explicit and is GDPR-sensitive, do it via the SendGrid UI).

Marketing Contacts: contacts are NOT the same as suppression list. The Marketing API (/v3/marketing/contacts) is for the Marketing Campaigns product (newsletters), separate from transactional Mail Send. Adding a contact to Marketing does NOT affect deliverability of transactional mail to that address.

Rate limits: Mail Send caps depend on plan (Essentials: 100k/month; Pro: 1.5M/month, etc.). Burst limits ~600 req/min for transactional, higher with dedicated IPs. On 429, back off.

Webhooks (Event Webhook) out of scope for this connector — host your own receiver to ingest delivery/bounce/open/click events.

Out of scope here: subuser management, IP warmup, A/B testing, single sends, designs, and the legacy Web v2 API.