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
-
Create a key with the inbox scopes
In the dashboard under API Keys, create a key with
inboxes:read, andinboxes:writeif the agent will reply. Copy it, it is shown once.Start with
inboxes:readalone 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. -
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 withDELETE /v1/api-keys/{key_id}/mailboxes/{mailbox_id}. Revoking takes effect at once, for webhooks as well as reads. -
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
inboxesarray 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.