Submit your first JSON request

Send a JSON submission with a stable idempotency key and an allowed origin.

This is the smallest useful request. Replace abc123 with the form’s public ID and https://customer-site.example with an origin configured on the website.

curl -X POST 'https://api.postvia.dev/v1/forms/abc123/submissions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Origin: https://customer-site.example' \
  --data-raw '{
    "name": "John Smith",
    "email": "[email protected]",
    "message": "I would like more information"
  }'

Success

{
  "success": true,
  "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
  "message": "Your enquiry has been received."
}

HTTP 201 means the submission is durably stored and scheduled. It does not mean the email has been delivered.

Retry safely

Reuse the same Idempotency-Key if the request fails before you receive a response. An identical replay returns 200 with the same submission_id and creates no duplicate delivery.

If the payload changes, use a new key. Reusing the key with different content returns 409 idempotency_conflict.

Generate a UUID per logical submission, not per HTTP attempt. Rotate the key after success or when the user changes the data.

Native HTML forms

A native HTML form posts to the same endpoint and receives a 303 redirect instead of JSON. See Standard HTML forms.

Next