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.

      Receive and reply

      Lockally is not send-only. You can read a mailbox as threaded conversations and reply in context, so an app or an agent can work a real inbox over HTTP.

      This takes about ten minutes, and you do not need a domain or a mail server to try it: step 4 injects a message through the real pipeline.

      1. Create a key with the inbox scopes

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

        To follow this guide without touching real mail, tick the test option, or create the key with {"test": true} on POST /v1/api-keys. A test key is prefixed lk_test_ and is the only kind that may simulate inbound in step 4.

      2. Grant the key a mailbox

        Per mailbox, never tenant-wide. Run this with an admin key, not the key 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"}'

        Mailboxes with agent access disabled, or with end-to-end encryption on, are refused. Lockally cannot read an E2E mailbox, which is the feature working rather than a fault.

      3. Confirm the grant landed

        curl https://api.lockally.com/v1/inboxes \
          -H "Authorization: Bearer $LOCKALLY_API_KEY"
        {
          "inboxes": [
            {
              "id": "8f14e45f-ceea-467a-9f0a-2d3b1c9e4a77",
              "email": "support@yourdomain.com",
              "last_message_at": "2026-10-15T09:12:44Z",
              "thread_count": 3
            }
          ]
        }

        An empty inboxes array means the grant did not apply. Go back to step 2 before going further, because everything below will look broken for the same reason.

      4. Put a message in the inbox

        With a lk_test_ key you can inject one through the real indexing pipeline, including thread adoption, annotations and the message.received webhook:

        curl -X POST https://api.lockally.com/v1/test/inbound \
          -H "Authorization: Bearer $LOCKALLY_TEST_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "mailbox": "support@yourdomain.com",
            "from": "customer@example.com",
            "subject": "Order 1042 arrived damaged",
            "text": "The box was crushed. I would like a refund."
          }'

        A live lk_live_ key is refused here with a 403. On a live key, send yourself a real email instead and carry on from step 5.

      5. List the conversations

        curl "https://api.lockally.com/v1/inboxes/support@yourdomain.com/threads" \
          -H "Authorization: Bearer $LOCKALLY_API_KEY"
        {
          "mailbox": "support@yourdomain.com",
          "threads": [
            {
              "id": "3c6f1b2e-77a1-4d0e-9b55-1f2a8c4d9e30",
              "subject": "Order 1042 arrived damaged",
              "participants": ["customer@example.com", "support@yourdomain.com"],
              "message_count": 1,
              "last_message_at": "2026-10-15T09:12:44Z",
              "last_direction": "inbound"
            }
          ]
        }

        Newest active first. ?before= pages backwards and ?since= delta-syncs forward, which is what you want on a schedule rather than refetching.

      6. Read the whole conversation

        curl https://api.lockally.com/v1/threads/{thread_id} \
          -H "Authorization: Bearer $LOCKALLY_API_KEY"

        You get thread, mailbox and a chronological messages array. Each message carries direction, from, to, received_at, a snippet, has_attachments, and annotations computed at ingest. Full bodies are fetched per message from GET /v1/threads/{thread_id}/messages/{message_id}, so listing a busy thread stays cheap.

      7. Reply in thread

        The minimal reply is a single field. The server builds In-Reply-To and References from the latest turn and defaults the recipients and subject from the conversation, so you do not assemble headers yourself.

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

        Returns 202 with the message id and the thread_id it joined. You can override to, cc, subject, or send html instead of text.

      Reading never marks anything read

      This is deliberate and worth knowing before you build on it. Listing threads and fetching messages do not set the message to read. An agent skimming an inbox must not destroy the unread state a person relies on.

      Marking read is an explicit, separate call:

      curl -X POST https://api.lockally.com/v1/threads/{thread_id}/messages/{message_id}/read \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"read": true}'

      Do not poll

      Polling works and is fine while you are building. In production, subscribe a webhook to message.received and let inbound come to you. Grants apply to events as well as reads, so a key only hears about the mailboxes it holds, and removing a grant stops the events immediately.

      Next

      • Agent API for the full surface, including drafts held for human approval and the annotations computed on every inbound message.
      • Connect an agent to drive all of this from an MCP client instead of by hand.
      • Code Examples for the same calls in the official SDKs.