Configuring

The application is configured through a YAML file. The default file, ~/.imapautofiler.yml, is read if no other file is specified on the command line.

Server Connection

Each configuration file can hold one server specification.

server:
  hostname: example.com
  username: my-user@example.com

imapautofiler also supports using the keyring module to store and retrieve a password from your system keyring:

server:
  hostname: example.com
  username: my-user@example.com
  use_keyring: true

In this scenario, you will be asked for the password on first run. The password will be stored in your operating system’s secure keyring and reused when running the app. Refer to the keyring documentation for more details about setting up secure password storage.

If you do not want to use the keyring, the connection section can optionally include a password.

server:
  hostname: example.com
  username: my-user@example.com
  password: super-secret

Warning

Because the password is kept in clear text, this mode of operation is only recommended when the configuration file is kept secure by other means.

If the password is not provided in the configuration file and use_keyring is not true, imapautofiler will prompt for a value when it tries to connect to the server.

You can also optionally provide the IMAP servers port and a custom CA file. This is helpful if your company uses custom ports and self issued certs.

server:
  hostname: example.com
  username: my-user@example.com
  port: 1234
  ca_file: path/to/ca_file.pem

Sometimes servers use an SSL/TLS certificate with a common name, which does not match the hostname you are connecting to. Normally, when encountering this situation, imapautofiler will abort the connection with an error:

imapautofiler: error: certificate error for imap.example.com: hostname 'imap.example.com' doesn't match 'bogus.example.com'

You can disable hostname checking for SSL/TLS certs by setting the check_hostname option to a false value (any value other than y, yes, t, true, on, enabled, or 1 (case-insensitive) will be regarded as false. The default is true).

server:
  hostname: imap.example.com
  username: my-user@example.com
  check_hostname: false

Warning

Use at your own risk! Disabling hostname checking is dangerous and makes the connection vulnerable to man-in-the-middle attacks. You should preferably ask the server operator to install a proper certificate instead.

You can disable SSL/TLS connection by setting the ssl option to a false value (any value other than y,``yes``, t, true, on, enabled, or 1 (case-insensitive) will be regarded as false. The default is true).

server:
  hostname: imap.example.com
  username: my-user@example.com
  ssl: false

Warning

Use at your own risk! Disabling SSL/TLS connection is dangerous. You should preferably ask the server operator to install a proper certificate instead.

Maildir Location

As an alternative to a server specification, the configuration file can refer to a local directory containing one or more Maildir folders. This is especially useful when combining imapautofiler with offlineimap.

maildir: ~/Mail

Note

The directory specified should not itself be a Maildir. It must be a regular directory with nested Maildir folders.

Trash Mailbox

The trash action, for discarding messages without deleting them immediately, requires a configuration setting to know the name of the trash mailbox. There is no default value.

trash-mailbox: INBOX.Trash

Mailboxes

The mailboxes that imapautofiler should process are listed under mailboxes. Each mailbox has a name and a list of rules.

mailboxes:
- name: INBOX
  rules: ...
- name: Sent
  rules: ...

Rules

The rules are organized by mailbox, and then listed in order. The first rule that matches a message triggers the associated action, and then processing for that message stops.

TimeLimit Rules

An Time Limit time-limit rule is added by specifying the ‘age’, number of days for the email to “live” in the specified mailbox. If age = 0, the rule is ignored.

- time-limit:
    age: 30

Header Rules

A header rule can match either a complete header value, a substring, or a regular expression against the contents of a specified message header. If a header does not exist, the content is treated as an empty string. The header text and pattern are both converted to lowercase before the comparison is performed.

This example rule matches messages with the string “[pyatl]” in the subject line.

- headers:
    - name: "subject"
      substring: "[pyatl]"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL"

This example rule matches messages for which the “to” header matches the regular expression notify-.*@disqus.net.

- headers:
    - name: to
      regex: "notify-.*@disqus.net"
  action:
    name: trash

This example rule matches messages for which the “Message-Id” header is exactly <4FF56508-357B-4E73-82DE-458D3EEB2753@example.com>.

- headers:
    - name: to
      value: "<4FF56508-357B-4E73-82DE-458D3EEB2753@example.com>"
  action:
    name: trash

Combination Rules

It is frequently useful to be able to apply the same action to messages with different characteristics. For example, if a mailing list ID appears in the subject line or in the list-id header. The or rule allows nested rules. If any one matches, the combined rule matches and the associated action is triggered.

For example, this rule matches any message where the PyATL meetup mailing list address is in the to or cc headers.

- or:
    rules:
      - headers:
          - name: "to"
            substring: "pyatl-list@meetup.com"
      - headers:
          - name: "cc"
            substring: "pyatl-list@meetup.com"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL"

For more complicated formulations, the and rule allows combining other rules so that they all must match the message before the action is taken.

For example, this rule matches any message sent to the PyATL meetup mailing list address with a subject including the text "meeting update".

- and:
    rules:
      - headers:
          - name: "to"
            substring: "pyatl-list@meetup.com"
      - headers:
          - name: "subject"
            substring: "meeting update"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL"

