📬 email-api

Your app shouldn't need to know anything about SMTP. It should just call a REST endpoint.

email-api is a self-hosted service that wraps Nodemailer behind a clean HTTP API — with attachments, CC/BCC, HTML bodies, per-sender templates, scheduled delivery, and automatic retry baked in. Run it once, call it from anywhere, and manage everything from a rich terminal dashboard.

☝️ 37 tests across REST routes, auth middleware, scheduler, validator, and template renderer. All green.

The problem it solves

Adding email to a service means choosing an SDK, wiring credentials into every service that needs it, and reinventing retry logic each time. email-api pulls that concern out of your app entirely. Every service in your stack calls one endpoint. Credentials live in one place. History is isolated per API key.

Install

npm install -g @aks-builds/email-api

Requires Node.js ≥ 22.5 (uses the built-in node:sqlite module).

email-send — quick send CLI

One command to send an email from your terminal. Catppuccin Mocha UI, Gmail REST API over HTTPS, attachments, multi-recipient, $EDITOR body input. Works in cmd.exe, PowerShell, and bash.

☝️ Real Catppuccin Mocha UI. Gmail credentials saved once to ~/.email-api/config.json — every subsequent run goes straight to COMPOSE.

# Install once
npm install -g @aks-builds/email-api

# Run anywhere — cmd.exe, PowerShell, or bash
email-send

Quickstart

# Start the server — generates an API key on first run
email-api server

# ┌─────────────────────────────────────────────┐
# │  email-api: API key generated (save this!)  │
# │  a3f9c2...e81b                              │
# │  Set EMAIL_API_KEY in .env to pin it        │
# └─────────────────────────────────────────────┘
# email-api server running on http://localhost:3000

# Send an email
curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer <your-key>" \
  -F "[email protected]" \
  -F "subject=Hello" \
  -F "text=World"

# Open the TUI dashboard (separate terminal)
email-api tui

REST API

All routes except GET /health require Authorization: Bearer <key>. All error responses follow { "error": "CODE", "message": "...", "statusCode": N }.

Emails

POST   /emails          Send or schedule an email (multipart/form-data)
GET    /emails          List history for this key (?status=&page=&limit=)
GET    /emails/:id      Get a single email record + delivery status
DELETE /emails/:id      Cancel a scheduled email (pending only)

POST /emails fields:

| Field | Type | Required | |---|---|---| | to | string | comma-separated | yes | | cc | string | comma-separated | no | | bcc | string | comma-separated | no | | subject | string | yes | | text | string | at least one of text/html/template | | html | string | at least one of text/html/template | | template | string (template name) | no | | templateVars | JSON string | no | | scheduledAt | ISO 8601 datetime | no (omit = send immediately) | | attachments | File[] (multipart) | no — up to 10 × 25 MB |

Email status lifecycle:

pending → sending → sent
                 ↘ failed      (after 3 retries: 30s → 2m → 10m)
         → cancelled           (DELETE while pending)

Keys

POST   /keys            Create a named API key → returns raw key once
GET    /keys            List active keys (names + IDs, never raw values)
DELETE /keys/:id        Revoke a key

Health

GET    /health          Server status, active key count (no auth required)

Configuration

Set in .env or environment variables. Copy .env.example to get started.

# Auto-generated on first run if absent
EMAIL_API_KEY=

SERVER_PORT=3000

# SMTP — defaults to Brevo free tier (300 emails/day)
SMTP_HOST=smtp-relay.brevo.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-brevo-smtp-key
# RFC 5322 format: "Display Name <address@domain>" or just "address@domain"
SMTP_FROM=Your Name <[email protected]>

# Set to true to keep attachment files on disk after successful send
KEEP_ATTACHMENTS=false
# Runtime data directory (SQLite DB, config.json, attachments, templates)
DATA_DIR=./data

Any SMTP provider works — change SMTP_HOST/PORT/USER/PASS to point at Gmail, AWS SES, Mailgun, Resend, or a local relay.

Features

HTML emails

Pass html alongside text for a multipart/alternative message. If only html is provided, a plain-text fallback is auto-stripped.

Attachments

Up to 10 files, 25 MB each, 50 MB total per email. Stored under ./data/attachments/<emailId>/ and cleaned up after successful delivery (unless KEEP_ATTACHMENTS=true).

Templates

Store templates as ./data/templates/<name>.html and/or <name>.txt. Reference them with template=welcome and pass variables as templateVars={"name":"Alice"}. Variables use {{varName}} syntax.

curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer <key>" \
  -F "[email protected]" \
  -F "subject=Welcome!" \
  -F "template=welcome" \
  -F 'templateVars={"name":"Alice","link":"https://example.com/verify"}'

Scheduled sending

Pass scheduledAt as an ISO 8601 datetime. The scheduler picks it up within 30 seconds.

# Schedule for tomorrow morning
-F "scheduledAt=2026-06-15T09:00:00Z"

Retry on failure

Transient SMTP errors are retried up to 3 times with exponential backoff (30s → 2m → 10m). Permanent errors (5xx SMTP codes) fail immediately. Failure details are captured in last_error and surfaced in the TUI.

Per-key isolation

Every API key sees only its own email history. Create one key per service, rotate independently, revoke without affecting others.

TUI Dashboard

Press S to compose, L for logs, C for config, H for the dashboard, R to refresh, Q to quit.

┌─ email-api ──────────────────────────────────────────────────────────────┐
│  ✔ 47 sent  ✘ 2 failed  ⟳ 3 pending  ⏰ 5 scheduled  ● connected :3000  │
├─ Recent Emails ────────────────────────────┬─ Live Log ──────────────────┤
│  ✔ [email protected]  Quarterly Report        │ 14:22:01 sent → alice       │
│  ✔ [email protected]    Invoice #4421           │ 14:21:44 sent → bob         │
│  ✘ [email protected]  Welcome email [timeout] │ 14:20:11 failed → charlie   │
│  ⏰ [email protected]   Weekly Digest [9am]    │ 14:20:11 retry scheduled    │
│  ⟳ [email protected]   Password Reset [2/3]   │ 14:19:58 scheduler tick     │
├────────────────────────────────────────────┴─────────────────────────────┤
│  S Compose  L Logs  C Config  H Dashboard  R Refresh  Q Quit             │
└──────────────────────────────────────────────────────────────────────────┘

Multi-key example

# Create a key for your notifications service
curl -X POST http://localhost:3000/keys \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"notifications-svc"}'
# → { "id": "abc123", "name": "notifications-svc", "key": "..." }

# That service uses its own key — isolated history, independently revokable
curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer <notifications-svc-key>" \
  -F "[email protected]" \
  -F "subject=Your order shipped" \
  -F "text=Tracking: #9876"

Tech stack

| Concern | Package | |---|---| | HTTP server | express 4 | | SMTP | nodemailer 6 | | Database | node:sqlite (built-in) | | File uploads | multer 1 | | Scheduler | node-cron 3 | | TUI rendering | blessed | | ID generation | nanoid 5 | | Runtime | Node.js ≥ 22.5 ESM | | Test runner | node:test (built-in) |

Development

git clone https://github.com/aks-builds/email-api
cd email-api
npm install
npm test        # 37 tests, node:test built-in runner

# Or install globally
npm install -g @aks-builds/email-api

License

MIT © aks-builds