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.