Send transactional email, preview templates, manage the queue, and open the Mailpit dev inbox.
# Open the Mailpit web UI (dev only — catches all outbound mail)
nself mail dev
# List available email templates
nself mail list-templates
# Send a test email using the welcome template
nself mail send welcome --to you@example.com
# Check queue status
nself mail queue statusnself mail <SUBCOMMAND> [FLAGS]nself mail manages the transactional email layer. In development it routes all outbound mail through Mailpit — a local SMTP catcher with a browser UI — so real addresses are never hit during testing. In staging and production it hands off to the configured mail provider via the optional mail service or thetransactional-email plugin (P98).
Templates live in backend/mail/templates/ as Handlebars files. Each template renders to both HTML and plain-text parts. The preview subcommand opens a rendered HTML preview in your browser before you send.
Render a template and deliver it immediately through the configured mail service.
| Flag | Type | Required | Description |
|---|---|---|---|
--to | string | Yes | Recipient address(es), comma-separated |
--from | string | No | Sender address (defaults to MAIL_FROM env var) |
--subject | string | No | Override the template's default subject line |
--var | key=value | No | Template variable (repeatable). Example: --var name=Alice |
--dry-run | bool | No | Render the template and print output; do not send |
nself mail send welcome --to alice@example.com --var name=Alice
nself mail send password-reset --to user@example.com --var reset_url=https://...
nself mail send invoice --to billing@example.com --var amount=49.99 --dry-runList all available email templates with their file paths and required variables.
nself mail list-templates
# TEMPLATE PATH VARS
# welcome mail/templates/welcome.hbs name, login_url
# password-reset mail/templates/password-reset.hbs reset_url, expires_in
# invoice mail/templates/invoice.hbs amount, invoice_id, items[]Inspect and manage the outbound email queue. The queue is backed by the Redis-based BullMQ worker when the transactional-email plugin is installed; otherwise it is synchronous.
| Sub-action | Description |
|---|---|
queue status | Print queue depth, failed count, and worker state |
queue list | Show recent jobs with status and recipient |
queue retry <JOB_ID> | Re-enqueue a failed job |
queue clear | Remove all failed jobs from the queue (requires --confirm) |
nself mail queue status
# Queue: mail
# Waiting: 0 Active: 1 Failed: 3 Completed: 842
nself mail queue list --status failed
nself mail queue retry job_1a2b3c4d
nself mail queue clear --confirmRender a template with optional variables and open the HTML result in your default browser. Nothing is sent.
nself mail preview welcome --var name="Alice Smith"
nself mail preview invoice --var amount=99.99 --var invoice_id=INV-001Open the Mailpit web UI in your browser. Mailpit catches all outbound mail in dev and displays it as an inbox you can inspect, forward, or delete. Available in development environments only.
nself mail dev
# → Opening http://localhost:8025 in your browser| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Output results as JSON (list-templates, queue list, queue status) |
--env | string | current env | Target environment: dev, staging, prod |
nself mail send welcome --to test@example.com --var name="Test User" --dry-runnself mail queue list --status failed --json | jq -r '.[].id' | xargs -I{} nself mail queue retry {}nself mail preview newsletter --var title="May Update" --var month=MayMAIL_FROM — default sender address (e.g. noreply@yourdomain.com)MAIL_PROVIDER — provider for staging/prod: smtp, sendgrid, mailgun, ses, elasticSMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS — SMTP credentials (provider: smtp)MAILPIT_PORT — Mailpit web UI port in dev (default: 8025)0 — success1 — send failure or template not found2 — invalid arguments3 — mail service not enabled (ENABLE_MAIL=true required)transactional-email plugin for queue support