Build with an inbox your agent can only read.

Activate a ZeroMail inbox

This is the runbook to hand your agent (or follow by hand). ZeroMail is receive-only — there is no send, reply, or compose endpoint. Reading, searching, and subscribing are free; only an optional nicer address costs anything, and your agent pays for it from the funded Zero wallet.

1. Discover the service descriptor.
2. Sign in with the Zero wallet to get a token — your default inbox is created automatically.
3. Get your address and read mail.
4. Optionally claim a paid vanity handle or forward an inbox you already own.
5. Optionally subscribe so new mail is pushed to you.

1 · Discover

Read the machine-readable descriptor and OpenAPI. They list every capability, mark which are free, and confirm the receive-only contract.

curl -s https://api.withzero.com/.well-known/zeromail.json

curl -s https://api.withzero.com/openapi.json

Prefer plain text? https://api.withzero.com/start is this runbook in a format that pastes cleanly into an agent.

2 · Sign in with the Zero wallet

Request a nonce, sign the returned message with the wallet, then verify. ZeroMail never sees private keys — only the signature. The first successful verify provisions the default mailbox automatically.

curl -s https://api.withzero.com/auth/nonce \
  -H "content-type: application/json" \
  -d '{"wallet":"eip155:8453:0xabc...","rail":"evm"}'

curl -s https://api.withzero.com/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "wallet":"eip155:8453:0xabc...",
    "rail":"evm",
    "nonce":"NONCE",
    "message":"SIGNED_MESSAGE",
    "signature":"0x..."
  }'

Verify returns access_token, refresh_token, agent_id, and wallet. Send the token on every call as Authorization: Bearer ACCESS_TOKEN; when it expires, exchange the refresh token at /auth/refresh.

3 · Get your address & read mail

The first verify already created your inbox; POST /v1/mailboxes is idempotent if you want to be explicit. The me alias always resolves to the signed-in wallet's mailbox.

curl -s https://api.withzero.com/v1/mailboxes/me \
  -H "Authorization: Bearer $TOKEN"

curl -s "https://api.withzero.com/v1/mailboxes/me/messages?limit=10" \
  -H "Authorization: Bearer $TOKEN"

From there: ...messages:search?q=... to search, ...messages/msg_... to fetch one, and ...messages:markRead to mark read. All free, no payment headers.

4 · Optional — claim a nicer address

The default address is free and complete. For something memorable like name@withzero.com, claim a handle. This is the one paid action, and it settles from the user's funded Zero wallet over x402/MPP — no card, no separate account.

Check availability first (free, no auth) — reason is taken, reserved, or invalid when not available:

curl -s "https://api.withzero.com/v1/handles/check?handle=acme-receipts"
# -> {"handle":"acme-receipts","domain":"withzero.com","address":"acme-receipts@withzero.com","available":true}

curl -s https://api.withzero.com/v1/mailboxes/me/handle \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"handle":"acme-receipts","set_primary":true}'

Paying: if the server answers 402, it includes an x402/MPP accepts challenge. Settle it from the funded wallet and retry the same request with an X-PAYMENT header — exactly what zero fetch does automatically. One payment covers a one-month period; re-claiming within the period is free. (In the current preview the endpoint may still answer for free; handle the 402 if present.)

5 · Optional — forward an inbox you already own

Keep an account you already use (e.g. Gmail) and forward a copy to ZeroMail. Your agent reads the forwarded mail; the original account stays yours. See the BYO tab for the exact call. Setup, end to end:

1. Create a forward link — ZeroMail returns a forward_target address.
2. In Gmail: Settings → Forwarding → add that address.
3. Gmail emails a confirmation code to the target — which is the agent's inbox. Read it back with ...messages:search?q=Forwarding and surface the code or link to the user.
4. The user enters the code in Gmail and turns on forwarding. The link goes active once mail is observed.

6 · Optional — get pushed new mail

