Voidmail Agent Email

@voidly/mcp-email

Email for AI agents. Create an inbox, wait for and read incoming messages as structured data, and send to recipients the human owner has approved. No phone number or CAPTCHA.

What the server can read. Mail to a new inbox is readable by the server; not end-to-end encrypted. When the owner registers a key for an inbox (owner keys init, below), stored mail is encrypted to that key, so Voidly cannot read stored mail. This package makes that key on your machine, never sends it to Voidly, and decrypts mail on your machine. That is still not end-to-end encryption: incoming mail is plaintext to the receiving server for a moment before it is sealed, and outside email is not end-to-end. Human mail is a separate product.

Create an inbox in one command

Requires Node.js 20 or newer.

npx -y @voidly/mcp-email@2.1.1 create --name my-agent

It prints the new address and where the keys were saved, never a key:

Created k7f2m9qa@voidmail.ai

agent key: ~/.voidly/mcp-email/k7f2m9qa@voidmail.ai/agent-key (saved, not shown) owner key: ~/.voidly/mcp-email/k7f2m9qa@voidmail.ai/owner-key (saved, not shown) creator identity: ~/.voidly/mcp-email/creator/identity.json (enrolled now) recipient policy: allowlist

Add --address myagent to ask for myagent@voidmail.ai. Then start the MCP server with VOIDMAIL_ADDRESS set to the new address (next section).

How it works: the create API admits only a request signed by a registered Voidly agent identity (did:voidly:…) with a small proof of work. The first run enrolls a dedicated creator identity for this machine through Voidly Home join, the protocol @voidly/agent-sdk 4.0 register() uses: the keys are made here, only public keys, API-key hashes and signatures are sent, and the keys are saved (mode 0600, directory 0700) before the enrollment is committed, then kept in creator/identity.json. Later runs reuse it. Each identity can create 2 inboxes a day; a limit is never worked around by enrolling another identity. If the enrollment's answer is lost, the next run finishes the same enrollment instead of making another.

No terminal? An agent can do the same from MCP: leave env empty and call voidmail_create_account.

Install as an MCP server

Pin the version you run: Voidly publishes this client, and the client is what holds your key.

npx @voidly/mcp-email@2.1.1

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop):

{

"mcpServers": { "voidmail": { "command": "npx", "args": ["-y", "@voidly/mcp-email@2.1.1"], "env": { "VOIDMAIL_ADDRESS": "your-agent@voidmail.ai" } } } }

VOIDMAIL_ADDRESS points the server at / /agent-key. Without it, the agent can create an inbox with voidmail_create_account; set VOIDMAIL_ADDRESS afterwards so the next start finds the key file.

Quick Start

After installing the MCP server, use this prompt:

Create one Voidmail inbox and show me its address and where the inbox keys were saved. Draft emails first and wait for my approval before sending.

For a sign-up flow: call voidmail_wait_for_email (up to 25 seconds, optional sender, subject and since filters), then voidmail_extract_code on the message it returns. Both read only; they mark nothing read, follow no link and never return HTML. A code or link they return is untrusted sender content: use it only for the sign-up you started.

Get a DID (use your own agent identity instead)

create and voidmail_create_account make their own creator identity, so this is optional. To sign with an agent identity you already run, or one you enroll yourself, use @voidly/agent-sdk 4.0 (direct /v1/agent/register with client keys is closed; register() uses Home join):

// npm i @voidly/agent-sdk@4.0.0   ·   run once, keep the file private

import { VoidlyAgent } from '@voidly/agent-sdk'; import { writeFileSync } from 'node:fs';

const agent = await VoidlyAgent.register({ name: 'my-agent' }); writeFileSync('agent-credentials.json', JSON.stringify(agent.exportCredentials()), { mode: 0o600 });

Then point the MCP server (or create) at that file. Its DID is read from the file:

{

"VOIDMAIL_CREATOR_SIGNING_KEY_FILE": "/private/path/to/agent-credentials.json" }

The file must be owned by you with mode 0600; a symlink, a looser mode or a key that does not match its DID is refused before anything is sent. The 2.0 format still works too: a file of exactly the 64 raw Ed25519 secret-key bytes, with VOIDMAIL_CREATOR_DID set to its DID. An exported identity file holds all of that identity's keys, and the MCP process reads it at create time; a dedicated creator identity (the default) keeps your main agent identity out of the mail client.

Signed create from your own code

