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.
-
Create a key with the inbox scopes
In the dashboard under API Keys, create a key with
inboxes:readandinboxes: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}onPOST /v1/api-keys. A test key is prefixedlk_test_and is the only kind that may simulate inbound in step 4. -
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.
-
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
inboxesarray means the grant did not apply. Go back to step 2 before going further, because everything below will look broken for the same reason. -
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 themessage.receivedwebhook: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 a403. On a live key, send yourself a real email instead and carry on from step 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. -
Read the whole conversation
curl https://api.lockally.com/v1/threads/{thread_id} \ -H "Authorization: Bearer $LOCKALLY_API_KEY"You get
thread,mailboxand a chronologicalmessagesarray. Each message carriesdirection,from,to,received_at, asnippet,has_attachments, andannotationscomputed at ingest. Full bodies are fetched per message fromGET /v1/threads/{thread_id}/messages/{message_id}, so listing a busy thread stays cheap. -
Reply in thread
The minimal reply is a single field. The server builds
In-Reply-ToandReferencesfrom 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
202with the message id and thethread_idit joined. You can overrideto,cc,subject, or sendhtmlinstead oftext.
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.