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"const message = await lockally.messagesApi.getMessage({ id: messageId });
console.log(message.metadata?.order_id);message = messages_api.get_message(id=message_id)
print(message.metadata.get("order_id"))msg, _, err := client.MessagesAPI.GetMessage(ctx, messageID).Execute()
if err != nil {
return err
}
fmt.Println(msg.Metadata["order_id"])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.