Airpost
Self-hosting

Mail on your phone

Use the Airpost web client from your phone, served by the gateway on your computer or a server, and paired with a one-time code.

What you’ll build

Your phone’s browser opening the Airpost web client, reading and drafting mail from the same engine as your desktop, with the same rules, signatures and drafts. The gateway serves the web client; a TLS layer in front makes it reachable from the phone; a one-time pairing code lets the phone in.

There are two ways to host it:

On your computerOn a server
Works whenYour computer is on and awakeAlways
TLSTailscale (below) or your own proxyCaddy from the compose setup
SetupThis pageAlways-on VPS, then step 4 here

Prerequisites

  • airpost and airpost-gateway, with the built web client. See Install the CLI. The desktop app ships both.
  • An engine running on the same profile (the desktop app, or airpost engine install).
  • For the computer route: Tailscale on the computer and on the phone, with HTTPS certificates turned on for your tailnet. Any TLS proxy works instead; Tailscale is the one shown.

Install the gateway on your computer

airpost gateway install

It listens on 127.0.0.1:5180 and starts on the first connection. Check it from the computer itself by opening http://127.0.0.1:5180.

Put HTTPS in front with Tailscale

tailscale serve --bg 5180
tailscale serve status

tailscale serve status prints the address, something like https://laptop.tail1234.ts.net. Only devices on your tailnet can reach it, and the gateway itself stays on loopback.

Tell the gateway its public URL

The gateway checks every request’s Host against its public URL, so set it to the Tailscale address:

airpost gateway install --public-url https://laptop.tail1234.ts.net
airpost gateway restart

Pair the phone

On your computer
airpost gateway pair --name "Phone" --ttl 5m

It prints a code and a link:

Pairing code: <code>
Open https://laptop.tail1234.ts.net/pair#<code> within 5 min.

Open the link on the phone, or open the web client there and type the code. Pair without --admin: a phone doesn’t need to add accounts or change engine settings.

Add it to the home screen

In Safari, Share > Add to Home Screen; in Chrome on Android, Menu > Add to Home screen. On iOS a home screen web app can keep its own cookies apart from Safari’s; if it asks for a code, print a new one and pair from inside it.

Expected output

The phone shows your inbox. Mark a thread read on the phone and it’s read in the desktop app within a moment. On the computer:

airpost-gateway devices list

One line per device: its id, admin or -, the day it was paired, the day it was last used, and its name. --json prints {"devices": [{"id", "name", "scopes", "pairedAt", "lastUsedAt"}]}.

How it works

The gateway is a small HTTP and WebSocket server that serves the built web client and forwards its calls to the engine’s local socket. It only lets in paired browsers. Pairing exchanges the one-time code for an HttpOnly, SameSite=Strict cookie; over HTTPS it’s a Secure __Host- cookie. The gateway stores only hashes of codes and tokens, in <profile>/gateway/devices.json.

A device paired without --admin gets mail reads, triage and drafts. A device unused for 180 days is dropped (30 days for admin devices).

The gateway speaks plain HTTP and refuses a non-loopback http public URL unless you pass --insecure-public-url, so a phone always reaches it through TLS.

Variations

  • Your own domain on a home server. Put Caddy or nginx in front as in Your own reverse proxy and use --public-url https://mail.home.example.
  • From the desktop app. Preferences > General > Web access from this computer installs the gateway, and Pair a browser prints a code.
  • Several phones. Pair each one with its own --name, so you can revoke one without touching the others.

Cleanup

Revoke the phone; its open sessions close at once:

airpost-gateway devices revoke <id>

To remove the gateway entirely:

tailscale serve reset
airpost gateway uninstall