How Postvia works
Understand the public request pipeline, durable acceptance and asynchronous delivery.
Postvia separates acceptance from email delivery. That separation is the core reliability guarantee.
Request pipeline
- The request reaches
api.postvia.devover HTTPS. - Host, body-size, origin, CORS and Redis rate-limit checks run.
- The form, website and customer are resolved; a disabled parent blocks the request.
- The body is parsed as JSON, URL-encoded or text-only multipart. Files and nested objects are rejected.
- Reserved control fields are stripped. Honeypot and form field validation run.
- An idempotent replay is returned if the same key and equivalent payload were already accepted.
- Turnstile is verified server-side only when the form has it enabled.
- One transaction creates the submission, delivery rows, outbox rows and aggregate metrics.
- After commit, the API returns
201JSON or a303redirect for a native HTML form.
If the transaction fails, the API returns an error and never claims success.
Delivery pipeline
Each recipient gets an independent delivery row and outbox row. A worker claims the delivery with a lease, sends the email outside the database transaction and records the outcome.
- Transient failures retry after
1m, 5m, 15m, 1h, 4h, 12hwith jitter. - Permanent failures stop immediately.
- Ambiguous provider outcomes become
unknownand retry after a delay. - The scheduler recovers expired leases and unpublished work every minute.
What the operator sees
The administration portal at app.postvia.dev shows the submission payload, delivery timeline, attempts and safe error categories. It never claims an email reached an inbox; it reports the provider outcome.