---
tags:
 - meta
---

# Predefined Metadata

KumoMTA provides the ability to set and retrieve metadata at both the connection and message level.

By leveraging metadata, information can be made available to policy running at
different phases in the life of a message, where the [connection
metadata](connectionmeta.md) is used for data that is shared in common with
all messages injected over a given connection, and the [message
metadata](message/set_meta.md) is for all data related to a given individual
message.

There are get and set functions available for both connection and message
metadata, and when a message is received **all connection metadata is also
copied into the message metadata**, meaning that for retrieving connection
metadata the user can opt to only access message metadata for any value that
doesn't change over the life of the connection.

The following metadata values are predefined by KumoMTA and are available to
retrieve. When defining your own meta keys via
[msg:set_meta](message/set_meta.md) or
[conn_meta:set_meta](connectionmeta.md), prefix them with `x_` to avoid
collisions with current and future predefined names; see the [naming
convention](message/set_meta.md#naming-convention-for-user-defined-keys) for
details.

<style>
table tbody tr td:nth-of-type(2) {
  white-space: nowrap;
}
</style>

|Scope|Name|Purpose|Since|
|----|----|-------|-----|
|Connection|`reception_protocol`|indicates the reception protocol, such as `ESMTP`|{{since('2023.08.22-4d895015', inline=True)}}|
|Connection|`received_via`|indicates the IP:port of the KumoMTA listener that is handling this session|{{since('2023.08.22-4d895015', inline=True)}}.<br> For HTTP injections {{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`orig_received_via`|Set when XCLIENT or other similar proxying is active; it indicates the raw IP:port of the KumoMTA listener that is handling this session, independent of any adjustments applied by XCLIENT or proxy protocol|{{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`received_from`|indicates the IP:port of the sending or peer machine in this session|{{since('2023.08.22-4d895015', inline=True)}}|
|Connection|`orig_received_from`|Set when XCLIENT or other similar proxying is active; it indicates the raw IP:port of the sending or peer machine in this session, independent of any adjustments applied by XCLIENT or proxy protocol|{{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`hostname`|A copy of the effective value of the hostname set by [kumo.start_esmtp_listener](kumo/start_esmtp_listener/hostname.md) or [kumo.start_http_listener](kumo/start_http_listener/hostname.md)|{{since('2023.11.28-b5252a41', inline=True)}}.<br> For HTTP injections {{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`authn_id`|the authentication id if the message was received via authenticated SMTP||
|Connection|`authz_id`|the authorization id if the message was received via authenticated SMTP||
|Connection|`ehlo_domain`|the domain name that was passed in from the sender via the SMTP EHLO or HELO|{{since('2024.11.08-d383b033', inline=True)}}|
|Connection|`tls_cipher`|If STARTTLS was used, holds the negotiated TLS cipher name|{{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`tls_protocol_version`|If STARTTLS was used, holds the negotiated TLS protocol version|{{since('2025.10.06-5ec871ab', inline=True)}}|
|Connection|`tls_peer_subject_name`|If STARTTLS was used, and the peer provided a client certificate, and the certificate matches up to the configured `tls_required_client_ca`, holds the subject name field of the verified peer certificate|{{since('2025.10.06-5ec871ab', inline=True)}}|
|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)}}|
|Message|`extra`|Per-recipient metadata supplied via the HTTP injection API's recipient-level `metadata` field. The value is the supplied object; accessible from Lua hooks via `msg:get_meta('extra')`.|{{since('2026.05.12-a6845223', inline=True)}}|
