Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-mailboxes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: lockally control plane Mailboxes API
version: 0.1.0
summary: REST API for managing tenants, domains, mailboxes, and outbound mail
description: 'The lockally control plane lets integrators and direct customers manage
everything except actual mail data flow (which uses standard JMAP / IMAP /
SMTP-submission against the data plane endpoints).
**Authentication.** All `/v1/*` endpoints require a Bearer API key in the
`Authorization` header. Keys are formatted `lk_live__`,
or `lk_test_` for a test key. Create keys in the dashboard, or with
`POST /v1/api-keys` using a key that holds `tenant:admin`.
The key''s plan is checked on every request, so a key stops working if the
account moves to a plan without API access, and works again if it moves back.
**Errors.** Failures return RFC 9457
`application/problem+json` documents.
**Scopes.** Each endpoint requires a specific scope on the presented key.
Insufficient scope returns `403` with the required scope name in `detail`.'
contact:
name: lockally support
email: support@lockally.com
license:
name: AGPL-3.0-only OR LicenseRef-LOC-Commercial
identifier: AGPL-3.0-only
servers:
- url: https://api.lockally.com
description: Production
- url: http://127.0.0.1:8081
description: Local development / spike
security:
- bearerAuth: []
tags:
- name: mailboxes
description: Mailboxes on verified tenant domains
paths:
/v1/mailboxes:
get:
operationId: listMailboxes
tags:
- mailboxes
summary: List mailboxes
description: 'Returns mailboxes under the calling tenant, active and soft-deleted.
`?limit=N` between 1 and 200 (default 50).'
x-required-scope: mailboxes:read
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 200
default: 50
responses:
'200':
description: Mailbox list.
content:
application/json:
schema:
type: object
required:
- data
- limit
properties:
data:
type: array
items:
$ref: '#/components/schemas/Mailbox'
limit:
type: integer
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
post:
operationId: createMailbox
tags:
- mailboxes
summary: Create a mailbox
description: 'Creates a mailbox on a tenant-verified domain. If `password` is
omitted, lockally generates a 16-char password and returns it in the
response, shown once.
**Gate.** The mailbox''s domain must already be registered AND
verified for this tenant (via `/v1/domains` + `/v1/domains/{domain}/verify`).
**Idempotent.** Re-posting the same email returns the existing
mailbox UNTOUCHED, password is NOT regenerated. To change a
password, use PATCH instead.'
x-required-scope: mailboxes:write
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
example: alice@acme.com
password:
type: string
minLength: 8
description: Optional; lockally generates if absent.
quota_bytes:
type: integer
format: int64
default: 5368709120
description: 5 GB default.
responses:
'200':
description: Mailbox already existed for this tenant (idempotent).
content:
application/json:
schema:
$ref: '#/components/schemas/Mailbox'
'201':
description: Mailbox created. `password` is in the response ONLY if generated.
content:
application/json:
schema:
$ref: '#/components/schemas/Mailbox'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'409':
description: Email claimed by another tenant.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/mailboxes/{email}:
parameters:
- name: email
in: path
required: true
schema:
type: string
format: email
get:
operationId: getMailbox
tags:
- mailboxes
summary: Get a mailbox
x-required-scope: mailboxes:read
responses:
'200':
description: Mailbox info.
content:
application/json:
schema:
$ref: '#/components/schemas/Mailbox'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
patch:
operationId: updateMailbox
tags:
- mailboxes
summary: Update a mailbox
description: 'Supply at least one of `password`, `quota_bytes`, `disabled`.
Returns the updated mailbox.'
x-required-scope: mailboxes:write
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
password:
type: string
minLength: 8
quota_bytes:
type: integer
format: int64
minimum: 0
disabled:
type: boolean
responses:
'200':
description: Updated mailbox.
content:
application/json:
schema:
$ref: '#/components/schemas/Mailbox'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
delete:
operationId: deleteMailbox
tags:
- mailboxes
summary: Soft-delete a mailbox
description: 'Sets `soft_deleted_at = now()` and `hard_delete_after = now() + 90d`
per design D25. A background sweep (planned) will hard-delete after
the window. The mailbox is also disabled immediately.'
x-required-scope: mailboxes:write
responses:
'204':
description: Soft-deleted.
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
/v1/mailboxes/{email}/export:
parameters:
- name: email
in: path
required: true
schema:
type: string
post:
operationId: exportMailbox
tags:
- mailboxes
summary: Request a mailbox export
description: 'Issues a one-shot "presigned" download URL for the mailbox''s content
in mbox format. The URL works without an Authorization header, the
token in the query string is the authz. TTL is 5 minutes; the token
is consumed on first GET.
**v1 caveat:** the synthesized mbox only contains outbound mail
(sent mail only). A later version will cover received mail
for full inbox + folder structure + flags. The endpoint contract
stays unchanged.
**Scope changed:** this used to accept `mailboxes:read`. It takes any
mailbox in the tenant and returns that mailbox''s mail, so it now
requires `tenant:admin`, matching `POST /v1/ediscovery/export`. A key
scoped `mailboxes:read` gets 403 and has to be reissued; admin console
sessions are unaffected.'
x-required-scope: tenant:admin
responses:
'201':
description: Export token issued.
content:
application/json:
schema:
type: object
required:
- url
- expires_at
- format
properties:
url:
type: string
description: Relative download URL. Caller appends to the API host.
expires_at:
type: string
format: date-time
format:
type: string
enum:
- mbox
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
/v1/mailboxes/{email}/export/download:
parameters:
- name: email
in: path
required: true
schema:
type: string
- name: token
in: query
required: true
schema:
type: string
get:
operationId: downloadMailboxExport
tags:
- mailboxes
summary: Download a previously-issued mailbox export
description: 'Public endpoint (no Authorization header). Validates the one-shot
token from the URL, marks it used, and streams an mbox file. Second
GET with the same token returns 404, tokens are single-use.'
security: []
responses:
'200':
description: mbox stream.
content:
application/mbox:
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/ProblemBadRequest'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
description: Token not found, already used, or expired.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/mailboxes/{email}/members:
parameters:
- name: email
in: path
required: true
schema:
type: string
format: email
get:
tags:
- mailboxes
summary: List shared mailbox members
operationId: listSharedMembers
x-required-scope: mailboxes:read
responses:
'200':
description: Members of the shared mailbox.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/SharedMember'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
post:
tags:
- mailboxes
summary: Add a shared mailbox member
operationId: addSharedMember
x-required-scope: mailboxes:write
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- member_email
properties:
member_email:
type: string
format: email
role:
type: string
enum:
- manager
- member
default: member
responses:
'201':
description: Member added.
content:
application/json:
schema:
$ref: '#/components/schemas/SharedMember'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
'409':
description: Already a member of this mailbox.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/mailboxes/{email}/members/{memberEmail}:
parameters:
- name: email
in: path
required: true
schema:
type: string
format: email
- name: memberEmail
in: path
required: true
schema:
type: string
format: email
delete:
tags:
- mailboxes
summary: Remove a shared mailbox member
operationId: removeSharedMember
x-required-scope: mailboxes:write
responses:
'204':
description: No content
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
components:
responses:
ProblemForbidden:
description: API key lacks the required scope.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemBadRequest:
description: Malformed request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemUnauthorized:
description: Missing, malformed, or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemNotFound:
description: Resource not found under the calling tenant.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Mailbox:
type: object
required:
- id
- tenant_id
- domain_id
- email
- quota_bytes
- disabled
- created_at
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
domain_id:
type: string
format: uuid
email:
type: string
format: email
quota_bytes:
type: integer
format: int64
disabled:
type: boolean
disabled_at:
type: string
format: date-time
nullable: true
soft_deleted_at:
type: string
format: date-time
nullable: true
hard_delete_after:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
password:
type: string
description: ONLY present on POST response when lockally generated the password. Shown once.
SharedMember:
type: object
required:
- id
- mailbox_id
- tenant_id
- member_email
- role
- created_at
properties:
id:
type: string
format: uuid
mailbox_id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
member_email:
type: string
format: email
role:
type: string
enum:
- manager
- member
created_at:
type: string
format: date-time
Problem:
description: RFC 9457 problem-details document.
type: object
required:
- type
- status
- title
properties:
type:
type: string
format: uri
default: about:blank
status:
type: integer
title:
type: string
detail:
type: string
instance:
type: string
format: uri
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: lk_live_<prefix>_<secret>
description: API key, format `lk_live_<8-char-prefix>_<32-char-secret>`.
oauth2:
type: oauth2
description: 'OAuth 2.1 (authorization code + PKCE). The access token is sent as the
`Authorization: Bearer` credential, exactly like an API key, so any SDK
that accepts a bearer token works with OAuth. Discovery:
`/.well-known/oauth-authorization-server`.
'
flows:
authorizationCode:
authorizationUrl: https://api.lockally.com/oauth/authorize
tokenUrl: https://api.lockally.com/oauth/token
scopes:
inboxes:read: Read agent-accessible mailboxes and threads
inboxes:write: Send and act on agent-accessible mailboxes