Airpost
Web client and gateway

Pairing browsers

Pair a browser with the gateway using a one-time code, and list, rename or revoke paired devices.

The gateway lets in only browsers you pair. You print a one-time code on the machine running the gateway, open the link on the device, and the browser gets a cookie that identifies it from then on.

Pair a browser

docker compose exec gateway airpost-gateway pair            # mail only
docker compose exec gateway airpost-gateway pair --admin    # also accounts and settings

It prints a code and a <public URL>/pair#<code> link. Open the link on the device, or open the web client and enter the code. Each code works once.

OptionDefault
--adminoffGrants the admin scope (below)
--name <device>the browser’s nameThe device’s name in devices list, up to 64 characters
--ttl <time>10mHow long the code stays valid: 90s, 10m, 1h. At most 1h.
--jsonoffPrint the result as JSON (airpost-gateway pair only)

You can pair while the gateway is stopped; it reads the new code when it starts.

Scopes

A device paired without --admin gets mail reads, triage and drafts. A device paired with --admin can also use account, secret and engine methods, such as adding an IMAP account in Settings > Accounts. Pair only devices you control with --admin.

How long a device stays paired

The browser holds an HttpOnly, SameSite=Strict cookie, refreshed each time it opens a session. Over HTTPS it’s a __Host- cookie marked Secure. The gateway stores only hashes of the codes and tokens, in <profile>/gateway/devices.json.

A device unused for 180 days is dropped. An admin device is dropped after 30 days unused.

Several devices

Pair each device separately, with its own code. Give it a name you will recognize later:

airpost-gateway pair --name "Work laptop"
airpost-gateway pair --name "Phone"
airpost-gateway pair --admin --name "Home desktop" --ttl 5m

All devices see the same profile’s mail. A useful pattern is one --admin device you keep at home and mail-only devices everywhere else. To give a device admin later, revoke it and pair it again with --admin.

To share Airpost with someone else, don’t pair their browser with your gateway: they would read your mail. Give them their own profile (Users and devices).

List, rename and revoke

airpost-gateway devices list [--json]
airpost-gateway devices rename <id> <name>
airpost-gateway devices revoke <id>

On a server, prefix them with docker compose exec gateway. Revoking a device takes effect at once: the running gateway closes that device’s open sessions.

If you lose a device, revoke it. If you think a code leaked before it was used, let it expire, or revoke the device it paired.

To unpair every device, revoke each id from devices list. Codes that were printed but never used expire on their own.

Troubleshooting

SymptomCause
The code is refusedIt was already used or expired. The gateway logs pairing refused: unknown or expired code.
Too many attempts. Wait a minute.More than 5 tries a minute from one address. Behind a proxy, check AIRPOST_TRUSTED_PROXIES (Security).
The browser shows This browser was unpaired.The device was revoked or expired (180 days unused, 30 for admin). Pair it again.
Paired, but the session drops on every visitThe browser is blocking the cookie, or you’re switching between two hostnames. The cookie is tied to the public URL’s host.