Lockally Send API

Programmatic outbound mail (single, batch, scheduled, templated) + delivery stats

GitHub OpenAPI

Operations 6

POST /v1/send Send an email #
POST /v1/send/batch Send a batch of emails #
GET /v1/messages/stats Aggregate delivery stats #
GET /v1/messages/{id} Get message status #
DELETE /v1/messages/{id} Cancel a scheduled send #
GET /v1/messages List outbound messages #

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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-send-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

lockally-com-send-api-openapi.yml Raw ↑
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