📧 Envelope

📧 Envelope

U+1F4E7 — if you know, you know.

Email for agents. Add your credentials, and go.

BYO mailbox. Human-in-the-loop approval. Production-scale.

Why U1F4E7? It's the Unicode codepoint for 📧. Humans see a repo name. Agents see an envelope. The ones who get it are the ones this was built for.

30-Second Setup • Approval Flows • vs. Alternatives • OpenClaw • Scale • API • License

Your agent needs to send email. You shouldn't need to configure DNS records, set up a new domain, or pay per-message fees to make that happen.

Envelope: add your email address and SMTP password. That's it. Your agent sends email as you, from your mailbox, with your approval.

# Add a mailbox
curl -X POST http://localhost:8000/accounts \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "smtp_password": "your-app-password"}'

# Your agent drafts an email (doesn't send — waits for approval)
curl -X POST http://localhost:8000/accounts/{id}/drafts \
  -d '{"to": "[email protected]", "subject": "Proposal", "text": "..."}'

# You review and approve
curl -X POST http://localhost:8000/accounts/{id}/drafts/{draft_id}/approve

30-Second Setup

git clone https://github.com/tymrtn/U1F4E7.git && cd U1F4E7
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Open http://localhost:8000 → add your email address + SMTP password → done. Your agent can send email.

For Gmail: create an app password. For Fastmail, Migadu, any IMAP/SMTP provider: use your existing credentials. Envelope auto-discovers IMAP/SMTP settings from your email address.

Approval Flows

This is what separates Envelope from a raw SMTP library or a CLI tool like Himalaya.

Your agent should never send email without your say-so. Envelope enforces this architecturally:

Agent drafts email → Draft enters review queue → Human approves/rejects → Email sends (or doesn't)

How it works

1. Agent creates a draft via API or MCP — the email is composed but NOT sent
2. Draft enters the review queue at /review — a web UI where you see exactly what the agent wants to send
3. You approve or reject — approve sends immediately; reject returns feedback to the agent
4. Full audit trail — every draft, every approval, every rejection is logged with timestamps

Why this matters

AI agents are powerful but imperfect. A hallucinated email to a client, a wrong recipient, a tone-deaf reply — these are career-ending mistakes, not debug-and-retry situations. The approval gate is not a nice-to-have. It's the entire point.

You can also configure domain policies — rules like "always require approval for external domains" or "auto-approve internal replies" — so the gate is smart, not annoying.

Approval modes

OpenClaw Integration

Envelope was built to work with OpenClaw and any agent framework that speaks MCP.

As an OpenClaw skill

Add Envelope as an MCP server in your OpenClaw config:

{
  "mcpServers": {
    "envelope": {
      "command": "python",
      "args": ["-m", "app.mcp"],
      "cwd": "/path/to/U1F4E7",
      "env": {
        "ENVELOPE_SECRET_KEY": "your-key",
        "ENVELOPE_API_URL": "http://localhost:8000"
      }
    }
  }
}

Your agent can then:

→ start_here(account_id="...")        # Learn account policies and rules
→ create_draft(to="...", ...)         # Compose a draft (does NOT send)
→ list_drafts(account_id="...")       # Review pending drafts
→ approve_draft(draft_id="...")       # Approve and send (or reject with reason)
→ read_inbox(account_id="...")        # Check for replies
→ log_action(action="...", ...)       # Audit trail

With Claude Code, Cursor, Windsurf

Same MCP config. Envelope works with any MCP-compatible client — it's not locked to OpenClaw.

With raw REST

No MCP? No problem. Every feature is available via the REST API. Use it from Python, Node, curl, or any HTTP client.

Why Not Himalaya / Resend / Mailgun?

vs. Himalaya

Himalaya is a great CLI email client for humans. Envelope is an email API for agents. The differences:

If your agent just needs to fire-and-forget a notification, Himalaya works. If your agent is emailing clients, partners, or anyone who matters — you need the approval layer.

vs. Resend / Mailgun / SendGrid

Resend and friends are transactional email services — they're great for sending password resets from [email protected]. Envelope is a full email operating layer — read, write, draft, approve, track, audit — on top of mailboxes you already own.

Production Scale

Envelope isn't a toy. It's built to replace Resend/Mailgun in production:

• Async everywhere — aiosmtplib + aioimaplib for non-blocking I/O
• Connection pooling — persistent IMAP connections, not connect-per-request
• Rate limiting — per-account send throttling to stay within provider limits
• Queue-based sending — decouple draft creation from delivery
• SQLite → Postgres — swap the persistence layer for production (Postgres adapter on roadmap)
• Horizontal scaling — stateless API, externalize the DB, run N instances
• Credential encryption — Fernet encryption at rest for all stored passwords
• Webhook delivery events — get notified on send, bounce, open (roadmap)

For SaaS / Multi-Tenant

Building a product where users connect their own email? Envelope handles multi-account natively. Each account has its own credentials, policies, and audit trail. Add a tenant layer on top and you have a white-label email API.

Features

Core

• Send email with CC, BCC, Reply-To, attachments
• Read inbox via IMAP — list, search, fetch messages
• Thread reconstruction — follow conversation chains
• Auto-discovery — paste an email address, Envelope finds IMAP/SMTP settings
• Open tracking — pixel-based read receipts
• Signatures — per-account, per-context

Agent Layer

• Draft previews — agent composes, human reviews
• Approval gates — configurable per domain, per recipient, per account
• Domain policies — rules that govern what agents can do
• Action audit log — full provenance trail
• Scheduled sends — send_after for time-delayed delivery
• Rate limiting — per-account throttling

Dashboard

• Web UI at / — manage accounts, view messages
• Review queue at /review — approve or reject agent drafts
• Agent status at /agent/status — monitor activity

API Reference

Accounts

Send & Read

Drafts & Approval

Agent & Monitoring

Architecture

┌──────────────┐     ┌──────────────────────────┐     ┌──────────────┐
│  AI Agent    │────▶│      Envelope API         │────▶│  Your SMTP   │
│  (OpenClaw,  │     │                            │     │  (Gmail,     │
│   Claude,    │     │  Draft → Review → Approve  │     │   Fastmail,  │
│   Cursor)    │◀────│  Policies → Audit → Send   │◀────│   Migadu)    │
│              │     │                            │     │              │
│  MCP / REST  │     │  SQLite / Postgres         │     │  IMAP/SMTP   │
└──────────────┘     └──────────────────────────┘     └──────────────┘

Roadmap

• pip install envelope-email (Python SDK)
• Node.js SDK
• Postgres adapter
• Webhook delivery events (send, bounce, open)
• OAuth2 for Gmail/Outlook (no app passwords needed)
• React Email template support
• Docker compose one-liner
• Multi-tenant admin API
• OpenClaw skill package (one-command install)

Contributing

Envelope uses an agentic engineering protocol. See agents/PROTOCOL.md for contribution workflow.

# Run tests
pytest tests/

# Run with debug logging
uvicorn app.main:app --reload --log-level debug

License

FSL-1.1-ALv2 — Functional Source License. Free to use, modify, and self-host. Converts to Apache 2.0 after 2 years. Cannot be used to build a competing hosted email API service.

Built by Tyler Martin Your agent shouldn't need a $50/month Resend plan to send an email.