WoyraDocs
Get an API key

Get a mailbox token for Woyra Mail's apps

POST/v1/mail/auth/token

Mailboxes · Requires an API key

Two ways in, and both end with the same hour-long token for one mailbox. Password clients may opt into a revocable 30-day device session with rotating refresh credentials by sending deviceSession: true. API-key clients continue to mint short-lived tokens without refresh.

- **With an API key** carrying mail:access: a partner's control plane (TalariCloud), which already knows who its customer is, names a mailbox on its account and, optionally, its own customer reference. - **With no key**: the mailbox's address and the password its account set. A wrong address and a wrong password get the same answer. Ten attempts per address, and per client address, per 15 minutes.

A suspended mailbox gets 409 mailbox_suspended either way.

Body

FieldTypeDescription
mailboxrequiredstring
passwordstringWithout an API key only.
deviceSessionbooleanPassword login only. Issue a revocable device session with rotating refresh credentials.
accountRefstringWith an API key: the partner's customer id, carried in the token for audit.

Example

curl -X POST https://api.woyra.io/v1/mail/auth/token \
  -H "Authorization: Bearer $WOYRA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "mailbox": "<mailbox>"
  }'

Response

200 The token.

FieldTypeDescription
tokenrequiredstring
mailboxrequiredstring
expiresAtrequiredtimestamp
expiresInrequiredintegerSeconds.
refreshTokenstringOnly for opted-in password device sessions; store securely, never log.
sessionExpiresAttimestampAbsolute expiry of the device session.

Errors

StatusCodes
400invalid_request, unsupported_version
401authentication_required, invalid_api_key
403insufficient_scope, domain_not_verified, recipient_suppressed, sending_paused, mfa_required
404not_found, product_not_offered
409idempotency_conflict, idempotency_in_progress
429rate_limited, daily_send_limit_reached

Also in Mailboxes