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.

      Templates and personalization

      Store a message once and send it with values filled in, instead of building the body in your application every time.

      {
        "from": "receipts@yourcompany.com",
        "to": ["alice@example.com"],
        "template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
        "variables": {
          "name": "Alice",
          "order_id": "12345"
        }
      }

      The template supplies the subject and body; variables fills its placeholders. Manage templates with GET /v1/templates and the rest of the templates endpoints.

      Template and inline content are mutually exclusive

      Send template_id together with any of subject, text or html and the request is rejected:

      {
        "status": 400,
        "title": "Template conflict",
        "detail": "Provide either template_id or inline subject/text/html, not both."
      }

      There is no partial override. You cannot keep a template’s body and replace just its subject; the template owns all three fields or none of them.

      The placeholder syntax

      Placeholders are {{name}}, Mustache-style. Whitespace inside the braces is tolerated, so {{ name }} is the same placeholder. Names may contain letters, digits, underscores, dots and hyphens.

      It is deliberately not a template language. There are no conditionals, no loops, no sections and no partials, only substitution. A template is authored by a tenant and rendered on our servers, so anything more expressive would be a way to run logic inside the platform.

      Behaviour
      Placeholder with a matching variable replaced with the value
      Placeholder with no matching variable replaced with an empty string
      Variable with no matching placeholder ignored

      Values are escaped in HTML, and not in text

      When rendering the html field, substituted values are HTML-escaped, so a variable containing <b> arrives as visible text rather than markup. That is what stops a value from injecting layout into your template.

      The text and subject fields are not escaped, which is correct for plain text but means a value containing a newline would end a subject line early. Strip control characters from anything you pass as a subject variable.

      Personalization is per send, not per recipient

      This is the limit worth understanding before you design around templates.

      variables applies to the whole request. A send with ten recipients renders the template once and delivers the identical body to all ten:

      {
        "to": ["alice@example.com", "bob@example.com"],
        "template_id": "...",
        "variables": { "name": "Alice" }
      }

      Bob receives a message addressed to Alice. There is no per-recipient variable map and no mail-merge.

      Genuine personalization means one message per recipient. Use batch sending, which takes up to 500 independent messages in one call, each with its own recipient and its own variables:

      {
        "messages": [
          {
            "from": "receipts@yourcompany.com",
            "to": ["alice@example.com"],
            "template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
            "variables": { "name": "Alice", "order_id": "12345" }
          },
          {
            "from": "receipts@yourcompany.com",
            "to": ["bob@example.com"],
            "template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
            "variables": { "name": "Bob", "order_id": "12346" }
          }
        ]
      }

      That also gives each recipient their own message id, delivery event and bounce, which a single multi-recipient send cannot.

      Variables are strings

      variables is a flat map of string to string. There are no nested objects, no arrays and no numbers: format values in your application before sending them.

      A non-string value does not render as blank, it rejects the whole request with 400 Invalid JSON body before anything else is looked at. Quote it: "49.99", not 49.99. null is the exception and renders as an empty string.

      Going further

      This page covers sending with a template. The rest of the template surface has its own section:

      Personalising per recipient

      This is the part that catches people out, and the reason is simpler than it looks: one email message has one body. That is RFC 5322, not a Lockally limitation. A single POST /v1/send with ten addresses in to is one message, so variables are rendered once and all ten recipients receive identical content.

      For per-recipient content you need one message per recipient, which is what POST /v1/send/batch is:

      curl -X POST https://api.lockally.com/v1/send/batch \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Idempotency-Key: welcome-run-9981" \
        -H "Content-Type: application/json" \
        -d '{
          "variables": { "brand": "Acme", "year": "2026" },
          "messages": [
            { "from": "hello@yourdomain.com", "to": ["ada@example.com"],
              "template_id": "...", "variables": { "first_name": "Ada" } },
            { "from": "hello@yourdomain.com", "to": ["grace@example.com"],
              "template_id": "...", "variables": { "first_name": "Grace" } }
          ]
        }'

      The top-level variables are shared defaults. Every message inherits them, and each message’s own variables override them key by key. Without that, a 500-message batch repeats brand and year 500 times: most of the payload, and 500 places for one of them to differ by a typo.

      Each message is rendered, validated and enqueued on its own, and a bad one fails only its own slot. A batch is capped at 500 messages.