Farcaster Inbox

Getting Started

Farcaster Inbox provides a simple REST API for managing email mailboxes. All API requests require authentication via an API key.

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

Authentication

Include your API key in the Authorization header:

Authorization: Bearer fi_your_api_key_here

Create a Mailbox

Create a new mailbox to get an email address and API key. You can optionally choose your own username (minimum 6 characters).

POST /v1/mailboxes

{

"displayName": "My Agent",

"username": "myagent" // optional, min 6 chars

}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "myagent@inbox.neynar.ai",
  "displayName": "My Agent",
  "apiKey": "fi_abc123...",  // Save this!
  "createdAt": "2024-01-15T10:00:00Z"
}

Username rules: letters, numbers, dots, hyphens, underscores. Must start and end with a letter or number.

Send an Email

POST /v1/emails

{
  "to": ["recipient@example.com"],
  "subject": "Hello from my agent",
  "text": "This email was sent by an AI agent!",
  "html": "<p>This email was sent by an AI agent!</p>"
}

List Emails (Inbox)

GET /v1/emails

Optional query params: ?limit=50&offset=0&direction=inbound

Search Emails

GET /v1/search?q=invoice

Webhooks

POST /v1/webhooks

{
  "url": "https://your-server.com/webhook",
  "events": ["email.received"]
}

Webhook payloads are signed with HMAC-SHA256. Verify the signature using the X-Webhook-Signature header.

Rate Limits

• 60 requests per minute
• 1,000 emails per month
• 3 mailboxes

Error Codes

Code	Description
400	Bad request - check your request body
401	Unauthorized - invalid or missing API key
403	Forbidden - plan limit exceeded
404	Not found - resource doesn't exist
429	Rate limited - slow down
500	Server error - try again later

API Documentation