imapfilter Documentation

IMAPFilter is a mail filtering utility that connects to remote mail servers via the IMAP protocol (supporting versions 4 and 4rev1). It works by sending search queries to the server and processing mailboxes based on the results.

Common tasks you can perform include:

• Deleting messages
• Copying messages
• Moving messages
• Flagging messages

It is capable of managing messages residing in mailboxes on the same or different mail servers. Configuration and extensions are handled using the Lua programming language.

Once an account is initialized, mailboxes can be accessed as elements of the account table.

• Direct access: myaccount.mymailbox (only if name contains letters, digits, or underscores and doesn't start with a digit).
• Alternative access: myaccount['mymailbox'] (required if name contains special characters or starts with a digit).
• Folder access: myaccount['myfolder/mymailbox'] (required for mailboxes inside folders).

Note: Account methods (like list_all) and strings starting with an underscore are reserved and cannot be used as mailbox names.

Searching methods return a special table containing matching messages. These tables can be combined using logical operators:

• Logical OR (+): results = search1 + search2
• Logical AND (*): results = search1 * search2 (Higher precedence than + and -)
• Logical NOT (-): results = search1 - search2

Example:

-- Unseen messages that are larger than 100,000 bytes
results = myaccount.mymailbox:is_unseen() * myaccount.mymailbox:is_larger(100000)

-- Complex filter with parentheses
results = (myaccount.mymailbox:is_unseen() + myaccount.mymailbox:is_larger(100000)) * myaccount.mymailbox:contain_subject('test')

myfilter = function (mailbox, size, subject)
    return mailbox:is_unseen() + mailbox:is_larger(size) * mailbox:contain_subject(subject)
end

results = myfilter(myaccount.mymailbox, 100000, 'test')

To validate SSL connections, use the -t <truststore> flag to specify the path to your system's SSL CA TrustStore directory or file.

If no truststore is specified via the flag, imapfilter follows this fallback order:

1. The file $HOME/.imapfilter/certificates.
2. The default CA directory /etc/ssl/certs/.
3. The default CA file /etc/ssl/cert.pem.

imapfilter -t /path/to/custom/ca-bundle.crt

You can provide configuration to imapfilter using several methods:

1. Configuration File: Use the -c <configfile> flag to specify a path to a Lua configuration file. If omitted, it defaults to $HOME/.imapfilter/config.lua.
2. Standard Input: Use -c - to read the configuration from stdin.
3. Inline Command: Use -e '<command>' to provide a single line of configuration. When using this option, no configuration file is loaded.
4. Piped String: You can pipe a full configuration string into the command via stdin using the -c - flag.

imapfilter -c /path/to/config.lua
# Or using stdin
cat my_config.lua | imapfilter -c -
# Or using an inline command
imapfilter -e "print('hello')"

When troubleshooting connection or filtering issues, use the following flags:

• -d <debugfile>: Writes detailed debugging information about the full communication with the server and other internal workings to the specified file.
• -l <logfile>: Writes error messages to the specified log file.
• -v: Enables printing brief details of the communication with the server to the console.

imapfilter -d debug.log -l errors.log -v

The imapfilter configuration is a Lua script located at $HOME/.imapfilter/config.lua. While Lua knowledge is not strictly required for basic use, it is recommended for extending the tool.

Global program options are configured using a pre-initialized options table.

options.timeout = 120
options.namespace = false
options.charset = 'ISO-8859-1'

To install IMAPFilter, you must first ensure your system meets the compile-time requirements for Lua, PCRE2, and OpenSSL. Once requirements are met, use make to compile and make install to install the utility.

Compile-time requirements:

• Lua: version 5.1, 5.2, 5.3, 5.4, or 5.5
• PCRE2: version 10.00 or later
• OpenSSL: version 1.0.2 or later

make -j all
make install

To test your configuration without making any actual changes to the mail server (such as deleting, moving, or flagging messages), use the -n flag.

In dry-run mode, imapfilter will print informational messages about the actions it would have taken, but it will not send any modifying requests to the server. Searching and data retrieval operations will still proceed normally.

Note: The number of messages reported to be affected might differ between dry-run and normal execution because, in normal execution, subsequent actions are performed on a server state that is being continuously altered.

imapfilter -n

Use these methods to monitor mailbox changes:

• check_status(): Returns four numbers: total_messages, recent_messages, unseen_messages, and next_uid.
• enter_idle(): Implements the IMAP IDLE extension. It blocks execution until an update is received.
  • Returns true and an optional event string if an update occurred.
  • Returns false if the IDLE extension is not supported.
  • Can be interrupted by SIGUSR1 or SIGUSR2 signals.

Example:

exist, unread, unseen, uidnext = myaccount.mymailbox:check_status()
update, event = myaccount.mymailbox:enter_idle()