Envelope

📧 Envelope U+1F4E7 — if you know, you know. One inbox for all your email accounts, shared with your agents.

Why U1F4E7? It's the Unicode codepoint for 📧. Humans see a repo name. Agents see an envelope.

Setup • Travel • CLI • Rules • MCP • Agent plugins • vs. Alternatives • Dashboard • Commercial licensing • License

---

Envelope connects to the email accounts you already have (Gmail, Fastmail, iCloud, your own domain, any IMAP server) and puts them in one place. Open the Unified Inbox in your browser to read every account together, search them all at once, and archive or snooze across accounts in one pass. Your agents work the same mailboxes from the CLI, with JSON output, or over MCP, and anything they draft waits for your approval.

You don't change DNS, set up a new domain, or pay per-message fees. Add each address with its app password and go.

envelope accounts add --email you@gmail.com

envelope accounts add --email you@work.example envelope serve # every account in one inbox at http://localhost:3141 envelope inbox --account you@work.example --json # the same mail, for your agent

Install

# macOS or Linux: downloads the release binary for your OS and CPU, checks it

against the release's SHA-256 file, and installs it to ~/.local/bin (no sudo).

curl -fsSL https://u1f4e7.com/install.sh | bash

Homebrew (macOS or Linux) installs the same release binary.

brew install tymrtn/u1f4e7/envelope

tymrtn/u1f4e7/u1f4e7 is a live compat alias for the same formula.

To build it yourself instead:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && source "$HOME/.cargo/env"

git clone https://github.com/tymrtn/U1F4E7 cd U1F4E7 cargo build --release

Add --features governor to build in the Governor send gate (see below).

cp target/release/envelope ~/.local/bin/envelope

The release workflow signs and notarizes the macOS binaries once its Apple credentials are configured (docs/release-signing.md); until then macOS release binaries are unsigned. If macOS refuses to run an unsigned tarball you downloaded in a browser, clear the quarantine flag: xattr -d com.apple.quarantine ~/.local/bin/envelope.

Quick start

Envelope signs in to IMAP and SMTP with a password or an app password, and to Gmail with Google sign-in. That decides which mailboxes work today:

• Fastmail and iCloud Mail: create an app password in the provider's security settings.
• Gmail: envelope accounts add --provider google --email you@gmail.com signs in with Google in your browser; envelope accounts reauth you@gmail.com --provider google switches an account added with a password. While Envelope's Google app is in Google's testing stage, only addresses on its test-user list can sign in, and Google asks again every 7 days. An app password still works for accounts that can create one. From another device, add --paste (automatic over SSH), or run --paste --no-wait now and --finish - within 24 hours.
• Migadu, self-hosted Dovecot, and most other IMAP hosts: your normal mailbox password.
• Proton Mail: through Proton Mail Bridge, which needs a paid Proton plan. See Proton Mail for the setup.
• Outlook.com, Hotmail, Live, and Microsoft 365: not supported yet. Microsoft turned off password sign-in for IMAP on Outlook.com accounts and Exchange Online, so an app password does not help.

Envelope encrypts saved credentials with a passphrase. In a terminal it asks you for one. Scripts, agents, and the piped command below have no terminal to ask from, so give Envelope a passphrase file first:

# Create a random passphrase readable only by you, and point Envelope at it.

Add the export line to your shell profile, and back the file up: without it

the saved credentials cannot be decrypted.

(umask 077 && openssl rand -base64 32 > "$HOME/.envelope-passphrase") export ENVELOPE_MASTER_PASSPHRASE_FILE="$HOME/.envelope-passphrase"

Add an account. Envelope finds the IMAP/SMTP servers from the email domain

and logs in before saving; a rejected login fails here and prints what to fix.

(--skip-login-check saves without logging in, for offline setup.)

printf '%s\n' "$APP_PASSWORD" | envelope accounts add --email you@fastmail.com --password-stdin

Verify setup end-to-end (paths → account → IMAP auth → inbox peek)

envelope quickstart

See folders with unread counts

envelope folders

Read the inbox

envelope inbox --limit 20

Read a message (does not mark it as read)

envelope read 42

Send with attachment

envelope send --to someone@example.com --subject "Report" --body "Attached." --attach report.pdf

Reply in-thread as a reviewable draft

envelope draft reply 42 --body "Thanks."

Snooze until Monday

envelope snooze set 42 --until monday --reason waiting-reply

Watch for new mail in real time (IMAP IDLE push)

envelope watch --json

Retrieve a verification-code JSON result for unattended automation (bounded and fail-closed)

envelope --json code --account you@example.com --from otp@issuer.example --wait 60

Schedule a send for business hours

