IMAPFILTERRC(5)

NAME
imapfilterrc - imapfilter configuration file

SYNOPSIS
$HOME/.imapfilterrc

DESCRIPTION
The imapfilterrc configuration file consists of a series of commands and variable settings, with each one in a separate line.

Empty lines and lines beginning with the number sign ‘#’ character, which are considered comments, are ignored.

COMMANDS

account alias username[:password]@hostname[:port] [ssl|ssl2|ssl3|tls1]
    Defines a user account under the name alias, using the username as user identification and password as the secret word, connecting to the hostname mail server, at the specified port (if not specified the default IMAP protocol port (ie. 143 or 993 when SSL/TLS is enabled) is used). SSL/TLS support is enabled with the argument ssl, which uses as default the SSL protocol version 2, though this may be changed by specifying a different protocol/version.

    The alias is comprised by alphanumeric, underscore ‘_’ and minus ‘-’ characters.

    The username and password strings can be given in a URL encoding like scheme, that is the ‘%’ character followed by two hexadecimal digits representing the encoded character's ascii(7) code. Within the username and password field, any ‘’:, ‘@’, ‘%’ or ‘ ’ characters must be encoded in the above way.

    The password field may be omitted, in which case the user is prompted for one interactively, when imapfilter(1) is run. Also, a password must not be supplied, if the user intends to specify one using the interactive encrypted passwords' editor of imapfilter(1), in order to store the password securely in the filesystem.

folder alias folder[,...]
    Defines folders (mailboxes) and groups them under the alias name. The mailboxes are associated with the last preceding account setting. More than one folder can be declared, separating them with a comma ‘’, character. The alias is comprised by alphanumeric, underscore ‘_’ and minus ‘-’ characters.

filter alias [or|and]
    Starts the declaration of a filter with the name alias. Optionally the and or or flag can be set, in order to set the mode in which the filter's masks will be combined (default is and mode). The alias is comprised by alphanumeric, underscore ‘_’ and minus ‘-’ characters.

[mask] [or|and] [not] searchkey
    A filter entry contains one or more mask entries which are defined with the optional mask command, the or or and flag, the not flag and the searching criteria, based on which matching of a filter is done.

    The or and and flags are used to define in which way the current mask is combined with it's previous mask. The not flag is used to revert the functionality of the specified searchkey.

    A string can be a word, or a phrase enclosed in ‘"’. The matching of the string is case-insensitive.

    The available searching criteria are:

    answered
        Messages that have been answered.

    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.

    deleted
        Messages that are marked for deletion.

    draft
        Messages that have not completed composition.

    flagged
        Messages marked for urgent/special attention.

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

    header fieldname string
        Messages that have a header with the specified fieldname, and contain the specified string in the field body.

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

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

    newer number
        Messages whose internal date is newer than the specified number of days.

    old Messages that have not "recently" arrived in the mailbox and have not been read.

    older number
        Messages whose internal date is older than the specified number of days.

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

    seen
        Messages that have been read.

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

    subject string
        Messages that contain the specified string in the envelope structure's “Subject” field.

    unanswered
        Messages that have not been answered.

    undeleted
        Messages that are not marked for deletion.

    undraft
        Messages that have completed composition.

    unflagged
        Messages that are not marked for urgent/special attention.

    unseen
        Messages that have not been read.

action type
    The action command is used to end the filter entry started with the filter command. It assigns an action to be done when the filter is matched.

    The available type of actions are:

    copy mailbox [header,...]
        Copies the messages to the specified mailbox. If the mailbox does not exist, then it is created. Optionally, fetches and displays the header of the messages that were copied.

    delete [header,...]
        Deletes the messages. User can also, optionally, define the header of the deleted messages to be displayed. More than one header can be declared and fetched, by separating them with a comma ‘’, character.

    flag mode flag[,...] [header,...]
        Sets the flags of the messages. The mode can be replace, add, or remove. The flag can be none, seen, answered, flagged, deleted, or draft. Optionally, the header of the messages is displayed.

    list [header,...]
        Just displays the header of the messages.

    move mailbox [header,...]
        Moves the messages to the specified mailbox. If the mailbox does not exist, then it is created. Optionally, fetches and displays the header of the messages that were moved.

    rcopy account mailbox [header,...]
        Copies the messages to the specified mailbox residing on a specific account. Optionally, displays the header of the messages. Unlike all other type of actions, this requires that the message is downloaded from the source mail server and then uploaded to the target mail server.

    rmove account mailbox [header,...]
        Moves the messages to the specified mailbox residing on a specific account. Optionally, displays the header of the messages. Unlike all other type of actions, this requires that the message is downloaded from the source mail server and then uploaded to the target mail server.

job filter[,...] folder[,...]
    This command is used to define which filter must be applied to which folder. More than one filter and/or folder can be declared, by separating them with a comma ‘’, character.

[set] variable=value
    Manipulate and set the configuration variables.

VARIABLES

daemon
    This variable enables the daemon mode of imapfilter(1). It takes a numeric argument, the polling interval in seconds.

errors
    By enabling this option any error messages during program's execution get appended to the log file, besides being written to stderr. The argument must be “yes” or “no”. Default is “no.”

expunge
    Normally messages are marked for deletion and are actually deleted when the mailbox is closed. When this option is enabled, messages are expunged after they are marked deleted. The argument must be “yes” or “no”. Default is “no”.

headers
    By enabling this variable, message headers (if requested) are displayed, besides being written to the log file. The argument must be “yes” or “no”. Default is “no”.

logfile
    Full path to log file where filtering information and possible error messages are saved to. The command line -l option overrides this setting.

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. This must be disabled in cases where the user wants to manually specify mailbox names (eg. because they are not part of the user's personal namespace mailboxes). The argument must be “yes” or “no”. Default is “yes”.

subscribe
    By enabling this variable newly created mailboxes get also subscribed; they are set “active” in order for IMAP clients to recognize them. The argument must be “yes” or “no”. Default is “no”.

timeout
    The time in seconds, for the program to wait for a mail server's response. If not set, then the client will block indefinitely.

warning
    If imapfilter(1) cannot lock memory pages, it prints a warning message about "insecure memory". To suppress the warning, this variable must be disabled. The argument must be “yes” or “no”. Default is “yes”.

EXAMPLES
See sample.imapfilterrc.

ENVIROMENT

HOME
    User's home directory.

SEE ALSO
imapfilter(1)

AUTHORS
Lefteris Chatzibarbas <lefcha@hellug.gr>