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 is used for data that is shared in common with all messages injected over a given connection, and the message metadata 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:
| Scope | Name | Purpose | Since |
|---|---|---|---|
| Connection | reception_protocol |
indicates the reception protocol, such as ESMTP |
(Since: Version 2023.08.22-4d895015) |
| Connection | received_via |
indicates the IP:port of the KumoMTA listener that is handling this session | (Since: Version 2023.08.22-4d895015) |
| Connection | received_from |
indicates the IP:port of the sending or peer machine in this session | (Since: Version 2023.08.22-4d895015) |
| Connection | hostname |
A copy of the effective value of the hostname set by kumo.start_esmtp_listener | (Since: Version 2023.11.28-b5252a41) |
| 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: Version 2024.11.08-d383b033) |
| 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: Version 2023.08.22-4d895015) |