Postvow

Developer documentation

Three requests to a first send, the interactive API reference, and the index of every identifier the API links to. Everything here is generated from or checked against the running service — where a manual would be needed, this points at the generated contract instead of paraphrasing it.

Your first send

You need one thing that is not on this page: an API key. Keys are issued during onboarding, which is a conversation rather than a form. hello@postvow.com

  1. Send a message

    A test key — the pv_test_ prefix — captures the message instead of delivering it, so a first integration never reaches a real inbox and never spends your sending reputation. Swap it for the live key when you are ready.

    curl -X POST https://api.postvow.eu/v1/send \
  -H "Authorization: Bearer pv_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@example.com",
    "from": "noreply@your-domain.com",
    "subject": "First send",
    "text": "It works."
  }'

  2. Read the acceptance

    Sending is asynchronous: 202 means accepted for delivery, not delivered. Keep the messageId — it is how every later question about this message is asked.

    {
  "messageId": "019fd464-18dc-7e6f-a755-2d492f4ba944",
  "stream": "transactional",
  "warnings": []
}

  3. Ask what happened to it

    The first call returns the message and its current delivery status. The second is the one worth knowing about: it returns the decision tree — what was attempted, what the receiving server said, and why the outcome is what it is.

    curl https://api.postvow.eu/v1/messages/{messageId} \
  -H "Authorization: Bearer pv_test_..."

curl https://api.postvow.eu/v1/messages/{messageId}/explain \
  -H "Authorization: Bearer pv_test_..."

The full API

Two ways to read one artefact. Pick by why you came.

Two things are authoritative, and neither of them is this page.

The response you are holding. Every Postvow error is RFC 9457 problem details and carries its own message and suggestedFix. That text is generated at the point the error occurs and is more specific than anything written here could be.

The OpenAPI specification. It is generated from the running code, so it cannot drift from the behaviour of the API you are calling.

If a code below is unfamiliar and the response text did not resolve it, write to us and quote the code. hello@postvow.com

Error codes

The codes the API emits from a fixed call site. The set is open — a code absent from this list is not an invalid code, and the response body remains authoritative for it.

API topics

Each links to its operations in the specification.

Guides and compatibility

Topics referenced from responses and from the compatibility endpoints. The migration endpoints themselves return machine-readable differences; these anchors exist so those references resolve.