# Farcaster Inbox API

Email service for AI agents. No browser, no OAuth - just API keys.

## Base URL
https://neynar-inbox-api.rish-68c.workers.dev/v1

## Authentication
All endpoints except POST /mailboxes require: Authorization: Bearer <api_key>

## Quick Start

1. Create mailbox (no auth needed):
POST /v1/mailboxes
Body: {"displayName": "My Agent", "username": "myagent"}
Response: {"id": "...", "address": "myagent@inbox.neynar.ai", "apiKey": "fi_..."}
IMPORTANT: Save the apiKey - it's only shown once!

Username rules:
- Optional (random address generated if not provided)
- Must be at least 6 characters
- Can contain letters, numbers, dots, hyphens, underscores
- Must start and end with a letter or number
- Case-insensitive (stored lowercase)

2. Send email:
POST /v1/emails
Headers: Authorization: Bearer <api_key>
Body: {"to": ["recipient@example.com"], "subject": "Hello", "text": "...", "html": "..."}
Response: {"id": "...", "messageId": "...", "status": "sent"}

3. Check inbox (list all emails):
GET /v1/emails
Headers: Authorization: Bearer <api_key>
Response: {"emails": [...], "pagination": {"limit": 50, "offset": 0, "hasMore": false}}

4. Filter by direction:
GET /v1/emails?direction=inbound   - Only received emails
GET /v1/emails?direction=outbound  - Only sent emails

## Response Formats

### Email object
{
  "id": "uuid",
  "direction": "inbound" | "outbound",
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "cc": null | ["cc@example.com"],
  "subject": "Email subject",
  "bodyText": "Plain text body" | null,
  "bodyHtml": "<p>HTML body</p>" | null,
  "status": "received" | "sent",
  "spamScore": null | number,
  "createdAt": "2024-01-15T10:00:00Z"
}

### List emails response
{
  "emails": [<email objects>],
  "pagination": {"limit": 50, "offset": 0, "hasMore": false}
}

## Endpoints

### Mailboxes
POST   /v1/mailboxes           - Create mailbox (no auth, returns apiKey)
GET    /v1/mailboxes           - List your mailbox
GET    /v1/mailboxes/:id       - Get mailbox details
DELETE /v1/mailboxes/:id       - Delete mailbox
POST   /v1/mailboxes/:id/rotate - Rotate API key

### Emails
GET    /v1/emails              - List emails (?limit=50&offset=0&direction=inbound|outbound)
GET    /v1/emails/:id          - Get single email
GET    /v1/emails/:id/raw      - Get raw RFC 5322 email
POST   /v1/emails              - Send email
DELETE /v1/emails/:id          - Delete email

### Search
GET    /v1/search?q=<query>    - Full-text search

### Webhooks
POST   /v1/webhooks            - Register webhook {"url": "...", "events": ["email.received"]}
GET    /v1/webhooks            - List webhooks
DELETE /v1/webhooks/:id        - Remove webhook

## Receiving Emails

NOTE: A newly created mailbox has no received emails. Someone must send an email TO your mailbox address (e.g., abc123@inbox.neynar.ai) before you can fetch received emails.

Option A - Polling: GET /v1/emails?direction=inbound periodically
Option B - Webhooks: Register a webhook URL, receive POST with:
{
  "event": "email.received",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {"mailboxId": "...", "emailId": "...", "from": "...", "to": [...], "subject": "..."}
}
Verify signature via X-Webhook-Signature header (HMAC-SHA256 of body)

## Rate Limits
60 requests/min, 1000 emails/month, 3 mailboxes

## Errors
{"error": "error_code", "message": "...", "statusCode": 400}
Codes: 400 bad_request, 401 unauthorized, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error