buzon is a CLI for a self-hosted cloudflare_temp_email instance, a mail server that runs on a Cloudflare Worker with D1. It creates addresses on your domain, waits for the verification code or magic link, and keeps a local record of which address belongs to which account.
- Three tiers in the address name:
stefor one code,mtefor a few weeks,ltefor a real account. The instance deletes expired ones by itself. wait --codeandwait --linkprint just the code or the link, ready for a script or an agent.- A local registry of every address with its site and note, so "which address did I use for GitHub?" has an answer.
- A first install in one command, then deploys and upgrades of the upstream release, with every database patch shown and confirmed.
- An agent skill that tells an AI agent when to pick each tier and how to get a code.
Public temp-mail services are blocked by most sign-up forms, and their inboxes are readable by anyone who guesses the name. A catch-all on your own domain avoids both, but turns into a pile of addresses nobody remembers. buzon puts a lifetime on each address, cleans up the short ones, and records the long ones.
With Bun:
bun add -g @shbernal/buzon
Or as a standalone binary, with no Bun needed, for linux-x64, linux-arm64, darwin-x64 or
darwin-arm64 from the latest release:
curl -fsSL https://github.com/shbernal/buzon/releases/latest/download/buzon-linux-x64.tar.gz | tar -xz -C ~/.local/bin
buzon reads its passwords from BUZON_SITE_PASSWORD and BUZON_ADMIN_PASSWORD, or else from
the keyring: the Secret Service through secret-tool on Linux, the Keychain on macOS.
No instance yet? docs/deploying.md goes from a domain on Cloudflare to a
running one, mostly through buzon init --deploy.
Store the instance's site password in the keyring, on Linux:
secret-tool store --label="buzon site-password" service buzon key site-password
On macOS:
security add-generic-password -s buzon -a site-password -w
Elsewhere, export BUZON_SITE_PASSWORD instead.
2.
Point buzon at the instance. It checks that the instance answers, serves the domain and accepts the password before writing anything:
buzon init --url https://mail.example.com --domain example.com
Create a one-shot address and use it on a sign-up form:
buzon new ste
Wait for the code, then delete the address:
buzon wait ste-2610-9qa --code --since 10m
buzon delete ste-2610-9qa
For an account you will come back to, keep the address and say what it is for:
buzon new lte --site github --note "GitHub account for side projects"
| Command | Does |
|---|---|
new <ste|mte|lte> |
Create an address, with --site and--note |
new custom <name> |
Create an address with a name you choose, such as jane |
wait <address> |
Wait for new mail and print its --code ,--link or text |
read <address> |
Print the latest mail, --all , or one--id |
list ,show <address> |
Registry entries, filtered by --tier or--site |
note ,delete ,adopt |
Edit, remove, or take in an address made elsewhere |
init --deploy |
First install: database, schema, secrets and release |
secrets push |
Put the passwords and the JWT secret on the Worker |
deploy ,upgrade ,export-db |
Ship a release, move to a newer one, dump the database |
Every command takes --json. buzon --help lists every command and flag.
skills/buzon teaches an agent to pick the tier, get a code or link,
and find an address again later. Install it with:
npx skills add shbernal/buzon
A test fails the build when the skill names a command or flag the CLI does not have.
Cloudflare Email Routing hands every message for your domain to the Worker, which stores it in D1.
A daily cron deletes expired ste and mte addresses by the tier in their name.
buzon talks to the Worker over its HTTPS API, and keeps the registry of sites and notes on your
machine only.