Which two credentials are required?
- X-API-Key
- Your key, starting with
tk_live_. Created in Settings, then Developers. Shown once at creation. - Authorization
Basic base64(MAILBOX_EMAIL:APP_PASSWORD). The app password is created in Settings, then App passwords.
The same app password also works for IMAP and SMTP clients such as Thunderbird or Gmail, so you can revoke access in one place.
GET /v1/me HTTP/1.1
Host: api.tuskmail.africa
X-API-Key: tk_live_...
Authorization: Basic bWFpbGJveEBleGFtcGxlLmNvLmtlOmFwcC1wYXNzd29yZA==How is a key bound to a mailbox?
Each API key is bound to a single user mailbox. The email in the Basic header must be that mailbox, otherwise the request is rejected with invalid_credentials. To work with several mailboxes, create a key and an app password for each one.
What can I configure on an app password?
When you create an app password you give it a description, and you can set an expiry in days and a list of allowed IP addresses. A request from an address that is not on the list gets 403 forbidden. Revoke an app password at any time in Settings, and it stops working immediately for the API and for mail clients.
What happens on repeated failures?
Repeated failed attempts from one IP address are throttled and answered with 429 rate_limited and a Retry-After header before credentials are even checked. A blocked domain (overdue subscription) returns 402 payment_required, and a disabled mailbox returns 403 forbidden.