Send a submission from your website
This guide describes the browser form contract. It applies to forms that post directly from an allowed website origin to one FormPostbox form.
When to use this contract
Use it when you are writing or reviewing custom HTML, React, Astro, or other browser code. For a ready-made implementation, open Connect your form or copy the prompt from your form’s Connect your website panel.
Endpoint and request encoding
Send a POST request to https://formpostbox.com/f/{formId}, replacing the path value with the form ID shown in FormPostbox. The request body must be either application/json or application/x-www-form-urlencoded. Multipart uploads and other content types are rejected. Use Accept: application/json with fetch when the page needs to show a precise saved or error state. A native HTML form post redirects after a save and displays an HTML error page for a rejected request.
Fields and limits
Send named string fields. Business field names must contain 1–128 characters; a request can include up to 50 business fields. Each value may contain up to 32,768 characters. The encoded request body and normalized business-field JSON must each stay within 65,536 bytes. The reserved _intent_id and cf-turnstile-response fields do not count toward the 50 business fields.
Every request needs _intent_id, a 16–128 character identifier for one user submission. Create it when the visitor starts a new message, keep it with that message while a request is in flight, and reuse it for network retries. After the server confirms a save, clear it; create a fresh value for the next message.
Checkboxes and multi-select controls should use independent field names or an explicit string serialization such as topics=design%2Csupport. Do not send arrays, objects, files, or other non-string values. Attachments are not supported.
Allowed origins and optional protection
The page’s exact origin must be listed on the form’s site: scheme, hostname, and port must match. Paths do not belong in an origin, and wildcards are not supported. The origin is checked again on a retry. A browser may report a blocked cross-origin response as a network error; compare the page address with the allowed origin shown in the workspace.
When the site has Turnstile protection enabled, include a fresh, single-use cf-turnstile-response token of 1–2,048 characters. A missing, expired, reused, or rejected token fails the request. On an unprotected site, the token is unnecessary; a supplied token up to 2,048 characters is ignored. The secret key stays on FormPostbox servers and is never sent from browser code.
Read the result
A new accepted message returns HTTP 201 and a JSON object such as {"saved":true,"id":"…","replayed":false,"notification":"queued"}. A retry with the same intent and identical fields returns HTTP 200, the original ID, replayed: true, and notification: "unchanged". It creates no second record and uses no additional allowance. Reusing the intent with changed fields returns 409 conflict; restore the original fields to retry, or start a new message with a new intent.
Show success only when the JSON response has saved: true. The notification value describes the separate email path: queued means a new email notification was queued, off means this form saves to the inbox without email, and unchanged describes an idempotent retry. A saved message does not by itself mean an email reached the recipient’s inbox. See notification statuses.
Error responses
A rejected response has {"saved":false,"error":"…"}. Handle the status and error code before showing success:
| HTTP | Code | What it means and what to check |
|---|---|---|
| 400 | invalid | The body is invalid or a field exceeds a limit. Send an object of named strings and check the limits above. |
| 400 | origin | The page origin is not allowed. Match its scheme, hostname, and port in site settings. |
| 400 | captcha | Turnstile verification failed. Get a new token and check the widget keys and hostname. |
| 400 | paused | The form is not enabled. Enable it in the Forms list. |
| 400 | configuration | The selected notification recipient is no longer verified, or protection settings changed while the request was running. Check the form and site settings, reload the form page, then retry. |
| 404 | not_found | The form ID is unknown. Copy the endpoint from the correct form page. |
| 404 | expired | The earlier record associated with this intent was deleted or passed its retention date. Start a new submission with a new intent. |
| 409 | conflict | The intent was already used with different content. Retry with the original payload, or explicitly begin a new message with a new intent. |
| 413 | too_large | The request body exceeds 65,536 bytes. Reduce the submitted text or fields. |
| 415 | unsupported | The content type is unsupported. Use JSON or URL-encoded form data. |
| 429 | quota | The workspace has no submission allowance left for this UTC month. Review limits and quotas. |
| 429 | rate_limit | The request rate is temporarily too high. Wait before trying again. |
| 503 | unavailable | The intake service is temporarily busy. Retry later using the same intent and payload. |
Common questions
Can I send with a Developer API key? No. This endpoint is a public browser integration that relies on the page’s allowed origin; it does not accept API keys and does not require a server proxy. Developer API keys are for server-side read access to retained submissions.
Where do I see a saved message? Open Inbox, then select the message to inspect its fields and separate notification timeline.
Related guides: code examples, origin and verification checks, and common errors.
Still need help? Contact support@formpostbox.com. Include the guide topic and redacted error details, without keys or visitor messages.
Browse all topics ↑