SendGrid

Transactional email with dynamic templates and delivery analytics.

adds it to an existing project · no account needed
Currentas published in v1.5.1

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

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.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/sendgrid.mdchand-written
---
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.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

What else this module writes

The rule is one file of several. Selecting SendGrid contributes all of this too — 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/

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →

Rules people add alongside this one

conflicts withResend
Put this rule in a real project

The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.