Local lists

A local lookup list is defined entry by entry in the server’s configuration, and held in memory. It suits lists that the administrator maintains and that change occasionally, such as a set of trusted domains or a mapping from domains to values. Lists maintained elsewhere and published as a file are better served by remote lists.

Each entry is a separate object, and the entries that share a namespace form one list.

The lists in memory are built from these objects, so added, changed and removed entries take effect only when the lists are rebuilt. That happens when the ReloadLookupStores action runs, or when the server restarts. In a cluster, the action reaches the other nodes through the coordinator. When the rebuild fails, the previous lists are kept, and the action reports the error.

Key lists

A key list answers one question, through key_exists: whether a key is a member of the list. Each entry is a MemoryLookupKey object with a namespace and a key of up to 255 characters.

The spam filter’s lists of blocked domains, spam traps, trusted domains and URL redirectors are key lists. That is why the WebUI shows the entries in two places, under the lookup settings and in the spam filter settings: Settings › Lookups › In-Memory Keys, Settings › Spam Filter › Lists › Blocked Domains, Settings › Spam Filter › Lists › Spam Traps, Settings › Spam Filter › Lists › Trusted Domains, Settings › Spam Filter › Lists › URL Redirectors.

The following entries create a list trusted-partners with two domains:

{"namespace": "trusted-partners", "key": "example.org"}
{"namespace": "trusted-partners", "key": "example.net"}

With these entries, the expression key_exists('trusted-partners', sender_domain) is true for mail from either domain.

Key-value lists

A key-value list associates a value with each key, and key_get returns the value for a key. It turns a key into a setting, for example a domain into the host that handles it. Each entry is a MemoryLookupKeyValue object with a namespace, a key and a value. The entries are found in the WebUI under Settings › Lookups › In-Memory Key-Values.

The following entries map two domains to the relay host that handles them:

{"namespace": "relay-host", "key": "example.org", "value": "mx1.example.com"}
{"namespace": "relay-host", "key": "example.net", "value": "mx2.example.com"}

With these entries, key_get('relay-host', rcpt_domain) returns the host for the recipient’s domain, or an empty value for other domains.

A namespace holds either keys or key-value pairs, but never both. When entries of both kinds share a namespace, the key-value entries are loaded and the key-only entries are ignored. The server then logs the warning Memory lookup has mixed types (key-value and set).

Glob patterns

Listing every subdomain of a domain one by one would be impractical. A single entry can instead match many keys, when its key is a glob pattern. With isGlobPattern set to true, * in the key matches any sequence of characters, and ? matches a single character. For example, the key *.example.com matches every subdomain of example.com, and mx?.example.org matches mx1.example.org and mx2.example.org.

Patterns can be mixed with literal keys in the same list. A literal key is still matched exactly.