SendGrid

sendgridEmail34 lines

Transactional email with dynamic templates and delivery analytics.

Current — as published in v1.3.2. Written by hand for SendGrid, not generated.

The rule

Where it runs

  • Server-side only. The API key sends mail as your domain to any recipient.
  • Use a restricted key with Mail Send permission only. A full-access key can read contacts and change account settings.

Sending

  • from must be an authenticated sender or the send is rejected.
  • Always include a plain-text alternative alongside HTML.
  • Idempotency on any retryable path. Sending cannot be undone, and retries are exactly what happens when something downstream fails.

Templates

  • Dynamic templates live in the dashboard: they are not in version control and change without a deploy. Record template ids in the codebase and treat an edit as a production change.
  • Keep dynamicTemplateData keys in sync with the template, or fields render blank with no error.

Deliverability

  • Handle bounce, dropped and spamreport from the Event Webhook and suppress those addresses.
  • Verify the webhook signature — the endpoint is public.

Never

  • Never put a token, password or session id in an email body. Send a short-lived single-use link.
  • Never log recipient lists or message bodies.

As each tool receives it

The same guidance, in the shape each editor reads. Cursor and Claude Code are written separately by hand; the rest are derived from the Cursor rule.

→ .cursor/rules/sendgrid.mdchand-written for this tool
.cursor/rules/sendgrid.mdc
---
description: SendGrid transactional email conventions
globs: ["server/**", "api/**", "src/services/email/**"]
alwaysApply: false
---

# SendGrid

## Where it runs

- **Server-side only.** The API key sends mail as your domain to any recipient.
- Use a **restricted** key with Mail Send permission only. A full-access key can
  read contacts and change account settings.

## Sending

- `from` must be an authenticated sender or the send is rejected.
- Always include a plain-text alternative alongside HTML.
- **Idempotency on any retryable path.** Sending cannot be undone, and retries
  are exactly what happens when something downstream fails.

## Templates

- Dynamic templates live in the dashboard: they are not in version control and
  change without a deploy. Record template ids in the codebase and treat an edit
  as a production change.
- Keep `dynamicTemplateData` keys in sync with the template, or fields render
  blank with no error.

## Deliverability

- Handle `bounce`, `dropped` and `spamreport` from the Event Webhook and
  suppress those addresses.
- Verify the webhook signature — the endpoint is public.

## Never

- Never put a token, password or session id in an email body. Send a short-lived
  single-use link.
- Never log recipient lists or message bodies.

What else this module writes

Selecting SendGrid contributes more than a rule file — all of it merged with every other module you pick, with conflicts resolved rather than duplicated.

Environment
SENDGRID_API_KEYrequiredRestricted key, Mail Send only. Never ship in the app.
SENDGRID_FROM_EMAILrequiredAuthenticated sender address. Unauthenticated senders are rejected.
SENDGRID_WEBHOOK_KEYoptionalVerifies Event Webhook signatures. The endpoint is public.
Dependencies
@sendgrid/mail^8.1.0
Folders
server/email/

Related

conflicts withResend
Put this in your repo

Adds SendGrid to a project this tool generated, without starting over. Files you have hand-edited are left alone.