@core / email

1.0.0 ▾

1.0.0

verifiedMIT

GitHub

Transactional email with typed React Email templates: Resend, SMTP or console in dev

Code9 filesContext~544 tokensscan passed

~544 tokens→ src/lib/email/AGENTS.md→ .cursor/rules/genpm-core-email.mdc

This is exactly what your AI reads when it works in src/lib/email. Nothing else is added to its context.

@core/email — rules for AI agents

Purpose

Transactional email with typed templates: sendEmail('welcome', { to, props }). Providers: Resend (default), SMTP (optional, via nodemailer) and a console provider for development. Templates use React Email. No marketing lists, no queues, no tracking pixels.

Map

index.ts — public API: sendEmail, renderEmail, setEmailProvider, provider factories, TemplateProps.
send.ts — the template registry (templates) and sendEmail.
templates/*.ts — welcome, magicLink, receipt, plus the shared layout.ts.
providers.ts — EmailProvider interface and implementations.

Integration

Env: EMAIL_FROM ("App <hello@yourdomain.com>") and RESEND_API_KEY (verify the domain in Resend first). Without RESEND_API_KEY, outside production, emails are printed to the console. @types/react is only needed at build time: move it to devDependencies if GenPM added it to dependencies. SMTP instead: EMAIL_PROVIDER=smtp, SMTP_URL=smtps://user:pass@host:465 and install nodemailer.

Send from server code only:

import { sendEmail } from './lib/email/index.js';
await sendEmail('welcome', { to: user.email, props: { name: user.name, appUrl: 'https://app.example.com' } });

With @core/auth: send welcome after the first login (when the user was just created).
Verify: run the app without RESEND_API_KEY and check the console output.

Conventions

New template: create templates/<name>.ts exporting { subject(props), render(props) } built with createElement as h (no JSX, so it works with any jsxImportSource), then add it to templates and TemplateProps in send.ts. TypeScript then enforces its props everywhere.
Amounts in minor units (cents); links absolute (https://…).
Keep sendEmail calls out of request hot paths when possible (after the response, or in a job).

Don't

Don't send from the browser or expose RESEND_API_KEY to client code.
Don't interpolate untrusted HTML into templates; pass plain strings (React escapes them).
Don't log full email bodies in production (they may contain sign-in links).

# @core/email — rules for AI agents

## Purpose
Transactional email with typed templates: `sendEmail('welcome', { to, props })`. Providers: Resend (default), SMTP
(optional, via `nodemailer`) and a console provider for development. Templates use React Email. No marketing lists,
no queues, no tracking pixels.

## Map
- `index.ts` — public API: `sendEmail`, `renderEmail`, `setEmailProvider`, provider factories, `TemplateProps`.
- `send.ts` — the template registry (`templates`) and `sendEmail`.
- `templates/*.ts` — `welcome`, `magicLink`, `receipt`, plus the shared `layout.ts`.
- `providers.ts` — `EmailProvider` interface and implementations.

## Integration
1. Env: `EMAIL_FROM` (`"App <hello@yourdomain.com>"`) and `RESEND_API_KEY` (verify the domain in Resend first).
   Without `RESEND_API_KEY`, outside production, emails are printed to the console.
   `@types/react` is only needed at build time: move it to devDependencies if GenPM added it to dependencies.
   SMTP instead: `EMAIL_PROVIDER=smtp`, `SMTP_URL=smtps://user:pass@host:465` and install `nodemailer`.
2. Send from server code only:
   ```ts
   import { sendEmail } from './lib/email/index.js';
   await sendEmail('welcome', { to: user.email, props: { name: user.name, appUrl: 'https://app.example.com' } });
   ```
3. With `@core/auth`: send `welcome` after the first login (when the user was just created).
4. Verify: run the app without `RESEND_API_KEY` and check the console output.

## Conventions
- New template: create `templates/<name>.ts` exporting `{ subject(props), render(props) }` built with
  `createElement as h` (no JSX, so it works with any `jsxImportSource`), then add it to `templates` and
  `TemplateProps` in `send.ts`. TypeScript then enforces its props everywhere.
- Amounts in minor units (cents); links absolute (`https://…`).
- Keep `sendEmail` calls out of request hot paths when possible (after the response, or in a job).

## Don't
- Don't send from the browser or expose `RESEND_API_KEY` to client code.
- Don't interpolate untrusted HTML into templates; pass plain strings (React escapes them).
- Don't log full email bodies in production (they may contain sign-in links).

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/email/index.tsread-only · 3e2976e

// @core/email — API pública: `sendEmail('welcome', { to, props })`.
export {
  consoleProvider,
  defaultProvider,
  type EmailMessage,
  type EmailProvider,
  resendProvider,
  type SendResult,
  smtpProvider,
} from './providers.js';
export { getEmailProvider, renderEmail, sendEmail, setEmailProvider, type TemplateName, type TemplateProps, templates } from './send.js';