Documentation/Local & preview testing

Test a form during local development

Use a local web server to preview your form, then add that preview origin to the FormPostbox site before testing a submission.

When to use this guide

Use these steps while building or reviewing a form on your own machine. A local test is separate from the published site; test the published page again after deploying your site changes.

Serve the page over HTTP

Start your framework’s development server or a local static server. Open the resulting http://localhost:PORT or http://127.0.0.1:PORT preview address in your browser. Use the actual port printed by the server. A port is part of the origin, so http://localhost:3000 and http://localhost:5173 are different origins.

Do not open the file directly as file://…. A file URL has no normal website origin for the browser check. If your site is served over HTTPS locally, use that exact HTTPS origin instead.

Allow the local origin

In FormPostbox, open Sites, choose the site used by your form, then open Settings. Add the full local origin, including scheme and port, under Allowed origins; leave off the path. Save the site settings. When you use a different port, add that origin too.

If the project is hosted in a preview environment, add its exact HTTPS preview origin for testing. A preview hostname is separate from both localhost and your production hostname.

Send and inspect one test message

Open the form in the local browser, submit once, and check Inbox. A successful JSON integration should treat the message as saved only when it receives saved: true. Open the record to check the independent notification result. A valid accepted test uses one submission from the current UTC month’s allowance.

Use Turnstile test keys only locally

For local development and automated tests, Cloudflare provides dummy Turnstile keys with predictable outcomes. See Cloudflare’s official Turnstile testing guide for current values and behavior.

When submissions go to formpostbox.com, a locally running frontend still cannot save dummy secrets to the hosted service. Use a separate site and form for local tests, either without protection or with a real Cloudflare widget that allows the local hostname. Dummy keys apply only when the receiving FormPostbox service itself runs locally with test mode explicitly enabled. The public Site Key and private Secret Key serve different purposes: the Site Key goes in the browser widget, while the Secret Key is saved in FormPostbox and never belongs in frontend code. A Site Key without its matching Secret Key does not turn protection on. For a published site, keep the real keys from the same Cloudflare widget in the production configuration; do not replace them with dummy keys.

Publish, then test the live page

After you publish the website change, open the actual page on its production origin and submit a new test message. Confirm the production origin is listed on the site and, when protection is enabled, that the Turnstile widget includes the production hostname. Local success alone does not confirm the published configuration.

Common questions

The browser says CORS or network error. Compare the full origin in the address bar with the allowed origin, including the port. A browser may hide the server’s error body for a disallowed origin.

The widget does not verify locally. For formpostbox.com, check that your real widget allows the local hostname and that its two keys match. Use Cloudflare’s dummy pairing only when the receiving service itself is a local test instance. Reload after changing protection settings so the page uses the current configuration.

Related guides: allowed origins, Turnstile setup, and submission troubleshooting.

Still need help? Contact support@formpostbox.com. Include the guide topic and redacted error details, without keys or visitor messages.

Browse all topics ↑