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.

      Batch sending

      POST /v1/send/batch

      Required scope: send:write

      A batch is a list of independent messages, each with its own sender, recipients and body. It is not a multi-recipient send: that is to, cc and bcc on a single call, and it produces one message, not many.

      Reach for a batch when each recipient needs something different, which is also the only way to personalise per recipient.

      Request

      {
        "messages": [
          {
            "from": "receipts@yourcompany.com",
            "to": ["alice@example.com"],
            "subject": "Order 12345 confirmed",
            "text": "Thanks, Alice."
          },
          {
            "from": "receipts@yourcompany.com",
            "to": ["bob@example.com"],
            "subject": "Order 12346 confirmed",
            "text": "Thanks, Bob."
          }
        ]
      }

      Each entry takes every field POST /v1/send takes, including template_id, variables, send_at, attachments and headers. The two messages in a batch need not resemble each other at all.

      Maximum messages 500 per batch
      Minimum 1. An empty messages array is 400 Empty batch
      Recipients the 100 cap applies per message, not per batch

      Idempotency

      One Idempotency-Key header covers the whole batch. Per-message keys are derived from it as <key>:<index>, so retrying a whole batch is safe: the messages that already went are replayed from cache, and only the ones that did not are sent.

      Because keys are positional, keep your ordering stable on a retry. Reorder the array and <key>:0 now refers to a different message, which defeats the deduplication.

      Response: partial success is the normal case

      A batch returns 200, not 202, and the body reports each message separately. A bad message fails only its own slot:

      {
        "data": [
          {
            "index": 0,
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "message_id": "<d290f1ee-6c54-4b01-90e6-d701748f0851@lockally.com>",
            "status": "queued"
          },
          {
            "index": 1,
            "error": "\"not-an-address\" is not a valid email address."
          }
        ]
      }
      Field Present when
      index always. The position in your request array, so you can correlate
      id the message was accepted. This is the id to store
      message_id the message was accepted
      status the message was processed without error. queued, scheduled, delivered (test key) or suppressed
      error the message was not accepted. A human-readable reason

      Entries come back in request order, but correlate on index rather than on array position.

      Whole-batch rejections

      Three things fail the entire call with a 4xx and no data at all:

      400 Missing Idempotency-Key the header is required
      400 Empty batch messages was absent or empty
      400 Batch too large more than 500 messages

      Rate limits and allowance are applied per message, not per batch, so a batch can partially succeed and then start returning quota errors in later entries once you cross a cap. Those appear as error strings on the affected slots.

      Choosing a batch size

      500 is the ceiling, not a recommendation. Each message is validated and enqueued in turn within a single request, so a very large batch holds the connection open for correspondingly longer. Batches in the low hundreds are a reasonable default, and smaller ones give you more useful retry granularity.