Email Relay

Some hosts — most famously DigitalOcean droplets, but also many other cloud providers — block outbound SMTP ports (25, 465, and 587) to cut down on spam. On those hosts Trusted Servants Pro can't reach your mail server directly, so password resets, access requests, contact-form notifications, and test emails all silently fail to deliver.

TS Pro Relay solves this. It's a tiny companion container you run somewhere that does have SMTP egress. Instead of talking SMTP itself, your portal POSTs each message as JSON to the relay over HTTPS, and the relay performs the actual SMTP delivery on its behalf.

TSP app  ──HTTPS──▶  TS Pro Relay  ──SMTP:587/465──▶  mail server
(no SMTP egress)     (companion)                      (Gmail, SES, …)

There are two big wins beyond just getting mail out:

• Your SMTP password never touches the portal. Credentials live only on the relay. The portal stores nothing but the relay's URL and an API key.
• The relay can run anywhere. Put it on a $4 VPS, a home server, or any box with port 587 open. The portal only needs to reach it over HTTPS.

This guide has four parts:

1. Stand up the relay container on a host with SMTP egress.
2. Put HTTPS in front of it with a reverse proxy.
3. Configure the relay's SMTP server and API key from its web interface.
4. Connect Trusted Servants Pro to the relay.

Before you begin

You'll need:

• A host with outbound SMTP access to run the relay on. This can be the same machine as your portal if that machine can reach your mail server — but the whole point is usually that it can't, so this is typically a second box: a small VPS on a provider that doesn't block SMTP, a home server, or similar.
• Docker and Docker Compose installed on that host.
• Your SMTP server details — host, port, security mode (STARTTLS / SSL / none), username, and password. These are the same credentials you'd put into any email client.
• A domain name you can point at the relay (e.g. relay.example.com) so it can be reached over HTTPS in production.

Part 1: Stand up the relay container

The relay ships as a published image on Docker Hub — viibeware/tspro-relay. You don't need to clone anything to run it; a docker-compose.yml and a .env are enough.

1.1 — Create a working directory

On the relay host:

mkdir tspro-relay && cd tspro-relay

Everything for the relay lives here: the compose file, your .env, and a ./data folder the container will create for its database.

1.2 — Create docker-compose.yml

Create a file named docker-compose.yml with the following contents:

services:
  relay:
    image: viibeware/tspro-relay:latest
    # The relay serves BOTH the admin UI and the JSON send API on one port.
    # In production you put a TLS-terminating reverse proxy in front (Part 2)
    # and point the TSP app at the https:// URL.
    ports:
      - "0.0.0.0:8026:8000"
    environment:
      # Signs admin sessions AND derives the at-rest encryption key for the
      # stored SMTP password + API key. REQUIRED — set a long random value.
      - RELAY_SECRET_KEY=${RELAY_SECRET_KEY:?set RELAY_SECRET_KEY in .env}
      # First-boot admin login (ignored once the admin row exists).
      - RELAY_ADMIN_USER=${RELAY_ADMIN_USER:-admin}
      - RELAY_ADMIN_PASSWORD=${RELAY_ADMIN_PASSWORD:-admin}
      - RELAY_LOG_LEVEL=${RELAY_LOG_LEVEL:-INFO}
      # Set to 1 ONLY for local HTTP testing without TLS.
      - RELAY_INSECURE_COOKIES=${RELAY_INSECURE_COOKIES:-}
    volumes:
      - ./data:/data        # relay.db (settings, admin, transaction log)
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=5).status==200 else 1)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

A few things worth understanding:

• The container listens on port 8000 inside, published to 8026 on the host. The relay serves both its admin web interface and the JSON send API on this single port.
• The ./data volume holds relay.db — a SQLite database with the relay's settings, the admin account, and the transaction log. Back this folder up the same way you'd back up any data directory.
• The healthcheck lets Docker (and any orchestrator) know when the relay is ready and stays alive.

1.3 — Create the .env file

The one value you must set is RELAY_SECRET_KEY. It signs the admin login session and derives the key that encrypts the stored SMTP password and API key at rest. Generate a strong, random value:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Then create a file named .env next to your compose file:

# Signs login sessions AND encrypts the stored SMTP password + API key.
# REQUIRED — paste the output of the command above.
RELAY_SECRET_KEY=replace-with-a-long-random-value

# First-boot admin login. Used only to create the initial admin account;
# change the password from the UI afterwards (these are then ignored).
RELAY_ADMIN_USER=admin
RELAY_ADMIN_PASSWORD=change-me-on-first-login

1.4 — Start the relay

docker compose up -d

Confirm it's running and healthy:

docker compose ps

The relay's UI and API are now reachable on port 8026 of the host. From a browser on the same network, open http://<relay-host>:8026 — you should see the relay's login page. Sign in with the RELAY_ADMIN_USER / RELAY_ADMIN_PASSWORD you set above.

