Provided by: imapfilter_1.1.1-1_i386 bug

NAME

     imapfilter_config - imapfilter configuration file

SYNOPSIS

     $HOME/.imapfilter/config.lua

DESCRIPTION

     imapfilter(1) uses the Lua programming language (http://www.lua.org) 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:

           http://www.lua.org/docs.html

CONVENTIONS

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

           The nil is the type of the value “nil”, 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 “true” and “false”.  Both
           “nil” and “false” 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.

OPTIONS

     Program’s options are set using an already initialised table named
     “options”, 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 “false”.

     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
                   “true”.

     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 “true”.

     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 “false”.

     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 “true”.

     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 “true”.

     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 “true”.

     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 “false”.

     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 “true”.

ACCOUNTS

     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 “143” for imap and “993” 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: “ssl2”, “ssl3”, “tls1”.

FILTERS

     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:

           (unseen) AND (subject "hello world") AND (smaller 50000)

     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:

           (unseen) AND ((subject "hello") OR (subject "world")) AND (smaller
           50000)

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

     A filter table can also have the “invert” 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 “false”.  For example:

           myfilter = {
                   invert = true,
                   ’seen’,
                   { ’subject "hello"’, ’subject "world"’ },
                   ’larger 50000’,
           }

     The "inverted" filter is interpreted as:

           (unseen) OR ((subject "hello") AND (subject "world")) OR (smaller
           50000)

     The “not” 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 〈string〉 and
     〈field-name〉 refer to a sequence of characters enclosed in double quotes:

           bcc 〈string〉
                   Messages that contain the specified string in the envelope
                   structure’s “Bcc” field.

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

           cc 〈string〉
                   Messages that contain the specified string in the envelope
                   structure’s “Cc” field.

           from 〈string〉
                   Messages that contain the specified string in the envelope
                   structure’s “From” field.

           header 〈field-name〉 〈string〉
                   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 〈string〉
                   Messages that contain the specified string in the envelope
                   structure’s “Subject” field.

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

           to 〈string〉
                   Messages that contain the specified string in the envelope
                   structure’s “To” field.

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

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

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

     Searching criteria based on a message’s date, where the 〈date〉 refers to
     a date of the strftime(3) form “%d-%b-%Y”, where “%d” is the day of the
     month as a decimal number (01-31), “%b” is the national representation of
     the abbreviated month (“Jan”, “Feb”, “Mar”, “Apr”, “May”, “Jun”, “Jul”,
     “Aug”, “Sep”, “Oct”, “Nov”, “Dec”), “%Y” is the year with century as a
     decimal number:

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

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

           sentbefore 〈date〉
                   Messages whose “Date” header (disregarding time and
                   timezone) is earlier than the specified date.

           senton 〈date〉
                   Messages whose “Date” header (disregarding time and
                   timezone) is within the specified date.

           sentsince 〈date〉
                   Messages whose “Date” header (disregarding time and
                   timezone) is within or later than the specified date.

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

COMMANDS

     check(account, mailbox)
             The check() function gets the status of the mailbox (string) at
             the IMAP account (table).  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:

                   exist, unread, unseen = check(myaccount, ’INBOX’)

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

                   results = match(myaccount, ’INBOX’, myfilter)

     delete(account, mailbox, messages)
             The delete() function deletes the messages contained in the
             messages (table), from the mailbox (string) 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
             (table), from the srcmailbox (string) at the srcaccount (table),
             to the dstmailbox (string) at the dstaccount (table).  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
             (table), from the srcmailbox (string) at the srcaccount (table),
             to the dstmailbox (string) at the dstaccount (table).  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 (table)
             residing in the mailbox (string) at the account (table).  The
             mode is a string and can be one of: “add”, “remove”, “replace”.
             The flags is a table containing strings, that can be one of:
             “answered”, “deleted”, “draft”, “flagged”, “seen”.  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
             (table) residing in the mailbox (string) at the account (table).
             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 (table)
             residing in the mailbox (string) at the account (table).  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 (table) residing in the mailbox (string) at the
             account (table).  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 (table) of
             the messages (table) residing in the mailbox (string) at the
             account (table).  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 (table) residing in the mailbox (string) at the account
             (table).  The fetchfast() function returns a table containing
             other tables each containing the flags (table), the date
             (string), and the size (number) 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 (string) at the account (table).  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 (string) at the account (table).  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’)

FUNCTIONS

     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 (number).

     get_pass(prompt)
             The get_pass() function displays the specified prompt (string)
             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(1)
             from the controlling terminal and run it in the background as
             system daemon.  The program will then repeatedly poll at the
             specified interval (number) in seconds.  Each time the program
             wakes up, the commands (function) are executed.

     pipe_to(command, data)
             The pipe_to() function executes the system’s command (string) and
             sends the data (string) 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 (string)
             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.

EXAMPLES

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

ENVIRONMENT

     HOME             User’s home directory.

SEE ALSO

     imapfilter(1)

AUTHORS

     Lefteris Chatzibarbas 〈lefcha@hellug.gr