# FormPostbox submission contract (plain Markdown)

This document describes the public HTTP contract for submitting an existing website form to FormPostbox. It is framework-neutral; per-stack reference implementations live in the skill files linked at the bottom.

## Endpoint

`POST https://formpostbox.com/f/{formId}` — one path per form. Replace `{formId}` with the form's id from its FormPostbox page.

## Request

- Content types: `application/json` or `application/x-www-form-urlencoded`. Anything else answers `415`.
- Reference implementations use `fetch` with `Accept: application/json` so they can confirm `saved: true`. A native browser form post instead redirects on save and shows an HTML error page when rejected; it does not provide the JSON confirmation flow.
- Fields: any set of named string fields. Required:
  - `_intent_id` — 16–128 characters. Created once per message; reused on network retries (idempotent); renewed after a confirmed save or a new message.
  - On a protected site, `cf-turnstile-response` — the single-use Cloudflare Turnstile token. An unprotected site needs no token; if the field is supplied, a response up to 2048 characters is ignored. Longer responses exceed the request limit and are rejected.
- The page must run on an exact origin from the form's allowed origins; scheme, hostname and port must match (no wildcards). `Origin` is checked on every request, including each retry.
- A disallowed origin can appear in the browser as a CORS or network error because the browser may hide the response. Check the page's scheme, hostname and port against the allowed origins; the FormPostbox form page shows the rejected origin. After correcting it, retry with the same intent.
- Limits: business field names are 1–128 characters; at most 50 business fields (excluding `_intent_id` and `cf-turnstile-response` in all cases); each value is at most 32768 characters; JSON and URL-encoded request bodies are at most 65536 bytes (`413` if larger); normalized business-fields JSON is also at most 65536 bytes; a supplied `cf-turnstile-response` is at most 2048 characters; protected sites require a non-empty token (1–2048 characters).

## Response

Saved (new message): `201`

```json
{"saved":true,"id":"…","replayed":false,"notification":"queued"}
```

Saved (retry of the same intent and payload): `200` with `"replayed":true` and the original `id`; no duplicate record and no extra usage.

Rejected: `{"saved":false,"error":"…"}`

| Status | error | Meaning |
|---|---|---|
| `400` | invalid | Body is not valid JSON/an object, or a field violates the limits |
| `400` | origin | The page's origin is not in the form's allowed origins |
| `400` | captcha | On a protected site, the Turnstile token is missing, used, expired or failed |
| `400` | paused | The form is not enabled |
| `400` | configuration | An enabled notification recipient is not verified, or the protection settings changed while the request was in progress |
| `404` | not_found | Unknown form id |
| `404` | expired | The referenced record is deleted or past retention |
| `409` | conflict | The same intent was reused with changed content. Restore the original content to replay it while the submission is retained. For a genuinely new message, the user must explicitly start it and create a new intent. |
| `413` | too_large | Request body over 65536 bytes |
| `415` | unsupported | Content type is not JSON or form-urlencoded |
| `429` | quota | The workspace has no submission allowance left this month |
| `429` | rate_limit | The request rate was exceeded; retry later |
| `503` | unavailable | Temporary; retry later |

`notification` describes the email side: `queued` on a new save with email notifications enabled, `off` when disabled, and `unchanged` on a replay. Saved does not mean the email was delivered.

## Capability boundaries

- Browser integration uses public values only — no API key and no server-side proxy.
- Attachments, multipart uploads and non-string field values are not supported.
- A submission is accepted only while the form is enabled and the origin matches exactly. Protection is optional per site: a protected site requires a valid, single-use Turnstile response; an unprotected site saves submissions without a widget or response. The recipient must be verified if email notifications are enabled.

## Links

- AI integration guide: https://formpostbox.com/docs/ai-integration
- Per-stack skills: https://formpostbox.com/skills/html/SKILL.md · https://formpostbox.com/skills/react/SKILL.md · https://formpostbox.com/skills/astro/SKILL.md
- Index for AI tools: https://formpostbox.com/llms.txt
