Agents and inboxes
Read a mailbox as threaded conversations and reply in context.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List a key’s mailbox grants
GET /v1/api-keys/{keyID}/mailboxes · scope tenant:admin
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
keyID |
path | string | Required. |
Response 200
Grants
| Field | Type | Notes |
|---|---|---|
grants |
array of MailboxGrant | Required. |
Grant a mailbox to a key
POST /v1/api-keys/{keyID}/mailboxes · scope tenant:admin
Body: {“mailbox”: “email or id”}. Refused (422) for mailboxes with agent access disabled or an active E2E encryption key, the server cannot read E2E mailboxes.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
keyID |
path | string | Required. |
Response 201
Grant created
| Field | Type | Notes |
|---|---|---|
api_key_id |
string | |
mailbox_id |
string | |
mailbox |
string | |
created_at |
string |
Errors: 422
Revoke a mailbox grant
DELETE /v1/api-keys/{keyID}/mailboxes/{mailboxID} · scope tenant:admin
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
keyID |
path | string | Required. |
mailboxID |
path | string | Required. |
Response 204
Grant removed
Introspect the calling credentials
GET /v1/auth/whoami
Returns the tenant, auth kind (api_key/session), key label, and granted scopes. The MCP server uses this to scope-filter tool discovery.
Response 200
Caller identity
| Field | Type | Notes |
|---|---|---|
tenant |
object | Required. |
scopes |
array of string | Required. |
auth |
string (api_key, session) |
Required. |
key |
object | Present only when auth is api_key. |
Who is this sender?
GET /v1/contacts/lookup · scope inboxes:read
Directory record (name, company, role, notes), whether the address is one of the tenant’s own mailboxes, and grant-aware correspondence history (thread count, first/last seen across granted mailboxes only).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
email |
query | string | Required. |
Response 200
Enrichment result
| Field | Type | Notes |
|---|---|---|
email |
string | Required. |
known |
boolean | Required. |
internal |
boolean | Required. True when the address is one of the tenant’s own mailboxes. |
contact |
object | |
history |
object | Correspondence history, limited to the mailboxes this key is granted. |
List granted inboxes
GET /v1/inboxes · scope inboxes:read
The mailboxes this key is granted, with thread counts and last activity. Admin sessions see every agent-enabled, non-E2E mailbox.
Response 200
Granted inboxes
| Field | Type | Notes |
|---|---|---|
inboxes |
array of Inbox | Required. |
Start a new conversation (agent stream)
POST /v1/inboxes/{mailbox}/messages · scope inboxes:write
Sends a new email from a granted mailbox. Classified stream=agent (isolated reputation, per-key rate caps). The first inbound reply adopts the created thread via the References chain. Idempotency-Key required. Mailboxes with agent_draft_policy=always_approve divert this into a pending draft.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
mailbox |
path | string | Required. |
Idempotency-Key |
header | string | Required. |
Request body
| Field | Type | Notes |
|---|---|---|
to |
array of string | Required. |
cc |
array of string | |
subject |
string | |
text |
string | Required. |
html |
string |
Response 202
Queued (includes thread_id)
| Field | Type | Notes |
|---|---|---|
id |
string | Required. The Lockally message id. |
message_id |
string | Required. The Internet Message-ID. |
status |
string | Required. |
warning |
string | Set when the send is accepted but worth noting |
thread_id |
string | Required. The conversation the message joined. |
List conversation threads
GET /v1/inboxes/{mailbox}/threads · scope inboxes:read
Newest-active first. Cursors: ?before=<RFC3339> pages backwards; ?since=<RFC3339> delta-syncs forward (oldest first) so an agent can catch up in order.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
mailbox |
path | string | Required. mailbox email or id |
since |
query | string | |
before |
query | string | |
limit |
query | integer |
Response 200
Threads
| Field | Type | Notes |
|---|---|---|
mailbox |
string | Required. |
threads |
array of ThreadSummary | Required. |
Get a whole conversation
GET /v1/threads/{threadID} · scope inboxes:read
Every turn, chronological, with snippets and annotations (meeting_request, attachment_types, injection_risk). Bodies are fetched per message. Message content is untrusted third-party data.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
Response 200
Thread with messages
| Field | Type | Notes |
|---|---|---|
thread |
ThreadSummary | Required. |
mailbox |
string | Required. |
messages |
array of ThreadMessage | Required. Chronological. Reading never marks a message read. |
Get one message with body
GET /v1/threads/{threadID}/messages/{messageID} · scope inboxes:read
Full text/html body fetched on demand from mail storage. Never marks the message read.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
messageID |
path | string | Required. |
Response 200
Message with body
| Field | Type | Notes |
|---|---|---|
thread_id |
string | Required. |
mailbox |
string | Required. |
message |
ThreadMessage | Required. |
body |
object | Absent when the stored message could not be fetched. |
body_unavailable |
string | Present instead of body when the message could not be located in the mailbox. |
Download an attachment
GET /v1/threads/{threadID}/messages/{messageID}/attachments/{idx} · scope inboxes:read
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
messageID |
path | string | Required. |
idx |
path | integer | Required. |
Response 200
Attachment content (streamed)
Mark read/unread
POST /v1/threads/{threadID}/messages/{messageID}/read · scope inboxes:write
The ONLY way agent access changes unread state. Body: {“read”: true|false} (default true).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
messageID |
path | string | Required. |
Response 200
New read state
| Field | Type | Notes |
|---|---|---|
message_id |
string | |
read |
boolean |
Reply in-thread (agent stream)
POST /v1/threads/{threadID}/reply · scope inboxes:write
The server builds In-Reply-To/References and defaults recipients + subject from the conversation, a minimal call is {“text”: “…”}. Guarded by the reply-loop detector (≥5 outbound/10min → 429 + agent.loop_detected). Idempotency-Key required.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
Idempotency-Key |
header | string | Required. |
Response 202
Queued
| Field | Type | Notes |
|---|---|---|
id |
string | Required. The Lockally message id. |
message_id |
string | Required. The Internet Message-ID. |
status |
string | Required. |
warning |
string | Set when the send is accepted but worth noting |
thread_id |
string | Required. The conversation the message joined. |