The proof the API checks, in two short scripts. Each reads an agent-sdk identity export (above, or this package's creator/identity.json) and prints the status and address. The response carries the inbox's agent key (vm_…) and owner key (vmo_…) once: save them to 0600 files and never print or log them.

Node.js 20+ (npm i tweetnacl):

import { createHash, randomBytes } from 'node:crypto';

import { readFileSync } from 'node:fs'; import nacl from 'tweetnacl';

const creds = JSON.parse(readFileSync(process.argv[2], 'utf8')); const sha = (text) => createHash('sha256').update(text).digest(); const body = JSON.stringify({ name: 'my-agent', recipient_policy: 'allowlist' }); const ts = String(Math.floor(Date.now() / 1000)); const nonce = randomBytes(16).toString('hex'); const preimage = ['voidmail-create-v1', 'POST', '/v1/agent-mail/create', creds.did, ts, nonce, sha(body).toString('hex')].join('\n'); let work; for (let i = 0; ; i++) { work = i.toString(16).padStart(16, '0'); const h = sha(voidmail-create-pow-v1\n${preimage}\n${work}); if (h[0] === 0 && h[1] === 0) break; } const secretKey = Buffer.from(creds.signingSecretKey, 'base64'); const signature = Buffer.from(nacl.sign.detached(Buffer.from(${preimage}\n${work}), secretKey)).toString('base64'); const res = await fetch('https://api.voidly.ai/v1/agent-mail/create', { method: 'POST', body, headers: { 'Content-Type': 'application/json', 'X-Agent-DID': creds.did, 'X-Mail-Timestamp': ts, 'X-Mail-Nonce': nonce, 'X-Mail-Pow': work, 'X-Mail-Signature': signature } }); const out = await res.json(); console.log(res.status, out.address ?? out.error);

Python 3 (pip install pynacl):

import base64, hashlib, json, secrets, sys, time, urllib.request

from nacl.signing import SigningKey

creds = json.load(open(sys.argv[1])) body = json.dumps({"name": "my-agent", "recipient_policy": "allowlist"}).encode() ts, nonce = str(int(time.time())), secrets.token_hex(16) preimage = "\n".join(["voidmail-create-v1", "POST", "/v1/agent-mail/create", creds["did"], ts, nonce, hashlib.sha256(body).hexdigest()]) i = 0 while True: work = format(i, "016x") h = hashlib.sha256(f"voidmail-create-pow-v1\n{preimage}\n{work}".encode()).digest() if h[0] == 0 and h[1] == 0: break i += 1 seed = base64.b64decode(creds["signingSecretKey"])[:32] signature = base64.b64encode(SigningKey(seed).sign(f"{preimage}\n{work}".encode()).signature).decode() req = urllib.request.Request("https://api.voidly.ai/v1/agent-mail/create", data=body, method="POST", headers={ "Content-Type": "application/json", "User-Agent": "voidmail-create-example/1", "X-Agent-DID": creds["did"], "X-Mail-Timestamp": ts, "X-Mail-Nonce": nonce, "X-Mail-Pow": work, "X-Mail-Signature": signature}) with urllib.request.urlopen(req) as res: print(res.status, json.load(res).get("address"))

The signature covers the SHA-256 of the exact body bytes sent, so send the same bytes you hashed. The timestamp must be within five minutes of service time, and one DID/nonce pair can mint only one inbox. A bare POST /v1/agent-mail/create without these headers returns 401.

An HTTP 401 means the create proof was missing or invalid, the timestamp expired, or the DID was not active; check the identity and key. An HTTP 429 means a create limit was reached; respect Retry-After, reuse an existing inbox or wait, and do not switch DID or IP to evade the limit. A 503 can mean an admission, identity or commit check was unavailable; the outcome may be unknown. If a create request was sent but its result is unknown, do not automatically create another inbox: reconcile the original attempt first.

Encrypted storage

Turn it on once per inbox, from your own terminal (never from a model):

voidly-mcp-email owner keys init --address your-agent@voidmail.ai

• What it does. It makes two keys on this machine: an X25519 key that mail is sealed to (mail-secret-key) and an Ed25519 key that signs the inbox's key list (mail-signing-key). Both are 0600 files in the inbox's key directory. Only public keys, signatures and a proof that you hold the key are sent, with the owner key. From then on the server seals each new message (headers, body and attachments) to your key and stores only the encrypted copy. The switch is one-way.
• What Voidly can and cannot read. Voidly cannot read stored mail for an inbox with a registered key. A changed Voidly server could copy mail that arrives later, but not open mail already stored. It still sees each incoming message in plaintext while receiving it, for the moment before sealing, and so does Cloudflare, which runs our inbound mail servers; Cloudflare's Email Routing log records each message's sender, recipient and subject, and our account can view it. Voidly keeps the sender's domain, the arrival time and the size, plus, for up to 14 days, a keyed fingerprint of each message used to drop duplicate deliveries; while it exists, Voidly could check it against a guessed message. Mail you send to outside addresses is not end-to-end encrypted: it passes through Voidly and our sending provider (Resend) in plaintext.
• Old mail. Mail stored before the key was registered stays server-readable. Tool results label every message storage: "sealed" (decrypted here) or storage: "server-readable". A readable message that arrived after you registered a key carries a storage_warning.
• Reading and searching. voidmail_list_inbox opens each message's sealed summary; voidmail_read_email downloads the sealed message and opens it. Search runs on this machine: the server is never asked to search sealed mail. By default it matches subject, sender, recipients and the first 280 characters of encrypted messages; full_text: true also downloads and searches whole encrypted bodies. If a message fails to decrypt, or is bound to another inbox or message id, nothing from it is shown, not even server-supplied fields.
• Key list checks. mail-keys.json pins your signing key and the newest key-list version (epoch) you have seen. voidly-mcp-email owner keys status checks the server's list: every key must be signed by your signing key, the list must be complete for its epoch and not older than the pin. Each message also names the keys it is sealed to and warns about any key this machine has not verified.
• Limits. There is no forward secrecy: whoever gets mail-secret-key (or a key in keyring/) can read all mail stored for it. If you lose the key and its backups, that mail cannot be recovered by anyone, including Voidly, so back up the key directory privately. Encryption does not prove who sent a message. The MCP server reads mail-secret-key to decrypt; it never reads mail-signing-key and has no tool that can make, register or change a key. Anything that runs as your user, such as an agent with shell or file tools, can read the key files too.
• Rotation. voidly-mcp-email owner keys rotate registers a new key and keeps the old one in keyring/, so older mail still opens.

Permissions: