IMAPSieve Plugin (imap-sieve)

As defined in the base specification (RFC 5228), the Sieve language is used only during delivery. However, in principle, it can be used at any point in the processing of an email message.

RFC 6785 defines the use of Sieve filtering in IMAP, operating when messages are created or their attributes are changed. This feature extends both Sieve and IMAP.

Therefore, Pigeonhole provides both an IMAP plugin and a Sieve plugin.

The sieve_imapsieve plugin implements the imapsieve extension for the Sieve filtering language, adding functionality for using Sieve scripts from within IMAP.

The imap_sieve plugin for IMAP adds the IMAPSIEVE capability to the imap service. The basic IMAPSIEVE capability allows attaching a Sieve script to a mailbox for any mailbox by setting a special IMAP METADATA entry. This way, users can configure Sieve scripts that are run for IMAP events in their mailboxes.

Beyond the standard, the Pigeonhole implementation also adds the ability for administrators to configure Sieve scripts outside the user's control, that are run either before or after a user's script if there is one.

WARNING

The imapsieve extension can only be used in a Sieve script that is invoked from IMAP. When it is used in the active delivery script, it will cause runtime errors. To make a Sieve script suitable for both delivery and IMAP, the availability of the extension can be tested using the ihave test (RFC 5463) as usual.

Configuration

imap-sieve

The IMAP plugin is activated by adding it to the mail_plugins setting for the imap protocol:

protocol imap {
  mail_plugins {
    imap_sieve = yes
  }
}

This will only enable support for administrator scripts.

User scripts are only supported when a Sieve URL is additionally configured using the imapsieve_url setting. This URL points to the ManageSieve server that users need to use to upload their Sieve scripts. This URL will be shown to the client in the IMAP CAPABILITY response as IMAPSIEVE=<URL>.

User scripts are retrieved from the user's personal storage by name (RFC 6785), which requires no additional configuration.

Script storages for administrator scripts are defined in sieve_script blocks with sieve_script_typebefore or after. These execute administrator scripts before or after the user's personal script, respectively. The sieve_script_cause setting for the administrator storages used by the imap_sieve plugin must include the cause of the IMAP event (RFC 6785): either append, copy, or flag. The sieve_script_cause setting can list several causes together, including the default delivery, which in that case means that those administrator scripts are also executed at delivery.

The applicability of administrator scripts can be limited to a destination mailbox by placing the corresponding sieve_script blocks inside a mailbox block for that mailbox. For a source mailbox, limiting the applicability of administrator scripts can similarly be achieved by placing the corresponding sieve_script blocks inside a imapsieve_from block with that mailbox name. The mailbox and imapsieve_from blocks can be nested when both are required.

The imap_sieve plugin defines an additional script storage type called copy-source-after. Administrator scripts in such storages only apply when the cause is copy and are executed for the message in the source mailbox after the Sieve scripts for the corresponding message in the destination mailbox successfully finish executing. This does not apply to moved messages, since the message is removed from the source mailbox in that case.

sieve-imapsieve

The Sieve plugin is activated by adding it to the sieve_plugins setting:

sieve_plugins {
  sieve_imapsieve = yes
}

This plugin registers the imapsieve extension with the Sieve interpreter. This extension is enabled implicitly, which means that it does not need to be added to the sieve_extensions setting.

Example Configuration

imapsieve_from Spam {
  sieve_script ham {
    type = before
    cause = copy
    path = /etc/dovecot/sieve/ham.sieve
  }
}
mailbox Spam {
  sieve_script spam {
    type = before
    cause = copy
    path = /etc/dovecot/sieve/spam.sieve
  }
}

Settings

imap-sieve

imapsieve_expunge_discarded

Default	no
Value	boolean
See Also	sieve-imapsieve plugin

This setting determines whether de IMAPSieve plugin implicitly also expunges messages that were discarded by the executed Sieve script sequence; i.e., Sieve yielded no (implicit) keep.

imapsieve_from

Default	[None]
Value	Named List Filter
See Also	sieve-imapsieve plugin

Only execute the administrator Sieve scripts for the mailbox configured with sieve_script and type before or after when the message originates from the indicated mailbox. The filter name refers to the imapsieve_from_name setting. Therefore, the contained sieve_script blocks only apply when the source mailbox of the IMAP action match this filter.

imapsieve_from_name

Default	[None]
Value	string
See Also	sieve-imapsieve plugin

The name of the source mailbox for IMAPSieve before or after scripts. The imapsieve_from filter refers to this setting.

imapsieve_url

Default	[None]
Value	URL
See Also	sieve-imapsieve plugin

If set, support for user Sieve scripts in IMAP is enabled.

The value is an URL pointing to the ManageSieve server that users must use to upload their Sieve scripts.

Leave this setting empty if you don't want users to have the ability to associate Sieve scripts with mailboxes.

This has no effect on the administrator-controlled Sieve scripts.

imapsieve_url = sieve://sieve.example.com

sieve_script_cause

Default	delivery
Value	Boolean List
See Also	Script storage

The causes for executing Sieve scripts from this storage. This is currently only relevant for the IMAPSieve plugin. For standard Sieve execution at message delivery the cause is "delivery". Other causes can be append, copy and flag.

sieve-imapsieve

There are no dovecot.conf settings for this plugin.