stacks-email

# Stacks Email Multi-driver email system with template rendering, S3-based inbox management, and 7 built-in drivers. ## Key Paths - Core package: `storage/framework/core/email/src/` - Configuration: `config/email.ts` - Application mail: `app/Mail/` - Email layouts: `storage/framework/defaults/resources/emails/layouts/` - Email resources: `storage/framework/defaults/resources/emails/` ## Source Files ``` email/src/ ├── index.ts # All exports ├── email.ts # Email class + Mail singleton ├── template.ts # Template rendering engine ├── types.ts # Types and interfaces ├── sdk/index.ts # EmailSDK (send + inbox management) └── drivers/ ├── base.ts # BaseEmailDriver abstract class ├── ses.ts # AWS SES driver ├── sendgrid.ts # SendGrid driver ├── mailgun.ts # Mailgun driver ├── mailtrap.ts # Mailtrap driver (sandbox/production) └── smtp.ts # Raw SMTP driver (TLS/STARTTLS) ``` `log` and `capture` are also registered by the Mail singleton. `log` writes messages to `storage/logs/mail/` for local inspection. `capture` keeps messages in memory for deterministic tests. Unsupported names fail at the first send, so `MAIL_MAILER` must be one of `smtp`, `ses`, `sendgrid`, `mailgun`, `mailtrap`, `log`, or `capture`. ## Mail Singleton ```typescript import { mail } from '@stacksjs/email' await mail.send({ from: { name: 'App', address: 'noreply@app.com' }, to: 'user@example.com', subject: 'Welcome', html: '<h1>Hello!</h1>', text: 'Hello!' }) // Switch driver const sendgridMail = mail.use('sendgrid') await sendgridMail.send(message) ``` ## Email Class ```typescript const email = new Email({ name: 'WelcomeEmail', subject: 'Welcome!', to: 'user@example.com', from: { name: 'App', address: 'noreply@app.com' }, template: 'welcome', // looks for welcome.stx or welcome.html handle: async () => ({ message: 'sent' }), onError: async (err) => ({ message: err.message }), onSuccess: () => console.log('Sent!') }) const html = await email.renderTemplate() await email.send() await email.send('override@email.com') ``` ## Template Rendering ```typescript import { template, renderHtml, templateExists, listTemplates } from '@stacksjs/email' const { html, text } = await template('welcome', { variables: { name: 'John', url: 'https://app.com' }, layout: 'default', // or false to skip layout subject: 'Welcome' }) // Raw HTML rendering const { html, text } = renderHtml('<h1>Hello {{name}}</h1>', { name: 'World' }) templateExists('welcome') // boolean listTemplates() // string[] ``` Variable interpolation uses `{{ variable }}` syntax. Templates can be `.stx` (processed by STX engine) or `.html`. ## EmailSDK (Inbox Management via S3) ```typescript import { emailSDK, sendEmail, getInbox, searchEmails, deleteEmail } from '@stacksjs/email' // Send await sendEmail({ from: { address: 'a@b.com' }, to: 'c@d.com', subject: 'Hi', html: '<p>Hello</p>' }) // Send with template await emailSDK.sendTemplate({ to: 'user@example.com', templateName: 'welcome', data: { name: 'John' } }) // Read inbox (from S3) const emails = await getInbox('chris', { limit: 20 }) const email = await emailSDK.getEmail('chris', messageId) // Search const results = await searchEmails('chris', { from: 'boss', after: '2024-01-01', hasAttachments: true }) // Manage await emailSDK.markAsRead('chris', messageId) await emailSDK.markAsUnread('chris', messageId) await deleteEmail('chris', messageId) ``` ## Built-in Drivers ### SES Driver - Uses the `SESClient` from `@stacksjs/ts-cloud` - Lazy-loads client on first send - Supports `Source` formatting: `"Name" <address>` ### SendGrid Driver - API key from config/env - Multipart content (HTML + text) - Attachment support (base64 encoding) - Retry with exponential backoff ### Mailgun Driver - FormData construction with recipients - CC/BCC support - Attachment handling via FormData - Configurable domain and endpoint ### Mailtrap Driver - Inbox-aware sending - Sandbox and production modes - Host default: `sandbox.api.mailtrap.io` ### SMTP Driver - Raw TCP/TLS socket connection - STARTTLS upgrade support - AUTH LOGIN authentication - MIME multipart (text + HTML) - 30-second connection timeout - Command queue-based protocol ## Environment-backed configuration The source of truth for dashboard mail settings is `.env`: - Common: `MAIL_MAILER`, `MAIL_FROM_NAME`, `MAIL_FROM_ADDRESS` - SMTP: `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_ENCRYPTION` - SES: `AWS_SES_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` - SendGrid: `SENDGRID_API_KEY` - Mailgun: `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_ENDPOINT` - Mailtrap: `MAILTRAP_HOST`, `MAILTRAP_TOKEN`, `MAILTRAP_INBOX_ID` The dashboard endpoints are `GET` and `PUT` at `/api/dashboard/mail-settings`. They are guarded outside local development, return no stored secret values, preserve a secret when its input is blank, and require an explicit clear flag to remove one. Writes use the shared atomic environment-file service, create a machine-local backup under `storage/framework/runtime/dashboard/`, and reject stale revisions instead of overwriting concurrent edits. ## Driver Interface ```typescript abstract class BaseEmailDriver { abstract name: string abstract send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult> protected validateMessage(message): boolean protected formatAddresses(...): string[] protected handleError(error, message): Promise<EmailResult> protected handleSuccess(message, messageId?): Promise<EmailResult> } ``` ## config/email.ts ```typescript { from: { name: env.MAIL_FROM_NAME, address: env.MAIL_FROM_ADDRESS }, domain: 'stacksjs.com', mailboxes: ['chris', 'blake', 'glenn'], url: env.APP_URL, charset: 'UTF-8', default: 'ses', // 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp' | 'log' | 'capture' server: { enabled: true, scan: { enabled: true }, subdomain: 'mail', mode: 'server', // 'server' | 'serverless' ports: { smtp: 25, smtps: 465, submission: 587, imap: 143, imaps: 993 }, features: { imap: true, pop3: false, webmail: false, calDAV: false }, categorization: { enabled: true, social: { domains: ['facebook', 'twitter', ...] }, forums: { domains: ['reddit', ...] }, updates: { substrings: ['noreply', 'no-reply', ...] }, promotions: { substrings: ['unsubscribe', 'promo', ...] } } }, notifications: { newEmail: true, bounces: true, complaints: true } } ``` ## Application Mail Example ```typescript // app/Mail/SubscriptionConfirmation.ts export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Options) { const { html, text } = await template('subscription-confirmation', { variables: { unsubscribeUrl: url('email.unsubscribe', { token: subscriberUuid }), appName: config.app.name } }) await mail.send({ from: { name: config.app.name, address: config.email.from.address }, to, subject: 'Confirm your subscription', html, text }) } ``` ## CLI Commands - `buddy email` / `buddy mail` — email management - `buddy email:verify` — check domain verification - `buddy email:test [recipient]` — send test email - `buddy email:list` — list mailboxes - `buddy email:logs -n 50` — view logs - `buddy email:status` — server status - `buddy email:inbox [mailbox]` — view inbox from S3 - `buddy mail:user:add <email>` — add mail user - `buddy mail:user:list` — list mail users - `buddy mail:user:delete <email>` — delete mail user ## Gotchas - Default driver is `ses` — requires AWS credentials - Template rendering supports both `.stx` and `.html` files - Variable interpolation uses `{{ }}` double-brace syntax - The `mail` singleton auto-registers all 5 drivers on initialization - SMTP driver handles TLS handshake manually (not via node:tls) - SendGrid/Mailgun retry with exponential backoff on failure - Mailtrap requires `inboxId` for sandbox mode - EmailSDK reads inbox from S3 (bucket configured via env) - Email categorization auto-sorts incoming mail by domain/substring patterns - The `text` fallback is auto-generated from HTML via `htmlToText()`