Postlane

Postlane is a full-stack mail application inspired by modern webmail workflows. It includes a Next.js frontend, a FastAPI backend, threaded mailbox views, inbound SMTP ingestion, Redis-backed runtime services, and an admin surface for operational visibility.

Highlights

• Threaded inbox, sent, archive, spam, and trash flows
• Local inbound SMTP listener for testing real email delivery into user mailboxes
• Redis integration for runtime coordination and event-related infrastructure
• Postgres persistence for users, threads, messages, labels, drafts, and settings
• NextAuth-based frontend authentication and FastAPI JWT-backed backend flows
• Admin dashboard and mailbox insights
• Docker Compose stack with Traefik, frontend, backend, Postgres, Redis, OTEL Collector, Jaeger, Prometheus, Grafana, and Redis Commander

Flow

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Tech Stack

• Frontend: Next.js, TypeScript, React, Tailwind CSS
• backend: FastAPI, SQLAlchemy asyncio, Pydantic
• Database: PostgreSQL
• Cache and coordination: Redis
• Auth: NextAuth on the frontend, JWT on the backend
• Tooling: pnpm, uv, Docker Compose

Architecture

The app runs behind a single Traefik entrypoint:

• / and /api/auth/* route to the Next.js frontend
• /api/v1/* route to the FastAPI backend
• SMTP mail is accepted on localhost:2525
• OTEL traces and metrics flow through the OpenTelemetry Collector
• Jaeger is exposed on http://localhost:16686
• Grafana is exposed on http://localhost:3001
• Prometheus is exposed on http://localhost:9090
• Redis Commander is exposed on http://localhost:8081

Core services in Docker:

• frontend: Postlane web app
• backend: FastAPI API and SMTP listener
• postgres: primary relational store
• redis: cache and runtime coordination
• otel-collector: OTLP ingestion and telemetry export pipeline
• jaeger: distributed tracing UI
• prometheus: metrics scraping and query engine
• grafana: dashboards for metrics and traces
• redis-commander: Redis inspection dashboard
• traefik: public reverse proxy

Quick Start

Prerequisites

• Docker and Docker Compose
• make

Setup

1. Copy .env.example to .env
2. Update secrets if needed
3. Start the stack:

make start-build

Local URLs

• App: http://localhost:59998
• backend API: http://localhost:59998/api/v1
• SMTP test port: localhost:2525
• Grafana: http://localhost:3001
• Jaeger: http://localhost:16686
• Prometheus: http://localhost:9090
• Redis board: http://localhost:8081

Demo Login

• Email: admin@example.com
• Password: ChangeMe123!

Makefile Commands

Run these from the repo root:

• make start starts the Docker stack
• make start-build rebuilds images and starts the stack
• make stop stops the stack
• make stop-clean stops the stack and removes volumes
• make logs tails service logs
• make ps shows running services
• make send-dummy-mail sends a canned inbound email to the demo account
• make send-test-mail MAIL_TO=noah@example.com MAIL_SUBJECT="Hello" sends a custom inbound email
• make redis-board prints the Redis Commander URL
• make observability prints Grafana, Jaeger, Prometheus, and Redis URLs

SMTP Testing

Postlane includes a local SMTP listener for end-to-end inbound mail testing.

Default SMTP settings:

• Host: localhost
• Port: 2525
• Auth: none

Quick test:

make send-dummy-mail

Custom test:

make send-test-mail MAIL_TO=admin@example.com MAIL_SUBJECT="Postlane SMTP Test"

You can also use the Python helper directly:

uv run python backend/scripts/send_test_smtp.py --to admin@example.com

Detailed instructions are available in SMTP_TESTING.md.

Redis Monitoring

Postlane now includes Redis Commander for inspecting Redis content and activity.

Use it to:

• Browse keys
• Inspect values
• Verify TTLs
• Check what the application is storing in Redis during runtime

Open the dashboard at http://localhost:8081.

Observability

Postlane now includes a local observability stack built around OpenTelemetry.

Included components:

• OpenTelemetry instrumentation in the FastAPI backend
• SQLAlchemy and Redis tracing
• Manual tracing around SMTP ingestion and event publishing workflows
• OTEL Collector for telemetry ingestion and routing
• Jaeger for trace exploration
• Prometheus for metrics collection
• Grafana with preconfigured Prometheus and Jaeger data sources
• Provisioned Grafana dashboard for Postlane mail-processing and telemetry metrics

What you can inspect:

• API request traces
• Database and Redis spans
• SMTP message processing spans
• Event dispatcher activity
• Custom mail-processing metrics exported from the backend

Observability URLs:

• Grafana: http://localhost:3001
• Jaeger: http://localhost:16686
• Prometheus: http://localhost:9090

Grafana opens with a provisioned Postlane Observability dashboard that tracks SMTP volume, event publishing, collector intake, and mail-processing latency.

Local Development Without Docker

backend

cd backend
uv sync
uv run python scripts/export_openapi.py
uv run backend

Frontend

cd frontend
pnpm install
pnpm generate:api
pnpm dev

For local non-Docker development, you still need running Postgres and Redis instances.

Project Structure

• backend: FastAPI service, SMTP ingestion, API routes, and infrastructure code
• frontend: Next.js app, auth flows, mailbox UI, and admin UI
• docker-compose.yml: full local stack definition
• Makefile: common local workflow commands
• SMTP_TESTING.md: inbound SMTP usage guide
• ops: OTEL Collector, Prometheus, and Grafana provisioning

Notes

• Schema bootstrap currently happens on application startup
• No migration files are committed yet
• If you already have an older local Docker volume, recreate it after pulling schema-related changes
• The generated frontend API types depend on backend/openapi.json

Roadmap Ideas

• Add database migrations
• Add outbound email provider integration
• Add background worker metrics and queue visibility

Contributing

Contributions are welcome.

If you want to contribute:

• open an issue for bugs, ideas, or architecture discussions
• fork the repository and open a PR
• keep PRs focused and clearly described
• update documentation when behavior changes

Please read CONTRIBUTING.md before opening a pull request.

License

This repository is distributed under a custom non-commercial source-available license.

Key rules:

• personal, educational, research, and non-commercial use is allowed
• commercial use is not allowed without prior written permission
• attribution to Ankur Jaiswal, ankurjaiswalofficial@gmail.com, and https://github.com/ankurjaiswalofficial must be preserved as described in the license

Read the full license here: LICENSE