Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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.