Business, API and Both
Your account is on one of three modes. It decides which parts of the API
answer you, so it is worth knowing yours before you debug a 403.
| Mode | What it is | Mailbox endpoints |
|---|---|---|
api |
Lockally API. Transactional sending from addresses on your verified domains. | Not available |
business |
Business mail. Hosted mailboxes for your people, billed per mailbox. | Available |
both |
Both products on one account. | Available |
Check yours with one call:
curl https://api.lockally.com/v1/auth/whoami \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
The failure this explains
A Lockally API account calling a mailbox endpoint gets:
{
"status": 403,
"title": "Business mode required",
"detail": "This endpoint needs hosted mailboxes."
}
No scope fixes this. The mailbox endpoints act on hosted mailboxes, and
an API account has none, so granting mailboxes:write changes nothing. The
console will not even offer you the scope.
What each mode changes
It does not gate the API itself. API access is gated by your plan, not your mode. Moving between modes reveals or hides console surfaces and unlocks the mailbox endpoints; it does not switch your keys on or off.
Mode decides:
- Whether the mailbox endpoints answer: mailboxes, aliases, contacts, calendars, distribution lists, shared members, encryption, retention and eDiscovery.
- Which console navigation you see, and what the key page is called: Tokens on an API account, API keys on business mail.
- Which notification categories exist for you.
Changing mode
Both directions are self-serve, instant, and leave your existing setup alone. Keys, domains, templates, webhooks and send history are untouched.
Business mail, adding the API (business to both). In the console,
turn on the transactional API. It is free, and it grants a one-time welcome
bundle of 6,000 send units.
Lockally API, adding mailboxes (api to both). In the console under
Billing, choose a mail plan, then Add business mail. The
mailboxes:* scopes become grantable and the mailbox endpoints start
working with no code change.