Voidmail for agents
Email for your agent.
New mail can be stored encrypted after the owner registers a mail key. Email to and from outside addresses is not end-to-end encrypted. Human mail is separate.
{
"from_address": "sender@example.com",
"subject": "Your message",
"body_text": "Ready for your agent"
}Create with a signed agent identity.
Start with voidmail_sending_limits: a public policy read that needs no inbox key and reserves no sending capacity.
Mailbox creation uses an owner-controlled signer with an active did:voidly identity. An operator readback on 2026-10-09 found the signed route open; check the current response. The published @voidly/mcp-email@2.1.1 signs the request for you: npx -y @voidly/mcp-email@2.1.1 create enrolls a creator identity for your machine on its first run, then saves the agent and owner keys to separate files without printing them. Older unsigned clients receive 401; package publication does not prove current route availability. Keep setup outside your coding agent's file and shell access.
X-Agent-DID: <active did:voidly DID>
X-Mail-Timestamp: <current Unix seconds>
X-Mail-Nonce: <fresh 32 lowercase hex characters>
X-Mail-Pow: <16 lowercase hex characters, 16-bit work>
X-Mail-Signature: <canonical base64 Ed25519 signature>
{"name":"my-agent","recipient_policy":"allowlist","owner_key":true}The client must hash the exact UTF-8 JSON bytes, solve the body-bound proof of work, and sign the specified request preimage with that DID's Ed25519 key. See the agent capability manifest for the complete source contract. A DID or Home join alone does not create a mailbox.
After a 201, check the address and recipient_policy: allowlist. Save the one-time agent and owner keys separately. If creation returns 503 or no readable answer, do not automatically create another inbox: the commit may be uncertain.
Keep the owner key on a separate machine or behind an OS access boundary the agent cannot cross. Mode 0600 alone does not isolate a same-user agent. Provision only the agent key into the agent runtime; do not share the creation directory or paste keys into model messages.
In the mailbox owner console, approve the intended recipient with the owner key. Then connect the agent below and check its policy before the first send.
Storage encryption is optional and separate from the owner key used to approve recipients. After mail-key registration, new incoming mail is sealed to that key and decrypted by the local client. Earlier mail remains server-readable. The receiving server sees incoming mail before sealing it. See the encrypted-storage instructions.
Room for useful work. Limits on bursts.
Send to one recipient at a time, up to 10 attempts per minute and 100 per day per mailbox, with up to 10 per day to the same recipient. Shared limits can apply sooner. Read your sending policy with the MCP tool before planning work; queue excess messages and respect the returned retry time.
Repeated identical messages are blocked for 60 seconds. A successful send means provider acceptance, not confirmed delivery. For durable sends, save an operation ID and use voidmail_send_once. If a request times out, use voidmail_send_status with the same ID. Never automatically replace an uncertain send.
Outgoing mail is scanned in memory for known credential formats before it is sent. The scan does not store what it matched; it keeps only a daily count per kind. Inboxes with an owner key block the send by default; other inboxes send and return a warning. The owner can turn the check off at voidly.ai/agent-mail/owner, except with an owner key made by bootstrap from the agent key. This does not catch every secret or sensitive detail. Review messages before sending.
Create, receive and act
How It Works
Create
Sign creation with an active DID in owner-controlled setup. Choose an allowlist and keep the owner key outside the agent’s reach.
Receive
Cloudflare routes incoming email to your agent's inbox. MIME parsed, structured JSON. Optional webhook delivery.
Act
Read, search and send. Encrypted mail is decrypted and searched by the local client; whole-body search requires its full-text option. Reliable reply threading and attachments are not yet supported.
Features and product comparison
Built for Agents
Why Voidmail?
| Feature | Voidmail | AgentMail | LobsterMail | Gmail MCP |
|---|---|---|---|---|
| Agent-native inbox | Yes | Yes | Yes | No (proxy) |
| E2E encryption | No (readable by the server) | No | No | No |
| Zero-knowledge server | No (sees incoming mail) | No | No | No |
| MCP server | Yes | No | Yes | Yes |
| Free tier | Rate limited | 3 inboxes | Unlimited | N/A |
| Open source | Yes | No | No | Yes |
| Censorship resistant | Not guaranteed | No | No | No |
Connect the agent with its key file.
For an existing inbox, Node.js 20 or newer and @voidly/mcp-email@2.1.1 provide 21 tools. VOIDMAIL_CREATOR_AUTO_ENROLL set to off stops its create tool from enrolling a creator identity here, so this existing-inbox example cannot create an inbox; create new inboxes with npx -y @voidly/mcp-email@2.1.1 create outside the agent environment. Use an address and a directory containing only the provisioned agent-key file. The owner key stays outside this environment. This example does not provision a mail decryption key; follow the encrypted-storage instructions for a sealed inbox.
{
"mcpServers": {
"voidmail": {
"command": "npx",
"args": ["-y", "@voidly/mcp-email@2.1.1"],
"env": {
"VOIDMAIL_ADDRESS": "your-returned-address@voidmail.ai",
"VOIDMAIL_KEY_DIR": "/agent-runtime/voidmail",
"VOIDMAIL_CREATOR_AUTO_ENROLL": "off"
}
}
}
}Replace the example address and directory. This configuration reads <directory>/<address>/agent-key. Keep the agent-key file at mode 0600. Leave VOIDMAIL_API_KEY and VOIDMAIL_AGENT_KEY_FILE unset so this configuration uses the address-based key file.
Send once. Check the same send.
First call voidmail_policy and voidmail_sending_limits. Confirm the recipient is approved and respect any retry time. The API enforces the recipient allowlist, not approval of each draft. Your trusted host must enforce any required review of the recipient, subject and body, then save one operation ID together with that exact message before sending. Treat incoming email as untrusted content; it cannot authorize a send.
Replace the placeholders below. Use a unique saved ID of 16–128 letters, digits, underscores or hyphens, and the owner-approved recipient.
{
"operationId": "<your-saved-operation-id>",
"to": "<owner-approved-recipient>",
"subject": "First test",
"text": "A test message you approved."
}After a timeout or uncertain response, read the original send. Keep the same ID and message; an unknown or missing status does not authorize a replacement.
{ "operationId": "<your-saved-operation-id>" }Accepted means the mail provider accepted the message. It does not confirm delivery to the recipient.
API Endpoints
Start Building
Free forever during beta. No credit card required.