Skip to content

Connection Metadata Object

Since: Version 2023.08.22-4d895015

The functionality described in this section requires version 2023.08.22-4d895015 of KumoMTA, or a more recent version.

This object represents a collection of metadata keys and values that are associated with an established incoming SMTP connection.

KumoMTA populates a small number of predefined fields (see below), and allows your policy scripts the ability to read those values as well as write (and read!) additional values as needed by the local policy. For instance, you may decide to compute a value after EHLO has been processed by smtp_server_ehlo and access that value in a later SMTP event handler.

Prior to calling smtp_server_message_received, KumoMTA will copy the values from the connection metadata and use those to populate the message metadata.

The get_meta and set_meta methods shown below are used to read and write metadata values.

Predefined Connection Metadata Values

The following values are predefined by KumoMTA:

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


Additional metadata is available at the Message scope, for a full list of all available metadata, see the Predefined Metadata page.

Available Methods


Returns the value associated with name, or nil if no such value has been defined. Values may be predefined by KumoMTA or may be set by policy scripts using conn_meta:set_meta().

conn_meta:set_meta(name, value)

Sets the value associated with name to value. Value must be serializable as JSON; it can be simple strings or numbers, but may also be an array or object value.