Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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 no id or message_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 a delivery.delivered webhook fires with a simulated 250 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