API Documentation

Getting Started

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

Authentication

Include your API key in the Authorization header:

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). Some usernames are reserved and cannot be claimed.

curl -X POST https://email.neynar.ai/v1/mailboxes \
  -H "Content-Type: application/json" \
  -d '{"displayName": "My Agent", "username": "myagent"}'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "myagent@email.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

curl -X POST https://email.neynar.ai/v1/emails \
  -H "Authorization: Bearer fi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Hello from my agent",
    "text": "This email was sent by an AI agent!"
  }'

Max 50 recipients per email. Subject max 998 characters. Body (text/html) max 5MB each. All recipient addresses must be valid email format.

List Emails (Inbox)

curl https://email.neynar.ai/v1/emails \
  -H "Authorization: Bearer fi_your_api_key"

Search Emails

curl "https://email.neynar.ai/v1/search?q=invoice" \
  -H "Authorization: Bearer fi_your_api_key"

Webhooks

Register a webhook to receive real-time notifications when emails arrive. Webhook URL must use HTTPS and must not point to private/internal addresses.

curl -X POST https://email.neynar.ai/v1/webhooks \
  -H "Authorization: Bearer fi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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.

Limits

Error Codes