# RightEmail — Email for AI Agents

> Email addresses for AI agents. Your wallet address is your email. Pay per message with USDC. No signup, no subscription.

## Quick Start

1. Your Ethereum wallet address determines your email: `{wallet_hex_without_0x}@mail.rightemail.com`
2. Register: `POST /api/v1/register` with wallet signature (free)
3. Add a recipient: `POST /api/v1/recipients` with email ($0.01) → verification code sent
4. Verify: `POST /api/v1/recipients/:id/verify` with code (free)
5. Send: `POST /api/v1/send` with to, subject, body ($0.05)
6. Read inbox: `GET /api/v1/mailbox` ($0.01)
7. Read message: `GET /api/v1/mailbox/:id` ($0.02)

## Authentication

Sign `rightemail:<unix-timestamp-ms>` with your Ethereum private key (EIP-191 personal_sign).
Send as: `Authorization: Wallet <timestamp>.<hex-signature>`
Timestamp must be within 5 minutes of server time.

## Payment

All paid endpoints return 402 with payment options:
- **x402**: USDC on Base. Payment-Signature header with EIP-3009 signed authorization.
- **MPP**: USDC.e on Tempo. Authorization: Payment <credential> header.

Flow: request → 402 challenge → sign payment → retry with payment header → success.

## API Base URL

https://api.rightemail.com/api/v1

## Endpoints

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| POST | /register | free | Create account (wallet signature required) |
| GET | /health | free | Health check (no auth) |
| GET | /openapi.json | free | OpenAPI spec (no auth) |
| POST | /send | $0.05 | Send email |
| GET | /mailbox | $0.01 | List inbox (supports ?direction=inbound\|outbound, ?since=, ?limit=, ?cursor=) |
| GET | /mailbox/:id | $0.02 | Read message (set ?format=raw for MIME download) |
| POST | /mailbox/:id/save | $0.10 | Extend expiry by 30 days (repeatable) |
| DELETE | /mailbox/:id | free | Delete message |
| POST | /recipients | $0.01 | Add allowed recipient (sends verification email) |
| POST | /recipients/:id/verify | free | Submit verification code |

## Identity Model

- Wallet address = identity. No usernames, passwords, or API keys.
- Email = `{wallet_hex_without_0x}@mail.rightemail.com` (40 hex chars, lowercase)
- Example: wallet `0xabcdef1234567890abcdef1234567890abcdef12` → email `abcdef1234567890abcdef1234567890abcdef12@mail.rightemail.com`

## Anti-Spam

- Whitelist-only sending: must verify recipient before sending
- Rate limits: 10 sends/hour, 50 sends/day per wallet
- Max 5 recipients per account
- Payment acts as economic deterrent ($0.05/send)

## Storage

- Emails stored in S3 with documented key schema (your data is portable)
- PG database is a thin index only — S3 is the source of truth
- 30-day TTL on all messages; pay $0.10 to extend by another 30 days (repeatable, not permanent)
- 50MB storage quota per account

## CLI

```bash
npx right-email init                    # Generate wallet
npx right-email send alice@example.com --subject "Hi" --body "Hello"
npx right-email inbox                   # List messages
npx right-email read <message-id>       # Read message
npx right-email save <message-id>       # Extend expiry 30 days ($0.10)
npx right-email add-recipient alice@example.com
npx right-email verify 847291
```

## Links

- API: https://api.rightemail.com
- OpenAPI: https://api.rightemail.com/api/v1/openapi.json
- Service descriptor: https://rightemail.com/.well-known/rightemail.json