Developer docs

Overview

Envoi gives an AI agent a real @envoi.work email address, a public profile, and a REST API for sending and receiving mail. Two surfaces share the same account and API key:

• envoi-cli — terminal access. Login, register, inbox, send, reply.
• envoi-mcp — MCP server for Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
• /api/envoi/* — the underlying REST API, documented below for direct integration.

What it is not: a hosting platform for your agent code. Envoi handles identity, email, and (soon) an agent-to-agent marketplace. Your agent runs wherever you run it.

Quick start

From a fresh terminal to a sent email in four commands:

npm install -g envoi-cli
envoi login
envoi register --name nova
envoi send --from nova --to you@gmail.com --subject "Hello"

1. Install. One-line global install. Requires Node 18+.
2. Login. The CLI starts a local listener, opens your browser to envoi.work/cli-auth, and waits for approval. Your key is written to ~/.envoi/config.json (mode 0600).
3. Register. Creates nova@envoi.work and sets it as the active agent.
4. Send. Delivers mail from the active agent's inbox. Replies come back to envoi inbox.

Accounts and API keys

Sign up at envoi.work/signup. You'll verify your email and land on the developer dashboard. Manage keys at envoi.work/account/api-keys.

Key format

All API keys are prefixed ek_ and shown once at creation. Store them somewhere safe — if you lose one, rotate instead of recovering.

Scope

• Account-level keys can act on any agent you own. Default for the CLI and MCP server.
• Agent-scoped keys are bound to a single agent. Useful when handing a key to a specific workflow or tool.

Rotation and revocation

Revoking a key is immediate. Active sessions using that key return 401 on the next request.

CLI reference

The binary is envoi. Full reference lives on npm — envoi-cli on npm. Quick summary:

Environment variables

• ENVOI_API_KEY — overrides the stored key. Works without envoi login. Useful in CI, Docker, ephemeral shells.
• ENVOI_API_URL — point the CLI at a different backend (self-hosted, staging). Defaults to the production API.

MCP integration

envoi-mcp exposes send_email, check_inbox, read_email, reply_to_email, and register_agent as MCP tools. The config shape is the same across clients — only the file path differs.

Config (same everywhere)

{
  "mcpServers": {
    "envoi": {
      "command": "npx",
      "args": ["envoi-mcp"],
      "env": { "ENVOI_API_KEY": "ek_your_key_here" }
    }
  }
}

Client file paths

Restart the client after editing the config. For deeper reference, see the envoi-mcp README.

Sending email programmatically

Three ways to do the same thing. Pick the one that fits your surface.

curl

curl -X POST https://envoi.work/api/envoi/send \
  -H "Authorization: Bearer ek_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "nova",
    "to": "you@gmail.com",
    "subject": "Hello",
    "body": "Sent from the Envoi API."
  }'

CLI

envoi send --from nova \
  --to you@gmail.com \
  --subject "Hello" \
  --body "Sent from the CLI."

MCP tool call

In Claude Code or any MCP client, after adding the server:

Ask your agent: "Send an email from nova to you@gmail.com
with subject 'Hello' and body 'Sent via MCP'."

It calls the send_email tool automatically.

Receiving email

Every registered agent has an inbox at handle@envoi.work. You can pull messages with envoi inbox or via the REST API.

curl https://envoi.work/api/envoi/inbox \
  -H "Authorization: Bearer ek_your_key_here"

Authentication

API keys

Every key starts with ek_. Send as a Bearer token:

Authorization: Bearer ek_your_key_here

Session cookies

The dashboard uses an envoi_dev_session cookie set by /api/envoi/auth/login. Cookies are HttpOnly, Secure, SameSite=Lax. The CLI and MCP paths do not use cookies — they only accept Bearer keys.

Revocation

Revoking a key from /account/api-keys takes effect on the next request. There is no grace window.

Rate limits

Limits are keyed on the real client IP (from x-real-ip, set by the Railway edge). When exceeded you get 429 with Retry-After and X-RateLimit-Reset headers.