Part 2: Put HTTPS in front of the relay

Your portal authenticates to the relay with a Bearer API key, and you log into the relay's web interface with a session cookie. Neither should ever travel over plaintext HTTP. The standard fix is a reverse proxy that terminates TLS and forwards to the relay on 127.0.0.1:8026.

Point a DNS record — e.g. relay.example.com — at the relay host first, then pick one of the following.

Option A — Caddy (automatic HTTPS)

Caddy fetches and renews a Let's Encrypt certificate for you with zero extra config. In your Caddyfile:

relay.example.com {
    reverse_proxy 127.0.0.1:8026
}

Reload Caddy and you're done — https://relay.example.com now serves the relay with a valid certificate.

Option B — nginx

If you already run nginx (with certificates from Certbot or similar), add a location block to the server that handles relay.example.com:

location / {
    proxy_pass http://127.0.0.1:8026;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
}

Your relay is now reachable at https://relay.example.com. That HTTPS URL is what you'll give the portal in Part 4.

Part 3: Configure the relay's SMTP server and API key

Open the relay's web interface — https://relay.example.com in production — and sign in. Go to the Settings page. Everything in this part is done in the UI; there are no JSON or env files to edit.

3.1 — Change the admin password

If you're still on the seeded change-me-on-first-login password, change it now under Admin account (username, current password, new password). The first-boot .env credentials are ignored once the admin row exists, so this is your real login from here on.

3.2 — Enter your SMTP server

In the SMTP delivery card, fill in your mail server details:

Click Save SMTP settings.

3.3 — Copy the API key

In the API key card you'll find the shared secret your portal will send as a Bearer token. Click Reveal, then Copy — you'll paste it into the portal in Part 4. (You can Generate new key at any time, but doing so stops the portal from sending until you update its stored key to match.)

3.4 — Send a test from the relay itself

Before involving the portal, prove the relay can talk to your mail server. In the Send a test email card, enter a recipient address and click Send test. The result is recorded in the relay's Transaction Log (the Logs page), along with the SMTP status and any error.

• ✅ Delivered? Your SMTP settings are correct — move on to Part 4.
• ❌ Failed? The log shows the SMTP error. Common causes are a wrong password, the wrong port/security combination, or — if even the relay can't reach the mail server — the relay host also blocking outbound SMTP. (Run the relay somewhere that doesn't.)

Part 4: Connect Trusted Servants Pro to the relay

Now switch over to your portal's admin interface. Open Settings and select the Domain / Email tab.

1. Sending method → choose API relay (HTTPS). Extra fields appear for the relay connection. (The default is Direct SMTP; switching to the relay is what routes mail through your new container.)
2. Relay URL → the HTTPS address of your relay, e.g. https://relay.example.com. No trailing path is needed — just the base URL.
3. Relay API key → paste the key you copied from the relay's Settings page in step 3.3. (Leave this blank on later edits to keep the existing key; the portal stores it encrypted, the same way the relay does.)
4. From email / From name → your sender identity. These apply in both transports, so the sender doesn't change when you switch to the relay.
5. Click Save Email Settings.

Send the end-to-end test

Still on the Domain / Email tab, use Send Test: enter a recipient and send. This exercises the whole path — portal → HTTPS → relay → SMTP → mailbox.

Then confirm it from the relay side: open the relay's Transaction Log. A successful test appears there with the sender, recipient(s), subject, and a sent status. Seeing the message in that log is proof the portal reached the relay and the relay delivered it.

Once the test arrives, you're done — every email the portal sends (password resets, access requests, contact-form notifications, recovery-contact messages) now flows through the relay.

How it works under the hood

When the portal sends a message in relay mode, it POSTs JSON to the relay's POST /api/send endpoint with the API key as a Authorization: Bearer <key> header. The body carries the sender, recipients, subject, plain-text and optional HTML bodies, an optional reply-to, and any attachments (base64-encoded). The relay validates the key, checks the From against its allowlist, enforces the attachment-size limit, performs the SMTP delivery, and logs the result. You don't have to call this API yourself — the portal does it for you — but it's handy to know when reading the transaction log.

The relay also exposes an unauthenticated GET /healthz liveness probe (used by the Docker healthcheck) that reports whether SMTP and an API key are configured, without leaking any secrets.

Troubleshooting

Security notes

• Always run the relay behind TLS in production. The Bearer key and login cookie must never cross plaintext.
• Change the seeded admin password immediately (Part 3.1).
• Keep RELAY_SECRET_KEY long, random, and stable — rotating it invalidates the stored SMTP password and API key.
• Use the Allowed From list so a leaked key can't spoof arbitrary senders.
• Back up the relay's ./data folder along with your portal data; it holds the encrypted SMTP credentials and the transaction log.

Next steps

• Configuration & Security — environment variables and how the portal encrypts its own stored credentials.
• Backup & Restore — protect your portal's data.
• Installation — the full portal deployment guide.