Skip to content

Home

Jump to bottom
Copilot edited this page Jul 11, 2026 · 2 revisions

nmailx Wiki

nmailx is a serverless outbound-email relay for statically hosted sites, plus a server-rendered admin dashboard. Drop a small JS snippet into a contact/quote form on any static site (GitHub Pages, S3, wherever), and nmailx turns submissions into real emails via AWS SES.

This wiki goes deeper than the README on setup, architecture, and day-2 operations. If you just want to get started quickly, the README's Quick Start is still the fastest path - come here when you need more detail on a specific topic.

Pages in this wiki

Page What it covers
Architecture Request flow, both Lambdas, the shared layer, the 5 DynamoDB tables
Installation and Quick Start Prerequisites, first deploy, bootstrapping an admin user, common setup issues
Configuration Reference Every template.yaml parameter, in depth
Custom Domain Setup Serving /send and /admin from your own hostname (e.g. app.nmailx.com)
GitHub Pages and DNS How this project's own landing page (www.nmailx.com) is hosted and wired up in Cloudflare
Local Development and Testing Makefile targets, pytest layout, moto fixtures, linting
Teardown Deleting every piece of infrastructure this project creates, in the right order
Vendored Assets The admin dashboard's vendored frontend libraries and how to update them

At a glance

  • Serverless: 2 Lambda functions, 5 DynamoDB tables, 1 API Gateway HTTP API. No EC2, no containers in production.
  • Cheap: comfortably under $10/month at 500+ emails/day (mostly SES's $0.10 per 1,000 emails).
  • Secure by default: Origin-derived domain resolution (never client-supplied), Cloudflare Turnstile spam protection, atomic rate limiting, sandboxed Jinja2 templates, argon2id + JWT admin auth, CSRF protection, least-privilege IAM per function.
  • Self-contained UI: HTMX + Bootstrap 5.3.8, all vendored - no CDN dependency for the dashboard itself.
  • One-command deploy: make deploy (AWS SAM under the hood - real CloudFormation, not a bespoke deploy script).
  • Fully torn down on request: every piece of infrastructure this creates can be deleted just as easily as it was created - see Teardown.

For contributor-facing conventions and invariants (things an AI agent or a new contributor should know before touching the code), see AGENTS.md in the repo itself.

Clone this wiki locally