API reference
152 endpoints under https://api.woyra.io/v1, generated from the OpenAPI description the server is tested against. An endpoint missing here is an endpoint that fails the build.
Countries
Country endpoints, billing currencies and messaging rules.
| GET | /v1/products | What this deployment sells |
| GET | /v1/countries | List country endpoints |
| GET | /v1/countries/{code} | Retrieve a country |
| GET | /v1/status | Whether Woyra is working |
Accounts
Account creation and identity.
| POST | /v1/accounts | Create an account |
| GET | /v1/account | Describe the calling account |
Messages
Send and inspect SMS.
| POST | /v1/dlr/{carrier}/{secret} | Carrier delivery receipt |
Emails
Send and inspect email.
| GET | /v1/emails | List emails |
| POST | /v1/emails | Send an email |
| GET | /v1/emails/{id} | Retrieve an email |
| POST | /v1/emails/{id}/cancel | Cancel a scheduled email |
| POST | /v1/emails/batch | Send a batch of emails |
| GET | /v1/templates | List templates |
| POST | /v1/templates | Save an email template |
| GET | /v1/templates/{id} | Retrieve a template |
| PATCH | /v1/templates/{id} | Change a template |
| DELETE | /v1/templates/{id} | Delete a template |
| GET | /t/o/{token} | Open tracking image |
| GET | /t/c/{token} | Click tracking redirect |
| GET | /v1/emails/inbound | Mail received on your domains |
| GET | /v1/emails/inbound/{id} | Retrieve a received email |
| GET | /v1/emails/inbound/{id}/attachments/{attachment_id} | Download an attachment |
| GET | /v1/emails/threads/{id} | A conversation |
Domains
Sending domains, DKIM keys and DNS verification.
| GET | /v1/domains | List sending domains |
| POST | /v1/domains | Add a sending domain |
| POST | /v1/domains/{id}/verify | Verify a domain's DNS |
| DELETE | /v1/domains/{id} | Remove a sending domain |
Mailboxes
Woyra Mail mailboxes and aliases on a verified domain.
| GET | /v1/mailboxes | List mailboxes |
| POST | /v1/mailboxes | Create a mailbox |
| GET | /v1/mailboxes/{id} | Get a mailbox |
| PATCH | /v1/mailboxes/{id} | Change a mailbox's quota, suspension or password |
| DELETE | /v1/mailboxes/{id} | Delete a mailbox and its mail |
| GET | /v1/mailboxes/usage | Usage per mailbox for a period |
| GET | /v1/mailboxes/{id}/messages | List the messages in a folder |
| GET | /v1/mailboxes/{id}/messages/{message_id} | Read a message |
| GET | /v1/mailboxes/{id}/messages/{message_id}/attachments/{attachment_id} | Download an attachment by signed link |
| POST | /v1/mailboxes/{id}/messages/flags | Mark messages read, unread, flagged or unflagged |
| POST | /v1/mailboxes/{id}/messages/move | Move messages to another folder |
| POST | /v1/mailboxes/{id}/messages/delete | Delete messages for good |
| GET | /v1/mailboxes/{id}/changes | What changed in a mailbox since a cursor |
| POST | /v1/mailboxes/{id}/send | Send a message from a mailbox |
| GET | /v1/mailboxes/{id}/profile | A mailbox's profile |
| PATCH | /v1/mailboxes/{id}/profile | Change a mailbox's display name, letterhead or signature |
| PUT | /v1/mailboxes/{id}/profile/picture | Set a mailbox's picture |
| GET | /v1/mailboxes/sending_limits | What the account may send today, and why |
| POST | /v1/mail/auth/token | Get a mailbox token for Woyra Mail's apps |
| POST | /v1/mail/devices | Register this native device for mailbox notifications |
| DELETE | /v1/mail/devices | Remove a push destination belonging to this device session |
| POST | /v1/mail/auth/refresh | Rotate a mailbox device session |
| POST | /v1/mail/auth/revoke | Revoke this mailbox device session |
| GET | /v1/mail/sync/changes | What changed in the mailbox since a cursor |
| GET | /v1/mail/sync/messages | Several messages at once |
| GET | /v1/mail/messages | A folder's messages, newest first |
| GET | /v1/mail/search | Search the whole mailbox, newest first |
| GET | /v1/mail/rules | The mailbox's rules and blocked senders |
| POST | /v1/mail/rules | Add a rule, or block a sender |
| DELETE | /v1/mail/rules/{id} | Remove a rule, or unblock a sender |
| GET | /v1/mail/autoreply | The out-of-office reply |
| PUT | /v1/mail/autoreply | Set the out-of-office reply |
| POST | /v1/mail/messages/{id}/unsubscribe | Leave the list a message came from |
| POST | /v1/mail/messages/{id}/cancel-send | Call back a message sent for later |
| POST | /v1/mail/messages/send | Send from the token's mailbox |
| GET | /v1/mail/profile | The token's mailbox profile |
| PATCH | /v1/mail/profile | Change the display name, letterhead or signature |
| PUT | /v1/mail/profile/picture | Set the mailbox's picture |
| DELETE | /v1/mail/profile/picture | Remove the mailbox's picture |
| PUT | /v1/mail/profile/letterhead-image | Set the picture at the head of the letterhead |
| DELETE | /v1/mail/profile/letterhead-image | Remove the letterhead picture |
| GET | /v1/mail/letterheads/{id} | A mailbox's letterhead picture, by signed link |
| GET | /v1/mail/avatars | Pictures, names and company logos for the addresses a client shows |
| GET | /v1/mail/logos/{domain} | A company's logo, by signed link |
| GET | /v1/mail/pictures/{id} | A mailbox's picture, by signed link |
| GET | /v1/mail/messages/{id} | One message with its body, marking it read |
| PATCH | /v1/mail/messages/{id} | Mark a message read or unread, star it, or file it in another folder |
| GET | /v1/mail/messages/{id}/attachments/{attachment_id} | A short-lived link to one attachment |
| GET | /v1/mail/unread | How many messages in INBOX are unread |
| GET | /v1/aliases | List aliases |
| POST | /v1/aliases | Create or repoint an alias |
| DELETE | /v1/aliases/{id} | Delete an alias |
Suppressions
Recipients this account will not send to.
| GET | /v1/suppressions | List suppressed recipients |
| POST | /v1/suppressions | Suppress a recipient |
| DELETE | /v1/suppressions/{recipient} | Unsuppress a recipient |
Webhooks
Endpoint registration for outbound events.
| GET | /v1/webhook_endpoints | List webhook endpoints |
| POST | /v1/webhook_endpoints | Register a webhook endpoint |
| DELETE | /v1/webhook_endpoints/{id} | Remove a webhook endpoint |
| GET | /v1/webhook_deliveries | List webhook deliveries |
| GET | /v1/webhook_deliveries/{id} | Inspect one delivery |
| POST | /v1/webhook_deliveries/{id}/replay | Send a delivery again |
| POST | /v1/webhook_endpoints/{id}/release | Take an endpoint out of quarantine |
API keys
Minting, listing and revoking API keys.
| GET | /v1/api_keys | List API keys |
| POST | /v1/api_keys | Mint an API key |
| DELETE | /v1/api_keys/{id} | Revoke an API key |
Billing
Balance, top-ups and the account statement.
| POST | /v1/topups | Add funds by card |
| GET | /v1/topups/{id} | One top-up |
| POST | /v1/subscriptions | Start a product subscription |
| GET | /v1/subscriptions/{product} | Current product subscription |
| POST | /v1/payments/stripe/webhook | Stripe's webhook |
| GET | /v1/ledger | The account statement |
| GET | /v1/billing/payment_options | How this account can pay |
| PUT | /v1/billing/payment_currency | Choose to pay in birr or in US dollars |
| GET | /v1/billing/bank_deposits | Recent birr bank deposits |
| POST | /v1/billing/bank_deposits | Request a birr bank deposit |
| POST | /v1/billing/bank_deposits/{id}/receipt | Upload the bank receipt for a deposit |
| POST | /v1/billing/bank_deposits/{id}/cancel | Cancel a deposit that has not been submitted or was returned |
| GET | /v1/balance | Retrieve account balance |
| GET | /v1/billing/email_tariff | The email price this account pays |
| GET | /v1/billing/email_subscription | This account's monthly email plan |
| PUT | /v1/billing/email_subscription | Take an email plan, or change it |
| POST | /v1/billing/email_subscription/cancel | Stop the email plan renewing |
| GET | /v1/pricing/email | The published email tariff |
Console
Session authentication, two-factor, the dashboard and the audit trail.
| POST | /v1/auth/signup | Create an account and sign in |
| POST | /v1/auth/login | Sign in with email and password |
| POST | /v1/auth/logout | End the session |
| GET | /v1/auth/config | What a sign-in page needs before anyone signs in |
| GET | /v1/auth/me | The signed-in user, account and MFA state |
| POST | /v1/auth/mfa/verify | Finish signing in with a TOTP code or a recovery code |
| POST | /v1/auth/passkeys/login/begin | Start signing in with a passkey |
| POST | /v1/auth/passkeys/login/finish | Finish signing in with a passkey |
| GET | /v1/auth/passkeys | The signed-in user's passkeys |
| POST | /v1/auth/passkeys/register/begin | Start adding a passkey |
| POST | /v1/auth/passkeys/register/finish | Finish adding a passkey |
| DELETE | /v1/auth/passkeys/{id} | Remove a passkey |
| POST | /v1/auth/recovery_codes | Make a fresh set of recovery codes |
| POST | /v1/auth/mfa/enrol | Start TOTP enrolment |
| POST | /v1/auth/mfa/confirm | Confirm TOTP enrolment with a code |
| DELETE | /v1/auth/mfa | Disable TOTP |
| POST | /v1/auth/verify-email | Confirm an email address from its link |
| POST | /v1/auth/resend-verification | Send the verification email again |
| POST | /v1/auth/forgot-password | Request a password reset link |
| POST | /v1/auth/reset-password | Set a new password from a reset link |
| POST | /v1/auth/change-password | Change the password while signed in |
| GET | /v1/auth/invites/{token} | Describe an invitation before accepting it |
| POST | /v1/auth/invites/accept | Accept an invitation and sign in |
| GET | /v1/console/overview | Dashboard counts |
| GET | /v1/console/analytics | Daily series and the route view |
| GET | /v1/console/stream | Live message events |
| GET | /v1/audit_events | The account's audit trail |
Team
Members, roles and invitations.
| GET | /v1/team/members | List the team |
| PATCH | /v1/team/members/{id} | Change a member's role |
| DELETE | /v1/team/members/{id} | Remove a member |
| GET | /v1/team/invites | List pending invitations |
| POST | /v1/team/invites | Invite someone by email |
| DELETE | /v1/team/invites/{id} | Cancel an invitation |
Waitlist
Interest from markets that are not open yet.
| POST | /v1/waitlist | Join the waitlist for a market that is not open yet |
Health
Liveness and readiness. No authentication.
| GET | /health | Liveness |
| GET | /ready | Readiness |
| GET | /v1/mail/addresses | The addresses this mailbox can send as |
| GET | /v1/dedicated_ips | The account's dedicated sending IP |
| POST | /v1/dedicated_ips | Request a dedicated sending IP |
| DELETE | /v1/dedicated_ips/{id} | Release a dedicated IP |
Numbers
| POST | /v1/inbound/{provider}/{secret} | A provider's inbound-SMS webhook |
Voice
| POST | /v1/voice/{provider}/{secret} | A voice provider's event webhook |