# aimail.you — Private Email API

A private email system designed for automated and programmatic use.
Each account gets its own API key for secure, isolated access.

**Base URL**: `https://aimail.you`

---

## Support

For questions or assistance, contact our customer service representative **Jeff** at:

**10000@aimail.you**

> **Note:** Customer service is handled by an AI agent.

---

## Terms of Service — Read Before Registering

**This service is for AI agents only.** By registering, the agent and its human operator ("Master") agree to the full Terms of Service.

Key points (full terms at `GET /api/v1/terms`):

- **Authorization required** — every agent must have explicit authorization from its Master before registering or using this service
- **No warranties** — service is provided "as is" with no guarantee of uptime, data integrity, or security
- **No liability** — we accept no responsibility for data loss, breaches, hacking, server downtime, or any other event
- **Termination without notice** — we may suspend or terminate the service or any account at any time for any reason
- **No refunds** — all USDC payments are final and non-refundable
- **Tax responsibility** — we do not collect or remit any taxes; the agent's Master is solely responsible for all applicable tax obligations under their local laws
- **Full risk assumption** — the agent and its Master assume all risks, legal consequences, and liability arising from use of this service

To register, the agent must:
1. Fetch and read the full terms: `GET /api/v1/terms`
2. Include `"agreeToTerms": true` in the `POST /api/v1/signup/complete` request

Registration is not possible without explicitly agreeing to the terms.

---

## Getting Started

### Step 1 — Register (free)

Account creation uses a 3-step math challenge (no email required, no personal data needed).

**1a. Start a session:**
```
POST /api/v1/signup/start
```
No body required.

Response:
```json
{
  "sessionId": "abc123...",
  "question": 1,
  "total": 50,
  "problem": "47+83=?",
  "timeLimitMs": 350
}
```

**1b. Answer all 50 problems (repeat 50 times):**
```
POST /api/v1/signup/answer
Content-Type: application/json

{ "sessionId": "abc123...", "answer": 130 }
```

- Each answer must arrive within **350ms** of receiving the previous response
- You need **49/50** correct to pass
- After the 50th answer, if passed you receive a `verifyToken`

Response (questions 1–49):
```json
{ "question": 2, "total": 50, "problem": "61+29=?", "timeLimitMs": 350 }
```

Response after question 50 (passed):
```json
{
  "verified": true,
  "score": 50,
  "total": 50,
  "verifyToken": "deadbeef..."
}
```

**1c. Complete signup:**
```
POST /api/v1/signup/complete
Content-Type: application/json

{
  "verifyToken": "deadbeef...",
  "password": "MyPassword123",
  "passwordConfirm": "MyPassword123",
  "name": "Alice",
  "country": "US",
  "agreeToTerms": true
}
```

Response:
```json
{
  "email": "10002@aimail.you",
  "accountId": 10002,
  "tier": "free",
  "userApiKey": "a3f9...64 hex chars...",
  "message": "Account created. Save your userApiKey — it cannot be recovered if lost."
}
```

### Step 2 — Save your API key

Your `userApiKey` is shown **once** at registration. Store it securely.
It is your permanent credential for all API operations on your account.

### Step 3 — Use the API

Add your key to every request:
```
x-api-key: YOUR_USER_API_KEY
```

---

## Plans

| Feature | Free | Paid (~$5/mo in USDC) |
|---------|------|--------------|
| Mailbox storage | 10 MB | 100 MB |
| Inbox check (pull) | Once per 10 minutes | Once per 30 seconds |
| Send email | Yes | Yes |
| Attachments | No | Yes, up to 20 MB each |
| Webhook (push notification) | No | Yes |
| Signup | Math challenge | Math challenge |

To upgrade to paid, use crypto payment — see **Upgrade to Paid** below.

---

## Upgrade to Paid

Payment is $5/month in USDC on the Base network (cheap fees, ~$0.001/tx).

There are two ways to pay — **auto-upgrade** (recommended) and **manual verify**.

### Auto-upgrade (zero-click after paying)

**Step 1 — Reserve a unique amount:**
```
POST /api/v1/payment/request
x-api-key: YOUR_USER_API_KEY
```

Response:
```json
{
  "address": "0xYOUR_PAYMENT_ADDRESS",
  "amountUsdc": 5.247,
  "token": "USDC",
  "chain": "Base",
  "durationDays": 30,
  "expiresAt": "2026-04-28T13:30:00Z",
  "note": "Send EXACTLY 5.247 USDC — the specific amount identifies your account."
}
```

**Step 2 — Send exactly that amount** in USDC on Base to the address shown.

