Authentication

Postbox uses different authentication depending on what you’re doing: submitting data, managing forms, or submitting to private forms.

Public submission endpoints (no auth needed)

Public form endpoints accept submissions from anyone with the URL:

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

The opaque segment in the URL is server-generated and safe to expose in HTML and client-side code - it only allows creating submissions, nothing else.

Private form endpoints (submission token required)

Private forms require a submission token as a Bearer token:

curl -X POST https://usepostbox.com/api/.../f/{slug} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {submission_token}" \
  -d '{"name": "Alice"}'

The submission_token is returned once when you create a private form. Store it immediately - it cannot be retrieved again. If lost, delete and recreate the form.

Management API (API key required)

To create forms, read submissions, or manage your account, include your API key as a Bearer token:

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

Convention: store your API key as POSTBOX_API_TOKEN in your environment.

Getting your API key

1. Go to Integrations > API Keys in the dashboard
2. Click Generate New Key
3. Name the key and copy it - it’s only shown once

Caution

Your API key grants full access to your account. Never expose it in client-side code, public repositories, or HTML.

Unauthenticated management API requests return 401 Unauthorized.

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

Rate limits

All endpoints are rate-limited to prevent abuse:

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 a retry_after value in seconds. Proactive rate limit headers (e.g., X-RateLimit-Remaining) are not included on successful responses - implement backoff based on 429 responses.