API Documentation

Integrate OpenInbox.io into your applications with our powerful REST API. Create inboxes, fetch emails, and set up webhooks programmatically.

API access requires Pro, Business, Premium, or 7-Day PassUpgrade Now →

Quick Start

1. Get API Key

Upgrade to Pro/Business/Premium/7-Day Pass and generate your API key in Settings.

2. Make Requests

Include your API key in the X-API-Key header with each request.

3. Handle Responses

All responses are JSON formatted with consistent structure.

Base URL

https://api.openinbox.io/api

Authentication

All API requests require authentication via the X-API-Key header.

curl -X GET "https://api.openinbox.io/api/v1/inboxes" \
  -H "X-API-Key: tmp_your_api_key_here"

Premium accounts can create up to 5 labeled API keys, each individually revocable, managed in the dashboard under Settings → API Keys. All keys authenticate with the same X-API-Key header.

Rate Limits & Tiers

Tier	Price	API Access	Daily Limit
Free	$0	✗ No	—
7-Day Pass	$2 one-time	✓ Yes	3,000 req/day
Pro	$7/mo	✓ Yes	3,000 req/day
Business	$15/mo	✓ Yes	10,000 req/day
Premium	$29/mo	✓ Yes	10,000 req/day

Rate Limit Headers

Each response includes rate limit headers:X-RateLimit-Limit: 100 X-RateLimit-Remaining: 85 X-RateLimit-Reset: 1704153600

Error Handling

All errors follow a consistent format with appropriate HTTP status codes:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API key

403Forbidden - API access not available on your plan

404Not Found - Resource does not exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error

Webhook Events

Subscribe to the following events to receive real-time notifications:

email.receivedTriggered when a new email arrives in an inbox

inbox.createdTriggered when a new inbox is created

inbox.expiredTriggered when an inbox expires

Webhook Payload Example

{
  "event": "email.received",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "emailId": "uuid",
    "inboxId": "uuid",
    "from": "[email protected]",
    "subject": "Hello!"
  }
}

Premium accounts can register up to 5 webhook endpoints and route incoming emails between them with routing rules (see below). Webhook behavior on Pro and Business plans is unchanged.

Webhook Routing Rules (Premium)

Premium accounts can create routing rules that decide which of your webhook endpoints receives each incoming email. Routing rules are a dashboard feature managed in Settings → Webhooks (authenticated with your dashboard session, not the X-API-Key public API), and include a built-in rule tester.

Rule Model

{
  "id": "uuid",
  "name": "Route signups to CRM",
  "webhookId": "uuid",
  "conditions": [
    {
      "field": "subject",
      "operator": "contains",
      "value": "welcome"
    },
    {
      "field": "from",
      "operator": "ends_with",
      "value": "@example.com"
    }
  ],
  "isEnabled": true,
  "createdAt": "2024-01-01T10:00:00Z"
}

FieldsConditions match on subject, from, or to.

Operatorscontains, equals, starts_with, ends_with — all case-insensitive, no regex.

MatchingAll conditions in a rule must match (AND-combined). An email that matches multiple rules is delivered to every matching rule’s webhook.

FallbackA rule with no conditions always matches, acting as a catch-all fallback.

LimitsUp to 20 rules per account, up to 5 conditions per rule.

The webhook delivery payload is identical regardless of which rule routed the email — the same email.received payload shown above.

API Endpoints

Inboxes

Emails

Webhooks

Account

Ready to Get Started?

Upgrade to Pro, Business, or Premium, or get a 7-Day Pass to unlock API access and integrate OpenInbox.io into your applications.

View Pricing Plans