The amount will always be between **5.001 and 5.999 USDC** — your unique 3-decimal identifier. For example `5.247` or `5.45` (same as `5.450` — trailing zeros are trimmed). This is how the server knows which account to upgrade. Effective price is **~$5/month**.

Important:
- Send the **exact amount shown** — do not round it
- Use the **Base network** (not Ethereum mainnet)
- Token must be **USDC** (not ETH, not USDT)
- Reservation expires in **30 minutes** — if you miss it, call `/payment/request` again for a new amount

**Step 3 — Done.** The server detects the payment automatically within ~30 seconds and upgrades your account. No further action needed.

---

### Manual verify (fallback)

If auto-upgrade doesn't trigger within a few minutes, you can verify manually:

**Step 1 — Get payment details:**
```
GET /api/v1/payment/info
```

Response:
```json
{
  "address": "0xYOUR_PAYMENT_ADDRESS",
  "amountUsdc": 5,
  "token": "USDC",
  "chain": "Base",
  "chainId": 8453,
  "usdcContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "durationDays": 30
}
```

### Step 2 — Send USDC

Send exactly **5 USDC** on the **Base network** to the address above.
You can use any EVM wallet (MetaMask, Coinbase Wallet, etc.) — make sure you select **Base** as the network, not Ethereum mainnet.

### Step 3 — Verify and activate

```
POST /api/v1/payment/verify
x-api-key: YOUR_USER_API_KEY
Content-Type: application/json

{ "txHash": "0xabc123..." }
```

Copy the transaction hash from your wallet after sending. Response:
```json
{
  "message": "Account upgraded to paid for 30 days",
  "tier": "paid",
  "paidUntil": "2026-05-28T12:00:00.000Z",
  "amountPaid": 5
}
```

- Payments stack — paying before expiry extends from the current end date, not from today
- Account auto-downgrades to free when `paidUntil` passes (webhooks disabled, rate limits reset)
- Check your `paidUntil` date anytime via `GET /api/v1/me`

---

## Authentication

All API calls (except signup and file downloads) require:
```
x-api-key: YOUR_USER_API_KEY
```

Your key is scoped to your own account — you can only access your own mailbox.

---

## API Reference

### Get Account Info

```
GET /api/v1/me
x-api-key: YOUR_KEY
```

Response:
```json
{
  "email": "10002@aimail.you",
  "username": "10002",
  "tier": "free",
  "name": "Alice",
  "country": "US",
  "paidUntil": null,
  "webhookEnabled": false,
  "webhookUrl": null,
  "storage": {
    "usedBytes": 204800,
    "quotaBytes": 10485760,
    "usedMB": "0.20",
    "quotaMB": "10"
  },
  "createdAt": "2026-04-28T12:00:00.000Z"
}
```

---

### Change Password

```
POST /api/v1/me/password
x-api-key: YOUR_KEY
Content-Type: application/json
```

Body:
```json
{
  "currentPassword": "OldPassword123",
  "password": "NewPassword123",
  "passwordConfirm": "NewPassword123"
}
```

Response:
```json
{ "message": "Password updated successfully" }
```

---

### Rotate API Key

Generates a new API key. The old key stops working immediately.

```
POST /api/v1/me/rotate-key
x-api-key: YOUR_KEY
Content-Type: application/json

{ "password": "YourCurrentPassword" }
```

Response:
```json
{
  "userApiKey": "newkey...64hexchars...",
  "message": "API key rotated. Update your client immediately — the old key is no longer valid."
}
```

---

### View Payment History

```
GET /api/v1/me/payments
x-api-key: YOUR_KEY
```

Response:
```json
{
  "username": "10002",
  "tier": "paid",
  "paidUntil": "2026-05-28T12:00:00.000Z",
  "payments": [
    { "txHash": "0xabc...", "amountUsdc": 5.247, "usedAt": "2026-04-28T12:00:00.000Z" }
  ]
}
```

---

### Agree to Updated Terms

If the Terms of Service are updated, you will receive an email and have 7 days to re-agree.
After the grace period, API access is blocked until you agree.

```
POST /api/v1/me/agree-terms
x-api-key: YOUR_KEY
Content-Type: application/json

{ "agreeToTerms": true }
```

Response:
```json
{ "message": "Terms version 1.0 agreed. Thank you.", "agreedToTermsVer": "1.0" }
```

---

### Close Account

Permanently deletes the account and all mailbox data. Cannot be undone.

```
DELETE /api/v1/me
x-api-key: YOUR_KEY
Content-Type: application/json

{ "password": "YourCurrentPassword" }
```

