Quickstart

Send your first email

Prerequisite: You need a wallet with USDC on Base. $1 USDC = 200 emails. See Wallet Setup below.

Install

terminal

pip install x402mail[cdp]
export CDP_API_KEY_ID="your-key-id"        # from cdp.coinbase.com
export CDP_API_KEY_SECRET="your-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"

Send your first email

send.py

from x402mail import X402Mail

mail = X402Mail.from_cdp()

mail.send(
    to="alice@example.com",
    subject="Hello from x402mail",
    body="Sent with 3 lines of Python!"
)

That's it. The SDK handles x402 payment signing automatically. See SDK reference below.

SDK Reference

Your inbox address is derived from your wallet: inbox-{wallet_prefix}@x402mail.com. It's created automatically on first use — use mail.address to see your wallet address.

mail.send(to: str, subject: str, body: str, reply_to: str = None, reply_to_message_id: int = None) $0.005

Send an email. Use reply_to_message_id to thread replies.

{"message_id": "re_abc123xyz", "inbox": "inbox-0x1a2b...@x402mail.com"}

mail.inbox() → dict $0.001

Get your inbox address and message counts.

{"inbox": "inbox-0x1a2b...@x402mail.com", "total": 5, "unread": 2}

mail.messages(limit: int = 10, unread_only: bool = False) $0.002

List inbox messages. Returns previews, not full bodies.

[{
  "id": 1,
  "from": "user@example.com",
  "subject": "Hello",
  "preview": "Thanks for reaching out...",
  "received_at": "2026-01-15T10:30:00+00:00",
  "is_read": false
}]

mail.read(message_id: int) $0.001

Read a specific message. Marks it as read.

{
  "id": 1,
  "from": "user@example.com",
  "subject": "Hello",
  "body": "Thanks for reaching out. I'd love to discuss this further.",
  "received_at": "2026-01-15T10:30:00+00:00",
  "message_id": "<abc123@mail.example.com>",
  "in_reply_to": null
}

MCP Server for AI Agents

Run a local MCP server so LLMs can send and receive email. The server handles x402 payments internally — the AI just sees simple tools.

terminal

# With pip
x402mail mcp

# Or without installing
uvx x402mail mcp

Claude Desktop / Cursor Config

Install first: pip install x402mail[cdp]

mcp_config.json

{
  "mcpServers": {
    "x402mail": {
      "command": "x402mail",
      "args": ["mcp"],
      "env": {
        "CDP_API_KEY_ID": "your-key-id",
        "CDP_API_KEY_SECRET": "your-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

Or use a private key instead: "X402MAIL_PRIVATE_KEY": "0x..."

Available Tools

Tool	Cost	Description
send_email	$0.005	Send an email
get_inbox	$0.001	Get inbox address + counts
list_messages	$0.002	List inbox messages
read_message	$0.001	Read a specific message

Wallet Setup

You need a wallet with USDC on Base. Your wallet is your identity — your inbox address is derived from it automatically.

Recommended CDP Server Wallet

Managed wallet via Coinbase — no private keys to manage. Follow the CDP quickstart guide to get your API keys, then set the env vars shown in the Quickstart above.

Alternative: Private Key

Use any EVM wallet. Fund it with USDC on Base (Chain ID: 8453).

import os
from x402mail import X402Mail

mail = X402Mail(private_key=os.getenv("EVM_PRIVATE_KEY"))

$1 USDC = 200 emails. That's enough to test extensively. Start small.

Pricing

Action	SDK Method	Cost (USDC)
Send an email	mail.send()	$0.005
Get inbox info	mail.inbox()	$0.001
List messages	mail.messages()	$0.002
Read a message	mail.read()	$0.001

Spam Protection

There are no rate limits — payment is the rate limit. Spam is handled by AI classification.

AI spam filter

Every email body is classified by an LLM before sending. Detected spam is rejected and the payment is non-refundable.

Cooldowns

After 5 spam strikes, your wallet enters a 30-minute cooldown. During cooldown, all endpoints return an error. No permanent bans.