uses the Lua programming language as a configuration and extension language, therefore the configuration file is a Lua script.

Although knowledge of Lua is not required to use imapfilter(1) , it is nonetheless recommended, especially if one wants to extend imapfilter(1) . The user is advised to have a look at the available Lua documentation at:

A brief description of the Lua values and types mentioned hereafter in the manual page follows:

•

The nil is the type of the value whose main property is to be different from any other value; usually it represents the absence of a useful value.

•

The boolean is the type of the values and Both and make a condition false; any other value makes it true.

•

The type number represents real numbers.

•

The type string represents a sequence of characters and can be defined using single quotes, double quotes or double square brackets.

•

The type table implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value.

•

A function is a first-class value; it can be stored in variables, passed as argument to other functions, and returned as a result.

Program's options are set using an already initialised table named in the following manner: options.timeout = 120 options.namespace = false options.charset = 'ISO-8859-1'

Available options are:

create

According to the IMAP specification, when trying to write a message to a non-existent mailbox, the server must send a hint to the client, whether it should create the mailbox and try again or not. However some broken IMAP servers don't follow the specification and don't send the correct response code to the client. By enabling this option the client tries to create the mailbox, despite of the server's response. This variable takes a boolean as a value. Default is

charset

Indicates to the server the character set of the strings that appear in the search criteria. Character sets are defined in RFC 2978 and must be supported by the server. This variable takes a string as a value.

close

This option controls whether the currently selected mailbox is implicitly closed, at the end of each performed operation, removing all messages that are marked deleted. This variable takes a boolean as a value. Default is

crammd5

When this option is enabled and the server supports the Challenge-Response Authentication Mechanism (specifically CRAM-MD5), this method will be used for user authentication instead of a plaintext password LOGIN. This variable takes a boolean as a value. Default is

expunge

Normally, messages are marked for deletion and are actually deleted when the mailbox is closed. When this option is enabled, messages are expunged immediately after being marked deleted. This variable takes a boolean as a value. Default is

info

When this options is enabled, a summary of the program's actions is printed, while processing mailboxes. This variable takes a boolean as a value. Default is

namespace