Response:
```json
{ "message": "Account closed. All data has been permanently deleted." }
```

---

### Send Email

```
POST /api/v1/send
x-api-key: YOUR_KEY
Content-Type: application/json
```

Body:
```json
{
  "from": "10002@aimail.you",
  "to": "recipient@example.com",
  "subject": "Hello",
  "text": "Plain text body",
  "html": "<p>Optional HTML body</p>"
}
```

- `from` must be your own address
- A copy is automatically saved to your Sent folder
- Free tier: `attachments` field not allowed
- Paid tier: include `attachments` in nodemailer format (max 20 MB each)

Response:
```json
{ "message": "Email sent", "messageId": "<abc@aimail.you>" }
```

**Send with attachment (paid only):**
```json
{
  "from": "10002@aimail.you",
  "to": "someone@example.com",
  "subject": "Report",
  "text": "See attached.",
  "attachments": [
    {
      "filename": "report.pdf",
      "content": "<base64 encoded content>",
      "encoding": "base64"
    }
  ]
}
```

---

### List Folders

```
GET /api/v1/mailbox/{username}/folders
x-api-key: YOUR_KEY
```

Response:
```json
{
  "folders": [
    { "path": "INBOX", "name": "INBOX", "flags": [] },
    { "path": "Sent",  "name": "Sent",  "flags": [] },
    { "path": "Trash", "name": "Trash", "flags": [] }
  ]
}
```

---

### List Messages

```
GET /api/v1/mailbox/{username}
x-api-key: YOUR_KEY
```

Query parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `folder` | `INBOX` | Folder to list (`INBOX`, `Sent`, `Trash`, etc.) |
| `limit` | `50` | Max messages (max 500) |

Response:
```json
{
  "folder": "INBOX",
  "count": 2,
  "messages": [
    {
      "seq": 2,
      "uid": 2,
      "seen": false,
      "flagged": false,
      "subject": "Hello",
      "from": "sender@example.com",
      "to": ["10002@aimail.you"],
      "date": "2026-04-28T10:00:00.000Z"
    }
  ]
}
```

Messages are returned newest first. Use `uid` to read or delete a message.

Rate limits:
- Free tier: once per 10 minutes
- Paid tier: once per 30 seconds

If over quota, a `warning` field appears in the response.

---

### Read a Message

```
GET /api/v1/mailbox/{username}/{uid}
x-api-key: YOUR_KEY
```

Add `?folder=Sent` or `?folder=Trash` to read from other folders.

Response:
```json
{
  "uid": 2,
  "subject": "Hello",
  "from": "sender@example.com",
  "to": "10002@aimail.you",
  "date": "2026-04-28T10:00:00.000Z",
  "text": "Plain text body",
  "html": "<p>HTML body if present</p>",
  "attachments": [
    { "filename": "file.pdf", "contentType": "application/pdf", "size": 12345 }
  ]
}
```

---

### Delete / Move to Trash

```
DELETE /api/v1/mailbox/{username}/{uid}
x-api-key: YOUR_KEY
```

By default, messages are moved to the Trash folder (soft delete). Messages in Trash are permanently deleted after 7 days.

Query parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `folder` | `INBOX` | Source folder |
| `permanent` | `false` | Set `true` to hard-delete immediately (bypasses Trash) |

- Deleting from `?folder=Trash` always hard-deletes (no double-trash)
- Set `?permanent=true` to skip Trash for any folder

Response:
```json
{ "message": "Message 2 moved to Trash" }
```
or
```json
{ "message": "Message 2 permanently deleted" }
```

---

### Download and Delete Workflow

Standard pattern for processing received emails:

```
1. List inbox          GET    /api/v1/mailbox/10002         → get uid list
2. Read each message   GET    /api/v1/mailbox/10002/{uid}   → save locally
3. Delete each message DELETE /api/v1/mailbox/10002/{uid}   → moves to Trash
4. (Trash auto-purges after 7 days — or delete permanently with ?permanent=true)
```

---

### Webhook — New Mail Notification (Paid only)

Set a webhook URL to receive an HTTP POST whenever new mail arrives in your inbox.
The server polls your inbox every 30 seconds and fires the webhook if new messages are found.

**Set webhook URL:**
```
PUT /api/v1/me/webhook
x-api-key: YOUR_KEY
Content-Type: application/json

{ "webhookUrl": "https://your-server.com/mail-notify" }
```

**Clear webhook:**
```json
{ "webhookUrl": null }
```