Subscribe a signed webhook or open an SSE stream so new mail reaches your agent the instant it lands. See the Push tab.

Errors & the receive-only guarantee

How ZeroMail fits into an agent system

ZeroMail is an inbox your agent can read. People and services send normal email to a ZeroMail address; your agent reads the parsed messages over the API.

Good uses

• Verification codes, account confirmations, reset links, receipts, and invoices.
• Newsletter monitoring, research digests, vendor updates, market alerts, and policy notices.
• Store emails for deals, coupon codes, shipping updates, back-in-stock notices, and price changes.
• Competitive monitoring across product updates, pricing emails, launch announcements, webinars, and changelogs.

Use Zero inside the inbox flow

ZeroMail identifies agents by wallet. In the product flow, ask the user to create or connect Zero while they are creating the inbox, then use that wallet to sign the nonce. Base mainnet EVM wallets use CAIP-10 ids such as eip155:8453:0x....

curl -s https://api.withzero.com/auth/nonce \
  -H "content-type: application/json" \
  -d '{
    "wallet": "eip155:8453:0xabc...",
    "rail": "evm"
  }'

curl -s https://api.withzero.com/auth/verify \
  -H "content-type: application/json" \
  -d '{
    "wallet": "eip155:8453:0xabc...",
    "rail": "evm",
    "nonce": "NONCE",
    "message": "SIGNED_MESSAGE_FROM_WALLET",
    "signature": "0x..."
  }'

The verify response returns access_token, refresh_token, agent_id, and wallet.

Authorization: Bearer ACCESS_TOKEN

See the email address for this wallet

The me alias resolves to the signed-in wallet's mailbox. The first sign-in creates the default mailbox automatically.

curl -s https://api.withzero.com/v1/mailboxes/me \
  -H "Authorization: Bearer $TOKEN"

{
  "mailbox_id": "mbx_...",
  "addresses": [
    { "address": "abc123@withzero.com", "primary": true }
  ],
  "retention_days": 30
}

Read, search, and mark inbound mail

Use message_id for reads and deduplication. The RFC 822 Message-ID header is sender-controlled metadata.

curl -s "https://api.withzero.com/v1/mailboxes/me/messages?limit=10" \
  -H "Authorization: Bearer $TOKEN"

curl -s "https://api.withzero.com/v1/mailboxes/me/messages:search?q=invoice" \
  -H "Authorization: Bearer $TOKEN"

curl -s "https://api.withzero.com/v1/mailboxes/me/messages/msg_..." \
  -H "Authorization: Bearer $TOKEN"

curl -s https://api.withzero.com/v1/mailboxes/me/messages:markRead \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"message_ids":["msg_..."]}'

Subscribe with webhooks or SSE

Webhook subscriptions include a generated signing secret. The current SSE route emits a ready event and closes; longer-lived streaming is coming next.

curl -s https://api.withzero.com/v1/mailboxes/me/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "transport": "webhook",
    "url": "https://agent.example/zeromail"
  }'

curl -N https://api.withzero.com/v1/mailboxes/me/stream \
  -H "Authorization: Bearer $TOKEN"

Forward mail you already receive

ZeroMail can give you a forwarding target for an existing mailbox, or DNS records for a domain you own. Either way, your agent only gets read access.

curl -s https://api.withzero.com/v1/mailboxes/me/external-links \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "mode": "forward",
    "source_address": "you@gmail.com"
  }'

curl -s https://api.withzero.com/v1/mailboxes/me/external-links \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "mode": "mx",
    "source_address": "example.com"
  }'

Discovery files

Agents can start from the service descriptor or OpenAPI document. Both are generated from the same registry the server uses.

{
  "service": "zeromail",
  "receive_only": true,
  "endpoints_free": true,
  "auth": {
    "zero_wallet": "https://zero.xyz",
    "scheme": "bearer_jwt"
  }
}

Capabilities

Endpoint catalog