WoyraDocs
Get an API key

Woyra API

One base URL, one auth scheme, one error format, one pagination format and one idempotency mechanism, for transactional email and mailboxes. 152 endpoints, generated from the OpenAPI description the server is tested against.

Base URL

Everything lives under https://api.woyra.io/v1. Each country Woyra serves also has its own endpoint, such as ethiopia.woyra.io: the same key works on all of them, and which one you call decides the compliance rules applied and, where residency requires it, which data plane answers.

Authentication

A bearer key, prefixed by mode. Keys are shown once, stored hashed, and carry explicit resource:action scopes. There is no implicit all-permissions key: a leaked key should cost you one capability, not the account.

Authorization: Bearer wk_live_...   # sends real messages, spends real money
Authorization: Bearer wk_test_...   # sends nothing, costs nothing, skips DNS

Every error looks like this

Branch on code, never on message. Every response carries a request id you can quote to support, and every error carries a doc_url that points at its page here.

{
  "error": {
    "code": "insufficient_funds",
    "message": "This send needs $0.004 but the balance is $0.001.",
    "doc_url": "https://docs.woyra.io/errors/insufficient_funds",
    "param": null,
    "request_id": "req_01J..."
  }
}

Idempotency

Every request that spends money takes an Idempotency-Key, honoured for 24 hours. A retry replays the original response verbatim, so a dropped connection never becomes a double send. How to choose one.

Pagination

Lists take limit and cursor, and return has_more with next_cursor. Ids sort by time, so paging backwards through a log is stable even while new messages arrive.

Versioning

Send Woyra-Version to pin the behaviour you built against, or omit it for the current version (2026-09-01). Every response says which version served it.

What is in the reference

Guides

Start

Sign-up returns a working test key in the same response. No card, no sales call. Create an account, or read what everything costs first.