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.

      Metadata

      metadata is arbitrary key/value you attach to a message. Lockally stores it, never sends it, and returns it on every delivery webhook for that message.

      That last part is the whole feature. Without it, correlating a delivery.bounced webhook with the order it belongs to means keeping your own table of Lockally message ids, writing to it on every send, and reading it on every webhook. With it, the webhook already carries your order id.

      curl -X POST https://api.lockally.com/v1/send \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Idempotency-Key: order-1042-receipt" \
        -H "Content-Type: application/json" \
        -d '{
          "from": "receipts@yourdomain.com",
          "to": ["customer@example.com"],
          "subject": "Your receipt",
          "text": "Thanks for your order.",
          "metadata": { "order_id": "A-1042", "customer_ref": "acct_77" }
        }'

      Every delivery event for that message then carries it:

      {
        "id": "evt_9f2c...",
        "type": "delivery.bounced",
        "data": {
          "message_id": "7f3b...",
          "recipient": "customer@example.com",
          "smtp_code": "550",
          "metadata": { "order_id": "A-1042", "customer_ref": "acct_77" }
        }
      }

      Limits, and why they refuse instead of truncating

      Keys per message 20
      Key length 64 characters
      Value length 512 characters

      Exceeding any of these is a 400, never a truncation. That is deliberate. A silently shortened order id produces a send that succeeds, a webhook that arrives, and a key that is a prefix of the one you meant to match on. The failure surfaces weeks later, to whoever is reconciling. A 400 surfaces now, to the developer writing the integration.

      Lengths are counted in characters rather than bytes, so a non-ASCII value is measured by what you wrote and not by how UTF-8 happens to encode it.

      Reading it back

      GET /v1/messages/{id} returns metadata alongside the rest of the message. It is always present, as {} when the send set none, so you never need a null check.

      curl https://api.lockally.com/v1/messages/$MESSAGE_ID \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"

      What it is not for

      Not searchable. There is no endpoint that filters by metadata, and it is not indexed. To group sends by campaign, template or environment and see them in analytics, use tags.

      Not a place for personal data you would not otherwise keep. It is stored for as long as the message row is, and it appears in webhook payloads your endpoint logs. Putting a recipient’s full name or address in metadata makes it part of two more systems than it needs to be.

      Not mutable. Metadata is fixed at send time. There is no endpoint to change it afterwards, because the delivery events that carry it may already have fired.