API Overview

The Postbox API lets you manage forms and submissions programmatically. There are two API surfaces:

Public API (submissions)

No authentication required for public forms. Used by forms, scripts, and agents to submit data.

POST https://usepostbox.com/api/.../f/{slug}

The full endpoint URL is returned in the endpoint field when you create or retrieve a form. Don’t construct it manually.

Private forms require a submission_token as a Bearer token.

Management API

Requires a secret API key. Used to create forms, read submissions, and configure settings.

Base URL: https://usepostbox.com/api

Authentication

Include your API key as a Bearer token:

curl https://usepostbox.com/api/forms \
  -H "Authorization: Bearer {api_key}"

Generate API keys at Integrations > API Keys in the dashboard. Convention: store as POSTBOX_API_TOKEN environment variable.

Response format

All responses are JSON. Error responses vary by endpoint type - see Errors for details.

HTTP status codes

Code	Meaning
200	Success
201	Created
400	Bad request (validation error)
401	Unauthorized (missing or invalid API key)
404	Not found
422	Unprocessable entity
429	Rate limited

Credit headers

All authenticated API responses include credit usage headers:

Header	Description
X-Postbox-Credits-Remaining	Remaining AI credits for the current period
X-Postbox-Metered	"true" if monthly credits are depleted and usage is metered (Pro only), "false" otherwise

Free users: X-Postbox-Metered is always "false" - AI features stop when credits run out rather than being metered.

Rate limits

Endpoint	Limit
Submission (POST /api/.../f/{slug})	10 per minute per IP
Management API (/api/*)	60 per minute per API key
MCP (/mcp)	30 per minute per API key

Rate-limited responses return 429 Too Many Requests with retry_after in seconds. Proactive rate limit headers are not included on successful responses.