Lockally Send API
Programmatic outbound mail (single, batch, scheduled, templated) + delivery stats
Programmatic outbound mail (single, batch, scheduled, templated) + delivery stats
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-send-api"
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.
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: 3.2.0
info:
title: lockally control plane Send 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: Send
description: Programmatic outbound mail (single, batch, scheduled, templated) + delivery stats
paths:
/v1/send:
post:
operationId: sendEmail
tags:
- Send
summary: Send an email
description: 'Submits an email for delivery via lockally. Returns 202 immediately
once the message is accepted into lockally''s queue; the actual SMTP
submission to the recipient is async. Track delivery via
`GET /v1/messages/{id}` or webhook subscriptions for
`delivery.delivered` / `delivery.bounced` / `delivery.complaint`.
**Idempotency-Key required.** Any unique string per
send, 24-hour dedupe window. Repeated calls with the same key
return byte-exact the original response and do NOT create a
duplicate message.
**Sender authorisation.** `from` must be an address the calling
tenant owns on a verified domain. A mailbox always qualifies. On
business and combined accounts an **alias** qualifies too, so a
send-only address such as `no-reply@` need not be a billed seat.
An alias on an unverified domain, or one belonging to another
account, is refused with `403`. A catch-all creates no aliases and
so grants no sending rights.
**Rate cap.** Per-tenant `rate_cap_per_min` (returned on
`/v1/tenant`) is enforced, 429 with `Retry-After: 60` once tripped.
**Recipient warning.** Over 25 total recipients (To+Cc+Bcc) sets a
`warning` field in the response, large fan-outs queue noticeably
at scale. Hard cap is 100/send.
**Not every success is a 202.** Check the status code, not just the
body. A `200` means nothing was queued: either every recipient was
already suppressed, or the call used a test key and the send was
simulated. Both are successes, and neither produces a real delivery.
See the `200` response below.
**Warm-up headers.** While the platform is in its outbound warm-up
ramp, accepted sends carry `X-Warmup-Day`, `X-Warmup-Daily-Cap` and
`X-Warmup-Used-Today`. They describe a platform-wide cap shared by
every tenant, not your own allowance, and they disappear once the
ramp finishes. Hitting the cap returns 429.'
x-required-scope: send:write
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
maxLength: 255
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from
- to
properties:
from:
type: string
format: email
to:
type: array
items:
type: string
format: email
minItems: 1
cc:
type: array
items:
type: string
format: email
bcc:
type: array
items:
type: string
format: email
subject:
type: string
text:
type: string
description: Plain-text body. Required if `html` is absent.
html:
type: string
description: HTML body. Required if `text` is absent.
headers:
type: object
additionalProperties:
type: string
reply_to:
type: string
format: email
description: Where replies go. REQUIRED when `from` has no mailbox behind it, since a reply there would be delivered nowhere. A `Reply-To` entry in `headers` satisfies the same rule. The named form `Acme Support <a@b.com>` is also accepted.
reply_to_name:
type: string
description: Display name shown on `Reply-To`, e.g. `Acme Support`. Ignored without `reply_to`. Encoded and quoted for you, so accents, commas and quotes are all safe.
unsubscribe:
type: boolean
description: 'Mark as opt-in/broadcast: skips suppressed recipients and adds a managed one-click List-Unsubscribe header.'
template_id:
type: string
format: uuid
description: Render subject/text/html from a stored template (GET /v1/templates). Mutually exclusive with inline subject/text/html.
variables:
type: object
additionalProperties:
type: string
description: Values substituted into the template's {{variable}} placeholders.
send_at:
type: string
format: date-time
description: Schedule delivery for a future RFC3339 time (≤ 30 days out). Omit or past = send now. Cancel with DELETE /v1/messages/{id} while scheduled.
metadata:
type: object
additionalProperties:
type: string
maxProperties: 20
description: 'Arbitrary key/value you attach to this message and get back
on every delivery webhook for it, so a send can be matched
to your own records without a lookup table.
**It never leaves Lockally.** A custom entry in `headers`
goes out on the wire to the recipient, which is why that is
not a substitute: order ids and internal identifiers do not
belong in a header the recipient can read.
At most 20 keys, keys at most 64 characters, values at most
512. **Over a limit is refused with a `400`, never
truncated**: a silently shortened order id succeeds and then
fails to match weeks later.
Not indexed and not filterable.
'
tags:
type: array
items:
type: string
maxLength: 32
maxItems: 10
description: 'Labels that group this send for filtering and analytics:
campaign, template, environment.
**Lowercased, trimmed and deduplicated on write**, so the
grouping does not depend on every caller spelling them
identically. `Campaign-X` is stored as `campaign-x`, and
either spelling matches it in a filter.
At most 10 per message after deduplication, each at most 32
characters. Over either is a `400` rather than a trimmed
list: a send missing the tag it was tagged for is worse than
a refusal.
Unlike `metadata`, tags ARE queryable: filter with
`GET /v1/messages?tag=` and group with
`GET /v1/messages/stats?tag=`.
'
track_opens:
type: boolean
description: 'Override the account''s open-tracking setting for this one
send. Omit to inherit it.
Three states matter here: `true`, `false`, and absent. A
transactional receipt can set `false` without the account
turning tracking off for its marketing.
'
track_clicks:
type: boolean
description: 'As `track_opens`, for click tracking. Click tracking
rewrites `http(s)` links in the **HTML** part only: the
plain-text part is never rewritten, because a visible
redirect URL is what recipients complain about. A
text-only send is therefore not click-tracked.
'
attachments:
type: array
items:
type: object
required:
- filename
- content_type
- content_base64
properties:
filename:
type: string
content_type:
type: string
example: application/pdf
content_base64:
type: string
description: Base64-encoded body, max 10 MB decoded per attachment.
responses:
'200':
description: "Accepted, but nothing was queued for real delivery. Two cases, told\napart by `status`:\n\n- `suppressed`, every recipient was on your suppression list, so\n the send was dropped. Deliberately a success, not a retryable\n error: retrying cannot change the outcome. There is no `id` or\n `message_id`, because no message was created. Complaint and\n bounce suppressions block every send; unsubscribe and manual\n suppressions block only opt-in sends (`unsubscribe: true`).\n- `delivered`, the call used a test key (`lk_test_`). The message\n is recorded and a `delivery.delivered` webhook fires with a\n simulated `250 OK`, but nothing leaves the platform. Test sends\n count against nothing: not your rate cap, allowance, send units,\n the warm-up ramp, or your reputation.\n"
content:
application/json:
schema:
type: object
required:
- status
properties:
id:
type: string
format: uuid
description: Present on a test-mode send; absent when suppressed.
message_id:
type: string
description: RFC 5322 Message-ID. On a test send the domain is test.lockally.com. Absent when suppressed.
status:
type: string
enum:
- suppressed
- delivered
warning:
type: string
description: On a suppressed send, explains that nothing was sent.
examples:
suppressed:
summary: Every recipient suppressed
value:
status: suppressed
warning: All recipients are on your suppression list; nothing was sent.
testMode:
summary: Simulated send on a test key
value:
id: 9f1c2b7a-3d4e-4f56-8a9b-0c1d2e3f4a5b
message_id: <9f1c2b7a-3d4e-4f56-8a9b-0c1d2e3f4a5b@test.lockally.com>
status: delivered
'202':
description: Queued for delivery.
headers:
Idempotent-Replay:
schema:
type: string
description: '"true" when the response is replayed from the idempotency cache.'
X-Warmup-Day:
schema:
type: integer
description: 'Present only during the platform''s outbound warm-up ramp: which day of the ramp this send landed on.'
X-Warmup-Daily-Cap:
schema:
type: integer
description: 'Warm-up ramp only: total messages the whole platform may send today, shared across all tenants.'
X-Warmup-Used-Today:
schema:
type: integer
description: 'Warm-up ramp only: how much of that platform-wide cap was already used when this send was accepted.'
content:
application/json:
schema:
type: object
required:
- id
- message_id
- status
properties:
id:
type: string
format: uuid
description: Lockally identifier; use with GET /v1/messages/{id}.
message_id:
type: string
description: RFC 5322 Message-ID (with angle brackets).
status:
type: string
enum:
- queued
- scheduled
description: '"scheduled" when send_at is in the future.'
warning:
type: string
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'429':
description: 'Rate limited. Either your per-tenant `rate_cap_per_min`, or the
platform-wide warm-up cap for the day (which resets at UTC
midnight, so `Retry-After` can be hours rather than 60 seconds).
'
headers:
Retry-After:
schema:
type: integer
description: 60 for the per-tenant cap; seconds until UTC midnight when the warm-up cap is what was hit.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/send/batch:
post:
operationId: sendEmailBatch
tags:
- Send
summary: Send a batch of emails
description: 'Sends up to 500 messages in one call. Each is validated and enqueued
independently, a bad message fails only its own slot (partial success,
HTTP 200). One `Idempotency-Key` header covers the batch; per-message
keys are derived as `:`.'
x-required-scope: send:write
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
maxLength: 200
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- messages
properties:
messages:
type: array
minItems: 1
maxItems: 500
items:
$ref: '#/components/schemas/SendMessage'
variables:
type: object
additionalProperties:
type: string
description: 'Template variables every message in the batch inherits.
Each message''s own `variables` override these key by key,
so shared values are written once and per-recipient ones
stay per-recipient.
Without this, a 500-message batch repeats every shared
variable 500 times: most of the payload, and 500 places for
one of them to differ by a typo.
'
responses:
'200':
description: Per-message results (partial success).
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BatchResult'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/messages/stats:
get:
operationId: getMessageStats
tags:
- Send
summary: Aggregate delivery stats
description: 'Counts by delivery outcome (delivered/bounced/deferred/complaint) plus
rates over a window, from the delivery-event store. Privacy-first: this
reflects what receiving servers reported, NOT whether a human opened the
mail, Lockally does no open/click tracking.'
x-required-scope: send:read
parameters:
- name: from
in: query
schema:
type: string
format: date-time
description: Window start (default 7 days ago).
- name: to
in: query
schema:
type: string
format: date-time
description: Window end (default now).
- name: domain
in: query
schema:
type: string
description: Filter by sender domain.
- name: tag
in: query
schema:
type: string
description: 'Group the window by the sender''s own tags: one tag, or a comma-separated set meaning ANY. Case-insensitive. This is the dimension that tells a transactional stream from a notification one.'
responses:
'200':
description: Stats.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageStats'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
/v1/messages/{id}:
get:
operationId: getMessage
tags:
- Send
summary: Get message status
x-required-scope: send:read
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Message record with the content captured at send time.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageDetail'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
delete:
operationId: cancelMessage
tags:
- Send
summary: Cancel a scheduled send
description: Cancels a still-scheduled message (future queued_at). Already sending/sent → 409.
x-required-scope: send:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Cancelled.
'404':
$ref: '#/components/responses/ProblemNotFound'
'409':
description: Not cancellable (already sending or sent).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/messages:
get:
operationId: listMessages
tags:
- Send
summary: List outbound messages
description: 'Returns recent outbound messages for the calling tenant, sorted
newest first.'
x-required-scope: send:read
parameters:
- name: status
in: query
schema:
type: string
enum:
- queued
- sending
- delivered
- bounced
- deferred
- complaint
- name: sender
in: query
schema:
type: string
description: Exact match against the `from` mailbox.
- name: tag
in: query
schema:
type: string
description: 'Filter to messages carrying any of these tags. One tag, or a comma-separated set meaning ANY. Case-insensitive: the value is normalised the same way tags are on write.'
- name: q
in: query
schema:
type: string
description: Free-text search across subject + sender.
- name: since
in: query
schema:
type: string
format: date-time
description: Only messages queued at or after this RFC 3339 instant.
- name: cursor
in: query
schema:
type: string
description: queued_at of the prior page boundary. Pass back the `next_cursor` returned by the previous call.
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 200
- name: sort
in: query
schema:
type: string
enum:
- queued_at
- updated_at
default: queued_at
description: 'Field to order by. Only indexed columns are offered: an unindexed sort on this table is a full scan of the account''s send history. status and sender are filters instead.'
- name: order
in: query
schema:
type: string
enum:
- asc
- desc
description: Defaults to desc for the default field and asc for any other. The order is always made total by a tie-break on id, so paging cannot repeat or skip a row that shares a timestamp. cursor encodes queued_at, so combining it with another sort is a 400 rather than a wrong page.
responses:
'200':
description: List of messages + optional next-page cursor.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Message'
next_cursor:
type: string
description: Pass as `cursor` to fetch the next page. Absent on the final page.
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
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:
MessageStats:
type: object
properties:
window:
type: object
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
domain:
type: string
sent:
type: integer
counts:
type: object
properties:
delivered:
type: integer
bounced:
type: integer
deferred:
type: integer
complaint:
type: integer
rates:
type: object
properties:
delivered:
type: number
format: float
bounced:
type: number
format: float
deferred:
type: number
format: float
complaint:
type: number
format: float
BatchResult:
type: object
properties:
index:
type: integer
id:
type: string
format: uuid
message_id:
type: string
status:
type: string
enum:
- queued
- scheduled
- suppressed
- delivered
description: '"suppressed" means every recipient of that slot was on your suppression list, and it carries no id or message_id. "delivered" only appears on a test key: the send was simulated, not transmitted.'
error:
type: string
description: Present when this message failed; the others are then absent.
warning:
type: string
description: Advisory, and NOT a failure. Today the only one is a template variable the template referenced and the request never supplied, which rendered as the empty string.
Message:
type: object
required:
- id
- tenant_id
- message_id
- sender
- recipients
- status
- queued_at
- updated_at
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
message_id:
type: string
description: RFC 5322 Message-ID header, including angle brackets.
sender:
type: string
format: email
recipients:
type: array
items:
type: string
format: email
subject:
type: string
nullable: true
status:
type: string
enum:
- queued
- sending
- delivered
- bounced
- deferred
- complaint
queued_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
bounce_reason:
type: string
nullable: true
size_bytes:
type: integer
nullable: true
metadata:
type: object
additionalProperties:
type: string
description: The sender's own key/value from the send request. Always present; `{}` when none was set.
tags:
type: array
items:
type: string
description: Grouping labels, lowercased and deduplicated. Always present; `[]` when none were set.
SendMessage:
type: object
required:
- from
- to
properties:
from:
type: string
format: email
to:
type: array
items:
type: string
format: email
minItems: 1
cc:
type: array
items:
type: string
format: email
bcc:
type: array
items:
type: string
format: email
subject:
type: string
text:
type: string
html:
type: string
headers:
type: object
additionalProperties:
type: string
reply_to:
type: string
format: email
description: Where replies go. Required when `from` has no mailbox behind it. The named form `Acme Support <a@b.com>` is also accepted.
reply_to_name:
type: string
description: Display name shown on `Reply-To`. Ignored without `reply_to`.
unsubscribe:
type: boolean
template_id:
type: string
format: uuid
variables:
type: object
additionalProperties:
type: string
send_at:
type: string
format: date-time
attachments:
type: array
items:
type: object
required:
- filename
- content_type
- content_base64
properties:
filename:
type: string
content_type:
type: string
content_base64:
type: string
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
MessageDetail:
description: 'A single message with the content captured at send time. Returned only by GET /v1/messages/{id} (the list stays summary-only). Attachments are not returned.
'
allOf:
- $ref: '#/components/schemas/Message'
- type: object
properties:
from:
type: string
format: email
to:
type: array
items:
type: string
format: email
cc:
type: array
items:
type: string
format: email
bcc:
type: array
items:
type: string
format: email
text:
type: string
html:
type: string
headers:
type: object
additionalProperties:
type: string
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