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
it is nonetheless recommended, especially if one wants to extend
The user is advised to have a look at the available Lua documentation at:
CONVENTIONS
A brief description of the Lua values and types mentioned hereafter in the
manual page follows:
The
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
is the type of the values
and
Both
and
make a condition false; any other value makes it true.
The type
represents real numbers.
The type
represents a sequence of characters and can be defined using single quotes,
double quotes or double square brackets.
The type
implements associative arrays, that is, arrays that can be indexed not only
with numbers, but with any value.
A
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
named
in the following manner:
options.timeout = 120
options.namespace = false
options.charset = 'ISO-8859-1'
Available options are:
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
as a value. Default is
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
as a value.
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
as a value. Default is
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
as a value. Default is
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
as a value. Default is
When this options is enabled, a summary of the program's actions is printed,
while processing mailboxes. This variable takes a
as a value. Default is
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
as a value. Default is
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
as value. Default is
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
as a value. Default is
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
as a value.
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
as a value. Default is
ACCOUNTS
Accounts are
of the form:
myaccount = {
server = 'imap.mail.server',
username = 'me',
password = 'secret',
}
An account
must have the following elements:
The hostname of the IMAP server to connect to. It takes a
as a value.
User's name. It takes a
as a value.
User's secret keyword. It takes a
as a value.
An account
can also have the following optional elements:
The port to connect to. It takes a
as a value. Default is
for imap and
for imaps.
Forces an imaps connection and specifies the SSL/TLS protocol to be used. It
takes a
as a value, specifically one of:
FILTERS
Filters are
of the form:
myfilter = {
'unseen',
'subject "hello world"',
'smaller 50000',
}
Filter rules are either
or
containing
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
the rules inside the
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
cannot contain anything else than
A filter
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
are logically AND'ed. This variable takes a
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
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:
Messages that have been answered.
Messaget that are marked "deleted" for later removal.
Messages that have not completed composition.
Messages that are "flagged" for urgent/special attention.
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.
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.
Messages that are "recently" arrived in this mailbox, this session is the first
session to have been notified about these messages.
Messages that have been read.
Messages that have not been answered.
Messages that are not marked "deleted" for later removal.
Messages that have completed composition.
Messages that are not "flagged" for urgent/special attention.
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:
Messages that contain the specified string in the envelope structure's
field.
Messages that contain the specified string in the body of the message.
Messages that contain the specified string in the envelope structure's
field.
Messages that contain the specified string in the envelope structure's
field.
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.
Messages that contain the specified string in the envelope structure's
field.
Messages that contain the specified string in the header or body of the
message.
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:
Messages with a size larger than the specified number of octets (bytes).
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
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:
Messages whose internal date (disregarding time and timezone) is earlier than
the specified date.
Messages whose internal date (disregarding time and timezone) is within the
specified date.
Messages whose
header (disregarding time and timezone) is earlier than the specified date.
Messages whose
header (disregarding time and timezone) is within the specified date.
Messages whose
header (disregarding time and timezone) is within or later than the specified
date.
Messages whose internal date (disregarding time and timezone) is within or
later than the specified date.
COMMANDS
The
function gets the status of the
at the IMAP
The
function returns three values of
type: the total number of messages, the number of recent messages and the
number of unseen messages in the mailbox. Example:
The
function sends a search query to the server denoted by the
The search query is applied to the
and is extracted from the
The
function returns a
containing
the messages that matched the search query. Example:
The
function deletes the messages contained in the
from the
at the
Examples:
results = match(myaccount, 'INBOX', myfilter)
delete(myaccount, 'INBOX', results)
The
function copies the messages contained in the
from the
at the
to the
at the
If the
and
are different accounts, then the
are downloaded from the
at
and then uploaded to
the
at
Examples:
results = match(myaccount, 'INBOX', myfilter)
copy(myaccount, 'INBOX', myaccount, 'mymailbox', results)
results = match(myaccount1, 'INBOX', myfilter)
copy(myaccount1, 'INBOX', myaccount2, 'mymailbox', results)
The
function moves the messages contained in the
from the
at the
to the
at the
If the
and
are different accounts, then the
are downloaded from the
at
and then uploaded to
the
at
Examples:
results = match(myaccount, 'INBOX', myfilter)
move(myaccount, 'INBOX', myaccount, 'mymailbox', results)
results = match(myaccount1, 'INBOX', myfilter)
move(myaccount1, 'INBOX', myaccount2, 'mymailbox', results)
The
function manipulates the flags of the
residing in the
at the
The
is a
and can be one of:
The
is a
containing
that can be one of:
Examples:
results = match(myaccount, 'INBOX', myfilter)
flag(myaccount, 'INBOX', 'add', { 'seen' }, results)
The
function fetches the header of the
residing in the
at the
The
function returns a
containing
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)
The
function fetches the body of the
residing in the
at the
The
function returns a
containing
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)
The
function fetches the text (header and body) of the
residing in the
at the
The
function returns a
containing
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)
The
function fetches the
of the
residing in the
at the
The
function returns a
containing
the specified header lines of messages. Examples:
headers = fetchheaders(myaccount, 'INBOX', { 'from', 'to' }, { 1, 2, 4 })
print(headers[1], headers[2], headers[4])
results = match(myaccount, 'INBOX', myfilter)
headers = fetchheaders(myaccount, 'INBOX', { 'from', 'to' }, results)
The
function fetches the flags, date and size of the
residing in the
at the
The
function returns a
containing other
each containing the
the
and the
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)
FUNCTIONS
Some auxiliary functions are also available for conveniency:
The
function returns a
the date in a strftime(3) ``%d-%b-%Y' form,
that the system had before the specified number of
The
function displays the specified
and reads a password, while character echoing is turned off. The
function returns the password as a
The
function can be used to detach
from the controlling terminal and run it in the background as system daemon.
The program will then repeatedly poll at the specified
in seconds. Each time the program wakes up, the
are executed.
The
function executes the system's
and sends the
to the standard input channel of the subprocess. The
function returns a
the exit status of the child process.
The
function executes the system's
and retrieves the data from the standard output channel of the subprocess. The
function returns two values: a
the exit status of the child process, and a
the output of the child process.
