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 DNSEvery 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
- Countries: 4 endpoints. Country endpoints, billing currencies and messaging rules.
- Accounts: 2 endpoints. Account creation and identity.
- Messages: 1 endpoint. Send and inspect SMS.
- Emails: 16 endpoints. Send and inspect email.
- Domains: 4 endpoints. Sending domains, DKIM keys and DNS verification.
- Mailboxes: 52 endpoints. Woyra Mail mailboxes and aliases on a verified domain.
- Suppressions: 3 endpoints. Recipients this account will not send to.
- Webhooks: 7 endpoints. Endpoint registration for outbound events.
- API keys: 3 endpoints. Minting, listing and revoking API keys.
- Billing: 18 endpoints. Balance, top-ups and the account statement.
- Console: 27 endpoints. Session authentication, two-factor, the dashboard and the audit trail.
- Team: 6 endpoints. Members, roles and invitations.
- Waitlist: 1 endpoint. Interest from markets that are not open yet.
- Health: 2 endpoints. Liveness and readiness. No authentication.
- Mail: 1 endpoint
- Email: 3 endpoints
- Numbers: 1 endpoint
- Voice: 1 endpoint
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.