Recipient Rules

The example presented for or rules is a common enough case that it is supported directly using the recipient rule. If any header listing a recipient of the message matches the substring or regular expression, the action is triggered.

This example is equivalent to the example for or.

- recipient:
    substring: "pyatl-list@meetup.com"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL"

Actions

Each rule is associated with an action to be triggered when the rule matches a message.

Move Action

The move action copies the message to a new mailbox and then deletes the version in the source mailbox. This action can be used to automatically file messages.

The example below moves any message sent to the PyATL meetup group mailing list into the mailbox INBOX.PyATL.

- recipient:
    substring: "pyatl-list@meetup.com"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL"

The dest-mailbox value can contain jinja2 template directives using the headers of the message. For example

- recipient:
    substring: "pyatl-list@meetup.com"
  action:
    name: "move"
    dest-mailbox: "INBOX.PyATL.{{ date.year }}"

will extract the year value from the date header of the message and insert it into the destination mailbox path.

Header names are always all lower case and - is replaced by _.

Different IMAP servers may use different naming conventions for mailbox hierarchies. Use the --list-mailboxes option to the command line program to print a list of all of the mailboxes known to the account.

Sort Action

The sort action uses data in a message header to determine the destination mailbox for the message. This action can be used to automatically file messages from mailing lists or other common sources if the corresponding mailbox hierarchy is established. A sort action is equivalent to move except that the destination is determined dynamically.

The action settings may contain a header entry to specify the name of the mail header to examine to find the destination. The default is to use the to header.

The action data may contain a dest-mailbox-regex entry for parsing the header value to obtain the destination mailbox name. If the regex has one match group, that substring will be used. If the regex has more than one match group, the dest-mailbox-regex-group option must specify which group to use (0-based numerical index). The default pattern is ([\w-+]+)@ to match the first part of an email address.

The action data must contain a dest-mailbox-base entry with the base name of the destination mailbox. The actual mailbox name will be constructed by appending the value extracted via dest-mailbox-regex to the dest-mailbox-base value. The dest-mailbox-base value should contain the mailbox separator character (usually .) if the desired mailbox is a sub-folder of the name given.

The example below sorts messages associated with two mailing lists into separate mailboxes under a parent mailbox INBOX.ML. It uses the default regular expression to extract the prefix of the to header for each message. Messages to the python-committers@python.org mailing list are sorted into INBOX.ML.python-committers and messages to the sphinx-dev@googlegroups.com list are sorted into INBOX.ML.sphinx-dev.

- or:
    rules:
      - recipient:
          substring: python-committers@python.org
      - recipient:
          substring: sphinx-dev@googlegroups.com
  action:
    name: sort
    dest-mailbox-base: "INBOX.ML."

The dest-mailbox-base may include jinja2 template instructions, which are evaluated before the suffix is added to the base. Refer to the description of the move action for more details about template evaluation.

Sort Mailing List Action

The sort-mailing-list action works like sort configured to read the list-id header and extract the portion of the ID between < and >. if they are present. If there are no angle brackets in the ID, the entire value is used. As with sort the dest-mailbox-regex can be specified in the rule to change this behavior.

The example below sorts messages to any mailing list into separate folders under INBOX.ML.

- is-mailing-list: {}
  action:
    name: sort-mailing-list
    dest-mailbox-base: "INBOX.ML."

Trash Action

Moving messages to the “trash can” is a less immediate way of deleting them. Messages in the trash can can typically be recovered until they expire, or until the trash is emptied explicitly.

Using this action requires setting the global trash-mailbox option (see Trash Mailbox). If the action is triggered and the option is not set, the action reports an error and processing stops.

This example moves messages for which the “to” header matches the regular expression notify-.*@disqus.net to the trash mailbox.

- headers:
    - name: to
      regex: "notify-.*@disqus.net"
  action:
    name: trash

Delete Action

The delete action is more immediately destructive. Messages are permanently removed from the mailbox as soon as the mailbox is closed.

This example deletes messages for which the “to” header matches the regular expression notify-.*@disqus.net.

- headers:
    - name: to
      regex: "notify-.*@disqus.net"
  action:
    name: delete

Flag and Unflag

The flag action sets the flag of a message.

action:
  name: flag

The unflag action unsets the flag of a message.

action:
  name: unflag

Read and Unread

The mark_read action sets the message as seen or read.

action:
  name: mark_read

The mark_unread action sets the message as unseen or unread.

action:
  name: mark_unread

Complete example configuration file

Here’s an example of a configuration file with all the possible parts.

server:
  hostname: imap.gmail.com
  username: user@example.com
  password: xxxxxxxxxxxxxx

trash-mailbox: "[Gmail]/Trash"

mailboxes:
- name: INBOX
  rules:
  - headers:
    - name: "from"
      substring: user1@example.com
    action:
      name: "move"
      dest-mailbox: "User1 correspondence"
  - headers:
    - name: recipient
      substring: dev-team
    - name: subject
      substring: "[Django] ERROR"
    action:
      name: "move"
      dest-mailbox: "Django Errors"