Mailboxes
Hosted mailboxes and their members. Business mail only.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List mailboxes
GET /v1/mailboxes · scope mailboxes:read
Returns mailboxes under the calling tenant, active and soft-deleted.
?limit=N between 1 and 200 (default 50).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit |
query | integer |
Response 200
Mailbox list.
| Field | Type | Notes |
|---|---|---|
data |
array of Mailbox | Required. |
limit |
integer | Required. |
Errors: 401, 403
Create a mailbox
POST /v1/mailboxes · scope mailboxes:write
Creates a mailbox on a tenant-verified domain. If password is
omitted, lockally generates a 16-char password and returns it in the
response, shown once.
Gate. The mailbox’s domain must already be registered AND
verified for this tenant (via /v1/domains + /v1/domains/{domain}/verify).
Idempotent. Re-posting the same email returns the existing mailbox UNTOUCHED, password is NOT regenerated. To change a password, use PATCH instead.
Request body
| Field | Type | Notes |
|---|---|---|
email |
string | Required. |
password |
string | Optional; lockally generates if absent. |
quota_bytes |
integer | 5 GB default. |
Response 200
Mailbox already existed for this tenant (idempotent).
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain_id |
string | Required. |
email |
string | Required. |
quota_bytes |
integer | Required. |
disabled |
boolean | Required. |
disabled_at |
string | |
soft_deleted_at |
string | |
hard_delete_after |
string | |
created_at |
string | Required. |
password |
string | ONLY present on POST response when lockally generated the password. Shown once. |
Errors: 400, 401, 403, 409
Get a mailbox
GET /v1/mailboxes/{email} · scope mailboxes:read
Response 200
Mailbox info.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain_id |
string | Required. |
email |
string | Required. |
quota_bytes |
integer | Required. |
disabled |
boolean | Required. |
disabled_at |
string | |
soft_deleted_at |
string | |
hard_delete_after |
string | |
created_at |
string | Required. |
password |
string | ONLY present on POST response when lockally generated the password. Shown once. |
Errors: 401, 403, 404
Update a mailbox
PATCH /v1/mailboxes/{email} · scope mailboxes:write
Supply at least one of password, quota_bytes, disabled.
Returns the updated mailbox.
Request body
| Field | Type | Notes |
|---|---|---|
password |
string | |
quota_bytes |
integer | |
disabled |
boolean |
Response 200
Updated mailbox.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain_id |
string | Required. |
email |
string | Required. |
quota_bytes |
integer | Required. |
disabled |
boolean | Required. |
disabled_at |
string | |
soft_deleted_at |
string | |
hard_delete_after |
string | |
created_at |
string | Required. |
password |
string | ONLY present on POST response when lockally generated the password. Shown once. |
Errors: 400, 401, 403, 404
Soft-delete a mailbox
DELETE /v1/mailboxes/{email} · scope mailboxes:write
Sets soft_deleted_at = now() and hard_delete_after = now() + 90d
per design D25. A background sweep (planned) will hard-delete after
the window. The mailbox is also disabled immediately.
Response 204
Soft-deleted.
Errors: 401, 403, 404
Request a mailbox export
POST /v1/mailboxes/{email}/export · scope tenant:admin
Issues a one-shot “presigned” download URL for the mailbox’s content in mbox format. The URL works without an Authorization header, the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.
v1 caveat: the synthesized mbox only contains outbound mail (sent mail only). A later version will cover received mail for full inbox + folder structure + flags. The endpoint contract stays unchanged.
Scope changed: this used to accept mailboxes:read. It takes any
mailbox in the tenant and returns that mailbox’s mail, so it now
requires tenant:admin, matching POST /v1/ediscovery/export. A key
scoped mailboxes:read gets 403 and has to be reissued; admin console
sessions are unaffected.
Response 201
Export token issued.
| Field | Type | Notes |
|---|---|---|
url |
string | Required. Relative download URL. Caller appends to the API host. |
expires_at |
string | Required. |
format |
string (mbox) |
Required. |
Errors: 401, 403, 404
Download a previously-issued mailbox export
GET /v1/mailboxes/{email}/export/download
Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404, tokens are single-use.
Response 200
mbox stream.
Errors: 400, 403, 404
List shared mailbox members
GET /v1/mailboxes/{email}/members · scope mailboxes:read
Response 200
Members of the shared mailbox.
| Field | Type | Notes |
|---|---|---|
data |
array of SharedMember | Required. |
Errors: 401, 403, 404
Add a shared mailbox member
POST /v1/mailboxes/{email}/members · scope mailboxes:write
Request body
| Field | Type | Notes |
|---|---|---|
member_email |
string | Required. |
role |
string (manager, member) |
Response 201
Member added.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
mailbox_id |
string | Required. |
tenant_id |
string | Required. |
member_email |
string | Required. |
role |
string (manager, member) |
Required. |
created_at |
string | Required. |
Errors: 400, 401, 403, 404, 409
Remove a shared mailbox member
DELETE /v1/mailboxes/{email}/members/{memberEmail} · scope mailboxes:write
Response 204
No content
Errors: 401, 403, 404