SMTP server (Twisted) listens on a non-privileged port (>1024) and accepts mail.
SMTP client (Twisted) relays received mail to Gmail SMTP (submission) via STARTTLS.
HTTP server (Twisted Web) serves a simple dashboard with:
- server stats (uptime, counters)
- list of relayed messages (recent first)
- per-message detail view

Install

python -m venv .venv
# Windows:
.venv\Scripts\python -m pip install -r requirements.txt
# Linux/macOS:
.venv/bin/python -m pip install -r requirements.txt

Configure (environment variables)

Required:

GMAIL_USERNAME
GMAIL_APP_PASSWORD
FORWARD_TO (comma-separated list)

Optional:

SMTP_LISTEN_HOST (default: 127.0.0.1)
SMTP_LISTEN_PORT (default: 2525, must be >1024)
HTTP_LISTEN_HOST (default: 127.0.0.1)
HTTP_LISTEN_PORT (default: 8080, must be >1024)
GMAIL_HOST (default: smtp.gmail.com)
GMAIL_PORT (default: 587)
RELAY_FROM (default: GMAIL_USERNAME)
ALLOW_ANY_RCPT (default: true) - if false, only accept RCPT that match FORWARD_TO.
ADD_X_HEADERS (default: true) - add X-Original-* headers.
MAX_STORE (default: 200) - max number of message records kept in memory.

Run

PowerShell:

$env:GMAIL_USERNAME="you@gmail.com"
$env:GMAIL_APP_PASSWORD="xxxx xxxx xxxx xxxx"
$env:FORWARD_TO="you@gmail.com"
$env:SMTP_LISTEN_PORT="2525"
$env:HTTP_LISTEN_PORT="8080"
.venv\Scripts\python -m smtp_relay.main

Open dashboard:

http://127.0.0.1:8080/

Send a test email (to your local relay)

python scripts/send_test_mail.py --host 127.0.0.1 --port 2525 --to you@gmail.com

Tests

python -m unittest -v

Security notes

This is intended for local / controlled networks. If you expose it publicly:

firewall/VPN it
authenticate clients
rate limit
set ALLOW_ANY_RCPT=false

Docker

Build and run with compose:

docker compose up --build

Then:

SMTP: localhost:2525
Dashboard: http://localhost:8080/

Provide env vars via your shell or a .env file:

GMAIL_USERNAME
GMAIL_APP_PASSWORD
FORWARD_TO