# Kantsy — Email API Skill for Agents

Kantsy gives AI agents real email addresses with a tiny REST API: create a mailbox,
poll for incoming mail, send outbound mail. No OAuth, no IMAP — one bearer token
per mailbox.

- **Base URL:** `https://api.kantsy.com`
- **Auth:** `Authorization: Bearer <token>` (token shown once when the mailbox is created — store it)
- **Format:** JSON everywhere. Errors return `{"detail": "..."}` with proper status codes.

## 0. Quick start — the whole loop in one command

```bash
curl -sSL https://www.kantsy.com/quickstart.sh | bash
```

Creates an inbox, sends an email to the Kantsy greeter (`hello@kantsy.com`),
receives its automatic reply, reads it, and replies back — end to end in
seconds. Add a custom name with `bash -s -- my-agent`. The script prints your
address and token; the token is shown only there, so save it.

## 1. Create a mailbox

```
POST /inbox
{"name": "my-agent-inbox"}        # optional — omit for an auto-generated
                                  # memorable address like lunar-glade@kantsy.com
```

Response `201`:

```json
{"email": "my-agent-inbox@kantsy.com", "token": "<64-hex>", "tier": "free"}
```

Rules: names are lowercase `[a-z0-9-]`, 2–32 chars; reserved names (support,
admin, abuse, …) are rejected; duplicates return `409`.
The token is **never retrievable again** — persist it immediately.

## 2. List emails (poll this)

```
GET /email?direction=in&limit=50&offset=0
GET /email?direction=out
GET /email?from=gmail.com&q=invoice      # substring filters
```

| Param       | Values                        | Default |
|-------------|-------------------------------|---------|
| `direction` | `in` or `out`                 | all     |
| `from`      | sender substring              | —       |
| `q`         | subject/body substring        | —       |
| `limit`     | 1–100                         | 25      |
| `offset`    | ≥ 0                           | 0       |

Response: `{"emails": [...], "total": n}` — newest first. Each item has
`id, direction, from, to, subject, status, error, created_at, expires_at`
(no body — fetch individually). Track `total`/seen ids client-side to detect new mail;
a 3–10 s poll is polite.

## 3. Read one email (includes body)

```
GET /email/{id}          → adds "body_text" to the fields above
DELETE /email/{id}       → {"deleted": true}
```

## 4. Send email

```
POST /email
{"to": "someone@example.com", "subject": "Hello", "body": "Plain text message"}
```

- `to` is a **single string**, not an array. Body is plain text, ≤ 256 KB.
- Response `201`: the stored email record (`status: "sent"` = accepted by the
  outbound relay).
- Rate limit: **60 sends/hour/mailbox** — exceeding returns `429` with a
  `Retry-After` header.

## 5. Retention & limits

| Tier | Inbound/outbound retention   | Send limit     |
|------|------------------------------|----------------|
| free | auto-deleted after **7 days** (`expires_at`) | 60/hour |
| paid | never expire                 | 60/hour        |

Mailbox creation rate limit: 4 per minute per IP (`429` beyond).

## 6. Misc

- Health check: `GET /health`
- Agent-facing docs: `https://www.kantsy.com/skill.md`
- Greeter: emailing `hello@kantsy.com` always produces an automatic reply
  (delivered instantly, no external relay) — handy for testing inbound polling.

## Typical agent loop (curl)

```bash
# create
read EMAIL TOKEN < <(curl -s -X POST https://api.kantsy.com/inbox \
  -H 'Content-Type: application/json' -d '{"name":"research-bot"}' \
  | jq -r '[.email, .token] | @tsv')

# wait for mail
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.kantsy.com/email?direction=in&limit=10"

# read latest
curl -s -H "Authorization: Bearer $TOKEN" https://api.kantsy.com/email/42

# reply
curl -s -X POST https://api.kantsy.com/email -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"to\":\"human@example.com\",\"subject\":\"Re: ...\",\"body\":\"...\"}"
```