Twilio SendGrid

This page covers how the Twilio SendGrid mailer package is wired, configured, and extended for transactional email plus CRM create, update, and destroy operations.

How it works

SendGrid keeps tools.mailer.from as { email, name } (twilioSendgridSchema in apps/shared/src/mailer/schema.ts) — there is no numeric sender id in config. Brevo uses the same from shape; it resolves Brevo’s transactional sender id at send time; see Brevo mailer. The backend chooses a mailer implementation from config, then delegates to the package contract. SendGrid handles both transactional delivery and CRM contact operations through one adapter boundary. The CRM API follows shared input contracts:

type MailingListContactUpdateInput = {
  email: string;
  firstName?: string;
  lastName?: string;
  phone?: string;
  join: MailListTags[];
  leave: MailListTags[];
};

join and leave overlap is a hard validation error and returns a standardized failure result.

Extending this system

Ensure apps/backend/package.json contains tooling-mailer-twilio-sendgrid as a workspace dependency.
Run make deps-install.
Set SendGrid config in apps/backend/src/configuration/production.ts or apps/backend/src/configuration/staging.ts:

mailer: {
  client: MailerClientType.TWILIO_SENDGRID,
  from: process.env.MAILER_FROM ?? '[email protected]',
  apiKey: process.env.SENDGRID_API_KEY ?? '',
  listIdByTag: {
    [MailListTags.WAITLIST]: Number(process.env.SENDGRID_WAITLIST_LIST_ID ?? 0),
  },
}

Add environment variables:

SENDGRID_API_KEY=SG.xxxxx
SENDGRID_WAITLIST_LIST_ID=123
MAILER_FROM=[email protected]

Add/update tests in apps/tools/mailer/twilio-sendgrid/__tests__/buildMailer.spec.ts and apps/backend/src/tools/mailer/__tests__/loader.spec.ts.
Run:

make test module=tooling-mailer-twilio-sendgrid
make test module=backend

What not to do

❌ Never call provider APIs directly from resolvers. ❌ Never skip the overlap validation for join and leave. ❌ Never log unmasked user emails/phones in mailer logs.

Live API smoke (optional)

This is for local development only — do not wire smoke:api into CI (it requires a real API key and can send email or create/delete contacts). Manually verify SendGrid v3 (auth, optional transactional send, and Marketing contact lifecycle) using the same request shapes as apps/tools/mailer/twilio-sendgrid/src/index.ts. Run the tooling-mailer-twilio-sendgrid package script inside the backend container. Never commit API keys. When Twilio SendGrid is your mailer in local dev, SENDGRID_API_KEY is already loaded into the backend service from .env.development (same env_file as Compose uses for the app). You do not need docker compose exec -e SENDGRID_API_KEY=... unless you are overriding the key for a one-off run. Marketing contact create is asynchronous; the script waits SENDGRID_SMOKE_ASYNC_WAIT_SEC seconds (default 4) before searching for the new contact. Increase it if step 6 flakes.

403 on /marketing/*: the key is valid for auth (e.g. GET /user/profile succeeds) but lacks Marketing API permissions. Run smoke:api: it calls GET /v3/scopes and warns if marketing_campaigns.* is missing (that list is authoritative for this key). Fix by enabling Marketing Campaigns on the account and/or using a key that includes those scopes — see SendGrid authorization and retrieve scopes.

Variable	Required	Purpose
`SENDGRID_API_KEY`	Yes (in container)	Same key as mailer config; normally from `.env.development`
`SENDGRID_SMOKE_FROM`	For mail send step	Verified sender email (`from` domain)
`SENDGRID_SMOKE_TO`	For mail send step	Recipient (sends a real test email)
`SENDGRID_SMOKE_LIST_ID`	For Marketing steps	List id (same idea as `listIdByTag`)
`SENDGRID_SMOKE_EMAIL`	For Marketing steps	Disposable contact email you control
`SENDGRID_SMOKE_ASYNC_WAIT_SEC`	No	Seconds after create before search (default `4`)

Without SENDGRID_SMOKE_*, GET /user/profile and GET /scopes still run (validates the key and prints which scopes it has, including whether marketing_campaigns.* is present). For the full suite, either add SENDGRID_SMOKE_* to .env.development and recreate/restart backend if needed, or pass them only on exec:

docker compose exec \
  -e SENDGRID_SMOKE_FROM="[email protected]" \
  -e SENDGRID_SMOKE_TO="[email protected]" \
  -e SENDGRID_SMOKE_LIST_ID="3" \
  -e SENDGRID_SMOKE_EMAIL="sg-smoke-$(date +%s)@yourverifieddomain.com" \
  backend pnpm --filter=tooling-mailer-twilio-sendgrid run smoke:api

Typical one-liner (key already in container; optional SENDGRID_SMOKE_* in .env.development):

docker compose exec backend pnpm --filter=tooling-mailer-twilio-sendgrid run smoke:api

The script runs: GET /user/profile, GET /scopes (with a WARN if marketing_campaigns.* is absent while Marketing env vars are set), optional POST /mail/send, then (when list + email are set) preclean delete (if found), create (PUT /marketing/contacts), wait, search, update (PUT /marketing/contacts), list add (PUT /marketing/lists/{id}/contacts), delete (DELETE /marketing/contacts) — and exits non-zero if any expected status is wrong.

File conventions

New implementation code goes in apps/tools/mailer/twilio-sendgrid/src/ with a single package entrypoint in src/index.ts. Keep package tests in apps/tools/mailer/twilio-sendgrid/__tests__/.

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

How it works

Extending this system

What not to do

Live API smoke (optional)

File conventions

What’s next?

​How it works

​Extending this system

​What not to do

​Live API smoke (optional)

​File conventions

​What’s next?

How it works

Extending this system

What not to do

Live API smoke (optional)

File conventions

What’s next?