stacks-email

name	stacks-email
description	Use when working with email in a Stacks application — sending emails via SES/SendGrid/Mailgun/Mailtrap/SMTP, email templates with STX, email drivers, the Mail singleton, the EmailSDK for inbox management, or email configuration. Covers @stacksjs/email, config/email.ts, and app/Mail/.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

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

import { mail } from '@stacksjs/email'

await mail.send({
  from: { name: 'App', address: '[e-mail]' },
  to: '[e-mail]',
  subject: 'Welcome',
  html: '<h1>Hello!</h1>',
  text: 'Hello!'
})

// Switch driver
const sendgridMail = mail.use('sendgrid')
await sendgridMail.send(message)

Email Class

const email = new Email({
  name: 'WelcomeEmail',
  subject: 'Welcome!',
  to: '[e-mail]',
  from: { name: 'App', address: '[e-mail]' },
  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('[e-mail]')

Template Rendering

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)

import { emailSDK, sendEmail, getInbox, searchEmails, deleteEmail } from '@stacksjs/email'

// Send
await sendEmail({ from: { address: '[e-mail]' }, to: '[e-mail]', subject: 'Hi', html: '<p>Hello</p>' })

// Send with template
await emailSDK.sendTemplate({ to: '[e-mail]', 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.(, messageId)
 (, 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

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

{
  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', , ...] },
      : { : [, ...] },
      : { : [, , ...] },
      : { : [, , ...] }
    }
  },
  : { : , : , :  }
}

Application Mail Example

// 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()