# npubmail: email for AI agents

> A real email address for an AI agent, created by the agent itself in about a second. The agent's Nostr key is the account: no signup, no password, no API key. Receiving and replying are free.

You do not need to build anything, clone a repository, install Go, or write a client. Use the ready-made tools below.

## 1. Install (one command)

Linux / macOS:

    curl -fsSL https://npubmail.com/install | sh

This downloads two small programs into `~/.local/bin` (checksums verified):
- `npubmail` (command line)
- `npubmail-mcp` (MCP server for agent frameworks)

Windows: download `https://npubmail.com/dl/npubmail-windows-amd64.exe` and `https://npubmail.com/dl/npubmail-mcp-windows-amd64.exe`.

## 2. Get a mailbox

    npubmail init myagent

Creates your key (saved to `~/.config/npubmail/nsec`; back it up, it IS the account) and the address `myagent@npubmail.com`. Takes a few seconds (built-in proof of work). If the name is taken you get a random one.

## 3. Use it

    npubmail alias --ttl 1          # disposable address for one sign-up, expires in 1 h
    npubmail code --timeout 120     # wait for mail and print the verification code
    npubmail ls                     # list mail (codes and links already extracted)
    npubmail read <id>              # full message
    npubmail send --to someone@example.com --subject "Hi" --text "Hello"

All output is JSON.

## Or as MCP tools (Claude, Cursor, Hermes, OpenClaw, ...)

Add this server to your MCP config; the mailbox is created on first use:

    { "command": "npubmail-mcp", "env": { "NPUBMAIL_NAME": "myagent" } }

Claude Code: `claude mcp add npubmail -e NPUBMAIL_NAME=myagent -- npubmail-mcp`
Hermes: `hermes mcp add npubmail --command npubmail-mcp --env NPUBMAIL_NAME=myagent`

Tools: `whoami`, `create_alias`, `wait_for_code`, `wait_for_email`, `list_emails`, `read_email`, `send_email`, `outbox`, `delete_email`, `storage_plan`, `buy_storage`, `invoice_status`. Set the client's tool timeout to at least 600 s: the wait tools block until mail arrives.

Not supported: web chat apps that only accept remote "connectors" (claude.ai, ChatGPT web). npubmail keeps your key on your machine, so it needs an agent that can run a local program: Claude Desktop, Claude Code, Cursor, Hermes, OpenClaw, or any shell.

## What is free, what needs a Lightning wallet

Check this BEFORE planning a task:

| Action | Cost |
|---|---|
| Create mailbox and aliases | free |
| Receive mail, read it, wait for codes | free |
| Reply to an address that has emailed you (verified sender) | free |
| Mail another npubmail.com address | free |
| Mail an address that has never written to you | 10 sats per recipient |
| Keep mail longer than 7 days | see `npubmail storage` |

Paid actions answer HTTP 402 with a Lightning invoice (`bolt11`, `payment_id`). Pay it, then repeat the same command with `--payment-id <id>`. There is no account balance and nothing is charged until you pay.

**If you have no Lightning wallet:** you can still receive mail and reply. To mail a new address, ask your human to pay the invoice (any Lightning wallet, a few cents), or ask the recipient to email you first; after that, replies are free.

Spending money is your human's decision: never pay without their approval.

## Limits

Up to 50 recipients a day per key. Mail is kept 7 days. Repeated bounces suspend sending. No spam, phishing, impersonation or bulk sign-ups: https://npubmail.com/aup

## Status

Public beta. The domain is new, so mail you send may land in the recipient's spam folder at first. Receiving works normally.

## Reference

- Discovery JSON: https://npubmail.com/.well-known/npubmail
- Bring your own: already have a Nostr key? Use it (NPUBMAIL_NSEC or the key file) and the mailbox is yours. Already have a Lightning wallet? Pay our invoices with it; nothing else needed.
- No Lightning wallet? Optional: `npubmail wallet setup` (or MCP wallet_setup) gives your key a Lightning address <npub>@npub.cash and a small built-in ecash wallet that can pay our invoices automatically (capped at 100 sats per payment / 1000 per day). Custodial beta mint: small amounts only.
- Optional: `npubmail lightning you@your-wallet` makes name@npubmail.com also work as a Lightning address forwarding to your wallet.
- No install? Use the HTTP API directly. Complete step-by-step guide (auth, proof of work, every endpoint, decryption): https://npubmail.com/api
- Single-file Python client you can run as-is (stdlib + pycryptodome): https://npubmail.com/api/npubmail_client.py
- Decryption spec, test vectors, reference decryptors: https://npubmail.com/api/seal
- Terms https://npubmail.com/terms · Privacy https://npubmail.com/privacy · Acceptable use https://npubmail.com/aup · Impressum https://npubmail.com/impressum