envelope send --to cto@example.com --subject "Report" --body "..." --at "monday 9am"

Import contacts from your inbox, then create a contact-based rule

envelope contacts import --from-inbox envelope rule create --name "VIP" --match-contact-tag vip --action flag=\\Flagged

Agent scores a message, creates a rule, Envelope enforces it forever

envelope tag set 42 --score urgent=0.1 --tag newsletter envelope rule create --name "Junk newsletters" --match-tag newsletter --match-score-below interesting=0.3 --action move=Junk envelope rule run --confirm

Unsubscribe from a mailing list (dry-run by default)

envelope unsubscribe 99

Open the local dashboard at http://localhost:3141 (loopback, no auth — single-user local trust)

envelope serve

Expose it to agents/devices on your tailnet — REQUIRES auth first.

Option A (humans): allowlist tailnet identities; tailscale serve proves them.

envelope config set dashboard.tailscale_allow "you@your-tailnet.ts.net,skippy@your-tailnet.ts.net"

Option B (agents/scripts): a bearer token (stored 0600, never echoed).

envelope config set dashboard.auth_token "$(openssl rand -hex 32)"

tailscale serve --bg 3141

See where Envelope is storing local state

envelope paths

The dashboard opens as a three-pane mail shell. Unified Inbox is the default read-only surface and loads from the local message index; explicit refreshes or account/folder selections are what touch live IMAP mailboxes.

Actual sends are outbox-first. By default, an allowed send queues with a safety cooldown and the scheduled-send sweep performs the SMTP transmission later. Every agent send must declare factual attributes, and Envelope checks them against what it can observe before anything is queued or sent.

Governor scoring is a build-time Cargo feature, off by default. Homebrew and the release archives are built without it, so their sends are not scored by Governor, and send results and audit events record the gate as mode: "off". In those builds the draft-only ceiling still binds MCP sessions that carry an agent token, but an agent with shell access can send through envelope send (which defaults to autonomous-send), so give agents MCP with an agent token rather than a shell. Builds made with cargo build --release --bin envelope --features governor (or cargo install --path crates/cli --features governor) derive sanitized contextual attributes immediately before SMTP and ask Governor to score them with governor score --catalog envelope; only an opaque Governor allow sends. Those builds expect the Governor binary at the path pinned in SMTP_GOVERNOR_BIN (crates/email/src/outbound.rs), and every send fails closed when it is missing. Message bodies, full recipient addresses, attachment bytes, and secrets never enter the Governor request.

Dashboard URL metadata in --json output is discovered fresh for each UI construction or request, from an active local tailscale serve HTTPS route whose root proxy targets http://127.0.0.1:3141. It otherwise falls back to http://localhost:3141. Every agent-facing ui object reports that decision as dashboard_origin_source (tailscale_serve or localhost_fallback) and adds a non-secret dashboard_origin_warning only when discovery needs attention. MCP results omit these ui objects and skip Tailscale discovery unless the call passes include_ui_links: true, so the host's tailnet name stays out of model context by default. dashboard_path is always portable and remains the canonical handle for agents; dashboard.base_url and the legacy dashboard-base environment variables are retained only for compatibility and do not affect emitted agent UI links. Tailscale Serve keeps the dashboard tailnet-only; Tailscale Funnel publishes it on the public internet, so do not use Funnel for a mailbox dashboard unless that exposure is intentional.

Authentication (required before any non-loopback exposure)

On 127.0.0.1 the dashboard is an unauthenticated single-user local surface — the same trust boundary as your shell. The REST API reads and deletes mail, manages accounts, and queues sends, so the moment it is reachable by another device (a non-loopback --bind, or a tailscale serve front-end) it must require a credential. Configure one of:

• Tailscale identity allowlist (dashboard.tailscale_allow) — a request whose Tailscale-User-Login header (injected by tailscale serve) is in the allowlist is authorized. Humans just open the .ts.net URL; no token to type. Only safe behind tailscale serve, which sets and strips that header.
• Bearer token (dashboard.auth_token or ENVELOPE_DASHBOARD_TOKEN) — sent as Authorization: Bearer (or X-Envelope-Token), compared in constant time. The path for Hermes/OpenClaw agents and scripts.

Once either is configured, every /api route returns 401 without a valid credential — including when tailscale serve fronts loopback. envelope serve --bind refuses to start unless an auth method is configured. /api/health stays reachable for liveness probes but discloses local filesystem paths only to authorized callers. The CORS allowlist is a browser-only defense, not the access control.

Why not Himalaya / Cloudflare / Resend?

vs. Himalaya

Himalaya is a great CLI email client. Envelope is a CLI email client built for agents.

| Multiple accounts | ✅