When enabled, the program gets the namespace of the user's personal mailboxes, and applies automatically the prefix and hierarchy delimiter to any mailboxes residing on the mail server; the user must use the `/' character as the delimiter and ``'' (ie. nothing) as the prefix, regardless of the folder format of the mail server. This must be disabled, if the user wants to manually specify mailbox names (eg. because they are not part of the user's personal namespace mailboxes), in which case he/she should apply the prefix and hierarchy delimiter that is used by the mail server. This variable takes boolean as a value. Default is

starttls

When this option is enabled and the server supports the IMAP STARTTLS extension, a TLS connection will be negotiated with the mail server in the beginning of the session. This variable takes a boolean as value. Default is

subscribe

By enabling this option newly created mailboxes get also subscribed; they are set active in order for IMAP clients to recognize them. This variable takes a boolean as a value. Default is

timeout

The time in seconds for the program to wait for a mail server's response. If not set, the client will block indefinitely. This variable takes a number as a value.

uid

If this option is enabled, unique message identifiers are used instead of message sequence numbers, when accessing messages in a mailbox. This variable takes a boolean as a value. Default is

Accounts are tables of the form: myaccount = { server = 'imap.mail.server', username = 'me', password = 'secret', }

An account table must have the following elements:

server

The hostname of the IMAP server to connect to. It takes a string as a value.

username

User's name. It takes a string as a value.

password

User's secret keyword. It takes a string as a value.

An account table can also have the following optional elements:

port

The port to connect to. It takes a number as a value. Default is for imap and for imaps.

ssl

Forces an imaps connection and specifies the SSL/TLS protocol to be used. It takes a string as a value, specifically one of:

Filters are tables of the form: myfilter = { 'unseen', 'subject "hello world"', 'smaller 50000', }

Filter rules are either strings or tables containing strings .

In the first case, such as the aforementioned example, all rules are logically AND'ed. This means the above filter is interpreted by the mail server as:

In the case of rules being tables , the rules inside the tables are logically OR'ed. For example:

myfilter = { 'unseen', { 'subject "hello"', 'subject "world"' }, 'smaller 50000', }

In this case the filter is interpreted as:

Note, that these rules of type table , cannot contain anything else than strings .

A filter table can also have the option element which, when enabled, inverts the filter's AND/OR logic; filter rules are logically OR'ed and the rules of tables are logically AND'ed. This variable takes a boolean as a value. Default is For example: myfilter = { invert = true, 'seen', { 'subject "hello"', 'subject "world"' }, 'larger 50000', }

The "inverted" filter is interpreted as:

The keyword may be used as negation operator, when it is inserted in the beginning of the filter rule string . For example:

myfilter = { 'not seen', 'subject "hello world"', 'not larger 50000', }

This filter is essentially the same as the first example filter.

Searching criteria are described in the IMAP4rev1 specification, RFC 3501 Section 6.4.4, but are also presented here for completeness.

Searching criteria based on a message's status:

answered

Messages that have been answered.

deleted

Messaget that are marked "deleted" for later removal.

draft

Messages that have not completed composition.

flagged

Messages that are "flagged" for urgent/special attention.

new

Messages that are "recently" arrived in this mailbox, this session is the first session to have been notified about these messages, and have not been read.

old

Messages that are not "recently" arrived in this mailbox, this session is the first session to have been notified about these messages, and have not been read.

recent

Messages that are "recently" arrived in this mailbox, this session is the first session to have been notified about these messages.

seen

Messages that have been read.

unanswered

Messages that have not been answered.

undeleted

Messages that are not marked "deleted" for later removal.

undraft

Messages that have completed composition.

unflagged

Messages that are not "flagged" for urgent/special attention.

unseen

Messages that have not been read.

Searching criteria based on a message's text, where the and refer to a sequence of characters enclosed in double quotes:

bcc Aq string

Messages that contain the specified string in the envelope structure's field.

body Aq string

Messages that contain the specified string in the body of the message.

cc Aq string

Messages that contain the specified string in the envelope structure's field.

from Aq string

Messages that contain the specified string in the envelope structure's field.

header Ao field-name Ac Ao string Ac

Messages that have a header with the specified field-name and contains the specified string in the text of the header (what comes after the colon). If the string to search for is zero-length, this matches all messages that have a header line with the specified field-name regardless of the contents.

subject Aq string

Messages that contain the specified string in the envelope structure's field.

text Aq string

Messages that contain the specified string in the header or body of the message.

to Aq string

Messages that contain the specified string in the envelope structure's field.

Searching criteria based on a message's size, where the refers to an integer number:

larger Aq number

Messages with a size larger than the specified number of octets (bytes).

smaller Aq number

Messages with a size smaller than the specified number of octets (bytes).

Searching criteria based on a message's date, where the refers to a date of the strftime() form where is the day of the month as a decimal number (01-31), is the national representation of the abbreviated month is the year with century as a decimal number:

before Aq date

Messages whose internal date (disregarding time and timezone) is earlier than the specified date.

on Aq date

Messages whose internal date (disregarding time and timezone) is within the specified date.

sentbefore Aq date

Messages whose header (disregarding time and timezone) is earlier than the specified date.

senton Aq date

Messages whose header (disregarding time and timezone) is within the specified date.

sentsince Aq date

Messages whose header (disregarding time and timezone) is within or later than the specified date.

since Aq date

Messages whose internal date (disregarding time and timezone) is within or later than the specified date.

check account mailbox

The check function gets the status of the mailbox at the IMAP account The check function returns three values of number type: the total number of messages, the number of recent messages and the number of unseen messages in the mailbox. Example:

match account mailbox filter

The match function sends a search query to the server denoted by the account The search query is applied to the mailbox and is extracted from the filter The match function returns a table , containing numbers , the messages that matched the search query. Example:

delete account mailbox messages

The delete function deletes the messages contained in the messages from the mailbox at the account table . Examples: results = match(myaccount, 'INBOX', myfilter) delete(myaccount, 'INBOX', results)

copy srcaccount srcmailbox dstaccount dstmailbox messages

The copy function copies the messages contained in the messages from the srcmailbox at the srcaccount to the dstmailbox at the dstaccount If the srcaccount and dstaccount are different accounts, then the messages are downloaded from the srcmailbox at srcaccount and then uploaded to the dstmailbox at dstaccount . Examples: results = match(myaccount, 'INBOX', myfilter) copy(myaccount, 'INBOX', myaccount, 'mymailbox', results)

results = match(myaccount1, 'INBOX', myfilter) copy(myaccount1, 'INBOX', myaccount2, 'mymailbox', results) move srcaccount srcmailbox dstaccount dstmailbox messages The move function moves the messages contained in the messages from the srcmailbox at the srcaccount to the dstmailbox at the dstaccount If the srcaccount and dstaccount are different accounts, then the messages are downloaded from the srcmailbox at srcaccount and then uploaded to the dstmailbox at dstaccount . Examples: results = match(myaccount, 'INBOX', myfilter) move(myaccount, 'INBOX', myaccount, 'mymailbox', results)

results = match(myaccount1, 'INBOX', myfilter) move(myaccount1, 'INBOX', myaccount2, 'mymailbox', results) flag account mailbox mode flags messages The flag function manipulates the flags of the messages residing in the mailbox at the account The mode is a string and can be one of: The flags is a table containing strings , that can be one of: Examples: results = match(myaccount, 'INBOX', myfilter) flag(myaccount, 'INBOX', 'add', { 'seen' }, results) fetchheader account mailbox messages The fetchheader function fetches the header of the messages residing in the mailbox at the account The fetchheader function returns a table , containing strings , the header of the messages. Examples: header = fetchheader(myaccount, 'INBOX', { 1, 2, 4 }) print(header[1], header[2], header[4])

results = match(myaccount, 'INBOX', myfilter) header = fetchheader(myaccount, 'INBOX', results) fetchbody account mailbox messages The fetchbody function fetches the body of the messages residing in the mailbox at the account The fetchbody function returns a table containing strings , the body of the messages. Examples: body = fetchbody(myaccount, 'INBOX', { 1, 2, 4 }) print(body[1], body[2], body[4])

results = match(myaccount, 'INBOX', myfilter) body = fetchbody(myaccount, 'INBOX', results) fetchtext account mailbox messages The fetchtext function fetches the text (header and body) of the messages residing in the mailbox at the account The fetchtext function returns a table containing strings , the text of messages. Examples: text = fetchtext(myaccount, 'INBOX', { 1, 2, 4 }) print(text[1], text[2], text[4])

results = match(myaccount, 'INBOX', myfilter) text = fetchtext(myaccount, 'INBOX', results) fetchfields account mailbox headerfields messages The fetchfields function fetches the headerfields of the messages residing in the mailbox at the account The fetchfields function returns a table containing strings , the specified header lines of messages. Examples: fields = fetchfields(myaccount, 'INBOX', { 'from', 'to' }, { 1, 2, 4 }) print(fields[1], fields[2], fields[4])

results = match(myaccount, 'INBOX', myfilter) fields = fetchfields(myaccount, 'INBOX', { 'from', 'to' }, results) fetchfast account mailbox messages The fetchfast function fetches the flags, date and size of the messages residing in the mailbox at the account The fetchfast function returns a table containing other tables each containing the flags the date and the size of the messages. Examples: fast = fetchfast(myaccount, 'INBOX', { 1, 2, 4 }) print(unpack(fast[1]['flags']), fast[1]['date'], fast[1]['size']) print(unpack(fast[2]['flags']), fast[2]['date'], fast[2]['size']) print(unpack(fast[4]['flags']), fast[4]['date'], fast[4]['size'])

results = match(myaccount, 'INBOX', myfilter) fast = fetchfast(myaccount, 'INBOX', results) list account folder The list function lists the mailboxes available to the client in the folder at the account The list function returns a table containing strings , the available mailboxes, and a table containing strings , the available folders. Examples: mailboxes, folders = list(myaccount, '') print(unpack(mailboxes)) print(unpack(folders))

mailboxes, folders = list(myaccount, 'myfolder') lsub account folder The lsub function lists the subscribed mailboxes available to the client in the folder at the account The lsub function returns a table containing strings , the available mailboxes, and a table containing strings , the available folders. Examples: mailboxes, folders = lsub(myaccount, '') print(unpack(mailboxes)) print(unpack(folders))

mailboxes, folders = lsub(myaccount, 'myfolder')

Some auxiliary functions are also available for conveniency:

date_before days

The date_before function returns a string, the date in a strftime(3) ``%d-%b-%Y' form, that the system had before the specified number of days

get_pass prompt

The get_pass function displays the specified prompt and reads a password, while character echoing is turned off. The get_pass function returns the password as a string .

daemon_mode interval commands

The daemon_mode function can be used to detach imapfilter() from the controlling terminal and run it in the background as system daemon. The program will then repeatedly poll at the specified interval in seconds. Each time the program wakes up, the commands are executed.

pipe_to command data

The pipe_to function executes the system's command and sends the data to the standard input channel of the subprocess. The pipe_to function returns a number , the exit status of the child process.

pipe_from command

The pipe_from function executes the system's command and retrieves the data from the standard output channel of the subprocess. The pipe_from function returns two values: a number , the exit status of the child process, and a string , the output of the child process.

See sample.config.lua and sample.extend.lua .

HOME

User's home directory.