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.

      Connect an agent

      There are two ways to put an agent on a Lockally mailbox, and they share the same first two steps. Do those, then pick a path.

      • MCP, if you are using Claude, Cursor or another MCP client. No integration code.
      • REST, if you are writing the agent yourself and want control over the loop.

      Shared setup

      1. Create a key with the inbox scopes

        In the dashboard under API Keys, create a key with inboxes:read, and inboxes:write if the agent will reply. Copy it, it is shown once.

        Start with inboxes:read alone if you want the agent to look before it can touch anything. Scopes cannot be added to a key after it is made, so you will create a second key when you are ready to let it write.

      2. Grant the key each mailbox it may touch

        With an admin key, not the one you just made:

        curl -X POST https://api.lockally.com/v1/api-keys/{key_id}/mailboxes \
          -H "Authorization: Bearer $LOCKALLY_ADMIN_KEY" \
          -H "Content-Type: application/json" \
          -d '{"mailbox": "support@yourdomain.com"}'

        List grants with GET /v1/api-keys/{key_id}/mailboxes, and revoke one with DELETE /v1/api-keys/{key_id}/mailboxes/{mailbox_id}. Revoking takes effect at once, for webhooks as well as reads.

      3. Check the key is what you think it is

        curl https://api.lockally.com/v1/auth/whoami \
          -H "Authorization: Bearer $LOCKALLY_API_KEY"

        Confirms the tenant, the key’s label and its scopes. Then confirm the grant resolved:

        curl https://api.lockally.com/v1/inboxes \
          -H "Authorization: Bearer $LOCKALLY_API_KEY"

        A non-empty inboxes array means you are ready. An empty one means step 2 did not apply, and nothing further will work.

      Path A: an MCP client

      Point the client at https://mcp.lockally.com with your key as a bearer token, over streamable HTTP. Tool discovery is scope-filtered, so a key without inboxes:write never sees the send tools at all.

      The per-client configuration, the full tool list and the safety model are on the MCP server page rather than duplicated here.

      Once connected, ask the assistant to list your inboxes. If it comes back with the mailbox from step 2, the loop is live.

      Path B: your own agent over REST

      The read and reply loop is four calls, and the Receive and reply quickstart walks them end to end:

      Step Call
      Find the mailbox GET /v1/inboxes
      Find work GET /v1/inboxes/{mailbox}/threads?since=
      Read context GET /v1/threads/{thread_id}
      Act POST /v1/threads/{thread_id}/reply

      Three things about this surface that change how you write the loop:

      Reads never mark anything read. Skimming an inbox does not touch the unread state a person depends on. Marking read is an explicit call.

      Replies need an Idempotency-Key. Agents retry. A retried reply that sends twice is visible to your customer.

      ?since= exists so you do not refetch. Delta-sync the thread list on a schedule, or better, subscribe message.received and stop polling.

      Let a human approve before it sends

      You do not have to choose between an agent that cannot act and an agent that acts unsupervised. A draft is proposed rather than sent:

      curl -X POST https://api.lockally.com/v1/threads/{thread_id}/drafts \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Content-Type: application/json" \
        -H "Idempotency-Key: draft-$(uuidgen)" \
        -d '{"text": "Sorry about that. Your refund is on its way."}'

      A draft auto-sends when it is judged safe and is held for approval when it is not. A human releases it with POST /v1/drafts/{id}/approve, which requires tenant:admin, so the agent’s own key cannot approve its own work. That separation is the point.

      Drafts started with POST /v1/inboxes/{mailbox}/drafts, which begin a new conversation rather than continue one, always require approval.

      Before you trust it with a real inbox

      Treat message content as untrusted input. Every inbound message is annotated at ingest, and injection_risk flags likely prompt-injection attempts. Read the flag, and design the loop so a message cannot instruct your agent regardless of what the flag says.

      Rehearse on a test key. Create one with {"test": true} and the whole loop works, grants, threads, drafts and webhooks included, with POST /v1/test/inbound to inject messages through the real pipeline. Nothing is delivered to anyone.

      Every call is audited, reads included. The tenant audit log records which key touched which thread and when, which is what makes granting a mailbox to software defensible in the first place.

      Next