mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 10:58:17 +00:00
Wez Furlong
70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
---
|
|
tags:
|
|
- meta
|
|
---
|
|
|
|
# set_meta
|
|
|
|
```lua
|
|
message:set_meta(KEY, VALUE)
|
|
```
|
|
|
|
Messages are associated with some metadata. You can think of this metadata
|
|
as being equivalent to a JSON object.
|
|
|
|
The `set_meta` method allows you to set a field of that object to a value
|
|
that you specify.
|
|
|
|
You can assign any value that is serializable as a JSON:
|
|
|
|
```lua
|
|
-- set foo='bar', a string value
|
|
msg:set_meta('foo', 'bar')
|
|
|
|
-- set foo=123, a numeric value
|
|
msg:set_meta('foo', 123)
|
|
|
|
-- set foo=true, a boolean value
|
|
msg:set_meta('foo', true)
|
|
|
|
-- set foo={key="value"}, an object value
|
|
msg:set_meta('foo', { key = 'value' })
|
|
```
|
|
|
|
You can retrieve a metadata value via [message:get_meta](get_meta.md).
|
|
|
|
## Naming convention for user-defined keys
|
|
|
|
KumoMTA reserves a set of predefined meta keys (see [Predefined Metadata](../metadata.md)) and may add more over time. To avoid collisions with current and future predefined keys, prefix your own meta keys with `x_`.
|
|
|
|
This aligns with the `x_*` keys produced by
|
|
[message:import_x_headers](import_x_headers.md) and the default
|
|
`snake_case` transform used by [message:import_headers](import_headers.md),
|
|
and KumoMTA's own predefined meta keys will never start with `x_`.
|
|
|
|
```lua
|
|
-- recommended for application-specific data
|
|
msg:set_meta('x_campaign_id', '12345')
|
|
msg:set_meta('x_my_app_flag', true)
|
|
```
|
|
|
|
## Pre-defined meta values
|
|
|
|
The following meta values are unique to the message scope:
|
|
|
|
<style>
|
|
table tbody tr td:nth-of-type(2) {
|
|
white-space: nowrap;
|
|
}
|
|
</style>
|
|
|
|
|Scope|Name|Purpose|Since|
|
|
|----|----|-------|-----|
|
|
|Message|`queue`|specify the name of the queue to which the message will be queued. Must be a string value.||
|
|
|Message|`tenant`|specify the name/identifier of the tenant, if any. Must be a string value.||
|
|
|Message|`campaign`|specify the name/identifier of the campaign. Must be a string value.||
|
|
|Message|`routing_domain`|Overrides the domain of the recipient domain for routing purposes.|{{since('2023.08.22-4d895015', inline=True)}}|
|
|
|
|
!!! Note
|
|
Additional metadata is available in the message scope that is copied in from the connection scope, for a full list of all available metadata, see the [Predefined Metadata](../metadata.md) page.
|