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 computer | On a server | |
|---|---|---|
| Works when | Your computer is on and awake | Always |
| TLS | Tailscale (below) or your own proxy | Caddy from the compose setup |
| Setup | This page | Always-on VPS, then step 4 here |
Prerequisites
airpostandairpost-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
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