Sending and messages
Submit mail, then track what happened to it.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List outbound messages
GET /v1/messages · scope send:read
Returns recent outbound messages for the calling tenant, sorted newest first.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
status |
query | string (queued, sending, delivered, bounced, deferred, complaint) |
|
sender |
query | string | Exact match against the from mailbox. |
tag |
query | string | 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. |
q |
query | string | Free-text search across subject + sender. |
since |
query | string | Only messages queued at or after this RFC 3339 instant. |
cursor |
query | string | queued_at of the prior page boundary. Pass back the next_cursor returned by the previous call. |
limit |
query | integer | |
sort |
query | string (queued_at, updated_at) |
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. |
order |
query | string (asc, desc) |
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. |
Response 200
List of messages + optional next-page cursor.
| Field | Type | Notes |
|---|---|---|
data |
array of Message | Required. |
next_cursor |
string | Pass as cursor to fetch the next page. Absent on the final page. |
Errors: 401, 403
Aggregate delivery stats
GET /v1/messages/stats · scope send:read
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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
from |
query | string | Window start (default 7 days ago). |
to |
query | string | Window end (default now). |
domain |
query | string | Filter by sender domain. |
tag |
query | string | 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. |
Response 200
Stats.
| Field | Type | Notes |
|---|---|---|
window |
object | |
domain |
string | |
sent |
integer | |
counts |
object | |
rates |
object |
Errors: 400, 401
Get message status
GET /v1/messages/{id} · scope send:read
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id |
path | string | Required. |
Response 200
Message record with the content captured at send time.
Errors: 401, 403, 404
Cancel a scheduled send
DELETE /v1/messages/{id} · scope send:write
Cancels a still-scheduled message (future queued_at). Already sending/sent → 409.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id |
path | string | Required. |
Response 204
Cancelled.
Errors: 404, 409
Send an email
POST /v1/send · scope send:write
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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
Idempotency-Key |
header | string | Required. |
Request body
| Field | Type | Notes |
|---|---|---|
from |
string | Required. |
to |
array of string | Required. |
cc |
array of string | |
bcc |
array of string | |
subject |
string | |
text |
string | Plain-text body. Required if html is absent. |
html |
string | HTML body. Required if text is absent. |
headers |
object | |
reply_to |
string | 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 |
string | 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 |
boolean | Mark as opt-in/broadcast: skips suppressed recipients and adds a managed one-click List-Unsubscribe header. |
template_id |
string | Render subject/text/html from a stored template (GET /v1/templates). Mutually exclusive with inline subject/text/html. |
variables |
object | Values substituted into the template’s {{variable}} placeholders. |
send_at |
string | Schedule delivery for a future RFC3339 time (≤ 30 days out). Omit or past = send now. Cancel with DELETE /v1/messages/{id} while scheduled. |
metadata |
object | 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 |
array of string | 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 |
boolean | 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 |
boolean | 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 |
array of object |
Response 200
Accepted, but nothing was queued for real delivery. Two cases, told
apart by status:
suppressed, every recipient was on your suppression list, so the send was dropped. Deliberately a success, not a retryable error: retrying cannot change the outcome. There is noidormessage_id, because no message was created. Complaint and bounce suppressions block every send; unsubscribe and manual suppressions block only opt-in sends (unsubscribe: true).delivered, the call used a test key (lk_test_). The message is recorded and adelivery.deliveredwebhook fires with a simulated250 OK, but nothing leaves the platform. Test sends count against nothing: not your rate cap, allowance, send units, the warm-up ramp, or your reputation.
| Field | Type | Notes |
|---|---|---|
id |
string | Present on a test-mode send; absent when suppressed. |
message_id |
string | RFC 5322 Message-ID. On a test send the domain is test.lockally.com. Absent when suppressed. |
status |
string (suppressed, delivered) |
Required. |
warning |
string | On a suppressed send, explains that nothing was sent. |
Errors: 400, 401, 403, 429
Send a batch of emails
POST /v1/send/batch · scope send:write
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 <key>:<index>.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
Idempotency-Key |
header | string | Required. |
Request body
| Field | Type | Notes |
|---|---|---|
messages |
array of SendMessage | Required. |
variables |
object | 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. |
Response 200
Per-message results (partial success).
| Field | Type | Notes |
|---|---|---|
data |
array of BatchResult |
Errors: 400, 401, 403