Provided by:
imapfilter_1.1.1-1_i386 
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〉