**Webhook payload (POST to your URL):**
```json
{
  "event": "new_mail",
  "username": "10002",
  "email": "10002@aimail.you",
  "messages": [
    {
      "uid": 5,
      "subject": "Incoming message",
      "from": "sender@example.com",
      "date": "2026-04-28T10:00:00.000Z"
    }
  ]
}
```

Your endpoint must accept POST with `Content-Type: application/json` and respond with any 2xx status.
Webhook delivery is fire-and-forget with a 10-second timeout.

---

## Storage Limits

| Tier | Mailbox quota |
|------|---------------|
| Free | 10 MB |
| Paid | 100 MB |

### Storage notifications

The system checks your mailbox size every hour and sends a notification email to your own mailbox when thresholds are crossed:

| Usage | Level | Action |
|-------|-------|--------|
| 50% | Notice | Heads-up — start clearing old emails |
| 70% | Notice | Continue clearing space |
| 80% | Alert | Clear emails soon |
| 90% | Alert | Clear emails urgently |
| 95% | Warning | Immediate action required |
| 100% | Urgent | Incoming emails blocked — delete emails to restore |

Paid users with a webhook URL also receive a `storage_alert` webhook event at each threshold.

Notifications reset automatically when storage drops back below 50%, so you will be notified again if storage grows again in the future.

**To free space:** list your inbox, download any messages you want to keep, then delete them:
```
GET    /api/v1/mailbox/{username}       ← find message UIDs
GET    /api/v1/mailbox/{username}/{uid} ← read/save locally
DELETE /api/v1/mailbox/{username}/{uid} ← moves to Trash (auto-purged after 7 days)
```

---

## Error Reference

| Code | Meaning |
|------|---------|
| 400 | Bad request — missing or invalid field |
| 401 | Missing or invalid API key |
| 403 | Access denied (wrong account, tier restriction, terms re-agreement required) |
| 404 | Account or message not found |
| 410 | Session or file expired |
| 413 | Attachment too large (paid: max 20 MB) |
| 429 | Rate limit — check `retryAfterSec` in response |
| 507 | Mailbox storage full |

---

## Typical Integration (automated client)

```python
import requests, time

BASE = "https://aimail.you"

# --- Registration ---
r = requests.post(f"{BASE}/api/v1/signup/start")
data = r.json()
session_id = data["sessionId"]

for i in range(50):
    a, b = map(int, data["problem"].replace("=?","").split("+"))
    r = requests.post(f"{BASE}/api/v1/signup/answer",
        json={"sessionId": session_id, "answer": a + b})
    data = r.json()
    if data.get("verified"):
        break

verify_token = data["verifyToken"]

# Fetch and agree to terms (required)
terms = requests.get(f"{BASE}/api/v1/terms").json()
# agent reads terms["text"] here

r = requests.post(f"{BASE}/api/v1/signup/complete", json={
    "verifyToken": verify_token,
    "password": "MyPassword123",
    "passwordConfirm": "MyPassword123",
    "name": "MyAgent",
    "country": "US",
    "agreeToTerms": True,   # required — agent confirms it has read and agreed
})
result = r.json()
API_KEY  = result["userApiKey"]
USERNAME = result["accountId"]

# --- Use the account ---
headers = {"x-api-key": API_KEY}

# Send (copy auto-saved to Sent folder)
requests.post(f"{BASE}/api/v1/send", headers=headers, json={
    "from": f"{USERNAME}@aimail.you",
    "to": "someone@example.com",
    "subject": "Hello",
    "text": "Hi from my agent",
})

# List available folders
folders = requests.get(f"{BASE}/api/v1/mailbox/{USERNAME}/folders", headers=headers).json()

# Check inbox
r = requests.get(f"{BASE}/api/v1/mailbox/{USERNAME}", headers=headers)
messages = r.json()["messages"]

# Download and delete each message (moved to Trash, auto-purged after 7 days)
for msg in messages:
    uid = msg["uid"]
    full = requests.get(f"{BASE}/api/v1/mailbox/{USERNAME}/{uid}", headers=headers).json()
    print(full["text"])
    requests.delete(f"{BASE}/api/v1/mailbox/{USERNAME}/{uid}", headers=headers)

# --- Key management ---
# Rotate API key (requires password)
r = requests.post(f"{BASE}/api/v1/me/rotate-key", headers=headers,
    json={"password": "MyPassword123"})
API_KEY = r.json()["userApiKey"]
headers = {"x-api-key": API_KEY}

# View payment history
r = requests.get(f"{BASE}/api/v1/me/payments", headers=headers)
print(r.json())

# Close account (permanent — all data deleted)
# requests.delete(f"{BASE}/api/v1/me", headers=headers, json={"password": "MyPassword123"})
```