Deploy integration

Ship the form, verify production behaviour and keep documentation in sync.

Production checklist

  • Use the versioned endpoint in new code: /v1/forms/{public_id}/submissions.
  • Send an allowed Origin from server-side clients. Browsers do this automatically.
  • Keep the Turnstile site key in public frontend configuration. Never ship the secret key.
  • Generate an idempotency key per logical submission and reuse it on retry.
  • Handle 422 field errors, 429 rate limits and 503 temporary outages.
  • Do not automatically retry an invalid or expired Turnstile token.
  • Reset the Turnstile widget after success and after a used token.

What not to do

  • Do not put recipients, subjects or redirect URLs in the request body. They are ignored or rejected.
  • Do not retry a changed payload with an old idempotency key.
  • Do not treat a 201 response as proof that an email reached an inbox.
  • Do not proxy the public API through a server that hides the real customer origin without an explicit server integration decision.

Verify after deploy

  1. Submit a real form from the production website.
  2. Confirm the submission appears in the Postvia inbox.
  3. Confirm each recipient’s delivery status.
  4. Check the browser console for CORS or Turnstile errors.
  5. Confirm the success redirect or success message is accessible.

Keep documentation current

When an API or integration change ships, update the OpenAPI artifact, the relevant guide and the API changelog. Breaking changes must be recorded before rollout.