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.

      Tags

      tags are short labels you attach to a send so you can ask questions about a group of messages afterwards: how did this campaign deliver, is the staging environment bouncing, which template is generating complaints.

      curl -X POST https://api.lockally.com/v1/send \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Idempotency-Key: welcome-9981" \
        -H "Content-Type: application/json" \
        -d '{
          "from": "hello@yourdomain.com",
          "to": ["customer@example.com"],
          "subject": "Welcome",
          "text": "Thanks for signing up.",
          "tags": ["onboarding", "welcome-v3"]
        }'

      Tags against metadata

      These look similar and are for opposite things. Picking the wrong one is the most common mistake here.

      tags metadata
      Shape A short list of labels Key/value
      Scope A small set shared across many messages Unique to one message
      Queryable Yes. Filter and aggregate by them No. Not indexed, not filterable
      On the webhook No Yes, on every delivery event
      Use it for Campaign, template, environment An order id, a customer reference

      If you find yourself putting an order id in a tag, you want metadata. If you find yourself putting "campaign": "x" in metadata and wishing you could group by it, you want a tag.

      Normalised on write

      Tags are lowercased, trimmed and deduplicated when the send is accepted. ["Welcome-V3", "welcome-v3 "] is stored as ["welcome-v3"].

      That is deliberate, and it is why the grouping works at all: without it, the answer to “how did welcome-v3 deliver” depends on every caller in your codebase having spelled it the same way. Filters normalise the same way, so ?tag=Welcome-V3 and ?tag=welcome-v3 return the same rows.

      Limits: 10 tags per message after deduplication, 32 characters each. Over either is a 400, not a trimmed list. A send that silently dropped a tag would succeed and then be missing from exactly the grouping it was tagged for.

      Filtering

      # One tag
      curl "https://api.lockally.com/v1/messages?tag=welcome-v3" \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"
      
      # Any of several
      curl "https://api.lockally.com/v1/messages?tag=welcome-v3,onboarding" \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"

      A comma-separated list means ANY, not all. There is no AND filter; if you need one, tag more precisely.

      Aggregating

      GET /v1/messages/stats takes the same parameter, which is what makes tags worth more than a label you can only read back:

      curl "https://api.lockally.com/v1/messages/stats?tag=welcome-v3&from=2026-10-01T00:00:00Z" \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"

      You get the same counts and rates as the unfiltered call, restricted to messages carrying that tag. Combine it with domain= to narrow further.

      What tags do not do

      They are not visible to recipients. Like metadata, tags are never written into the message.

      They are not mutable. Tags are fixed at send time, because the aggregates they feed may already have been read.

      They do not change delivery. A tag has no effect on routing, throttling or which IP pool a message uses. Sending streams are the mechanism for that, and they are a separate concept with a separate purpose: see Deliverability.