One document matched: draft-ietf-sieve-imap-sieve-06.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY Keywds PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY IMAP PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3501.xml'>
<!ENTITY MultiAppend PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3502.xml'>
<!ENTITY Copy PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3894.xml'>
<!ENTITY UIDPlus PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4315.xml'>
<!ENTITY Environment PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5183.xml'>
<!ENTITY Sieve PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5228.xml'>
<!ENTITY Vacation PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5230.xml'>
<!ENTITY IMAP4Flags PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5232.xml'>
<!ENTITY Spamtest PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5235.xml'>
<!ENTITY EditHeader PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5293.xml'>
<!ENTITY Ereject PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5429.xml'>
<!ENTITY Notify PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5435.xml'>
<!ENTITY Metadata PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5464.xml'>
<!ENTITY MIMEloop PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5703.xml'>
<!ENTITY Manage PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5804.xml'>
<!ENTITY Submit PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6409.xml'>
]>
<!-- ?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ? -->
<?rfc toc="yes" ?>
<?rfc tocompact="no" ?>
<?rfc tocindent="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<rfc category="std"
ipr="trust200902"
docName="draft-ietf-sieve-imap-sieve-06">
<front>
<title abbrev="IMAP events in Sieve">
Support for Internet Message Access Protocol (IMAP) Events in Sieve
</title>
<author initials='B.' surname="Leiba" fullname='Barry Leiba'>
<organization>Huawei Technologies</organization>
<address>
<phone>+1 646 827 0648</phone>
<email>barryleiba@computer.org</email>
<uri>http://internetmessagingtechnology.org/</uri>
</address>
</author>
<date/>
<area>Applications</area>
<workgroup>Sieve Working Group</workgroup>
<keyword>IMAP</keyword>
<keyword>Sieve</keyword>
<keyword>email</keyword>
<keyword>filtering</keyword>
<abstract>
<t>
Sieve defines an email filtering language that can, in
principle, plug into any point in the processing of an email
message. As defined in the base specification, it plugs into
mail delivery. This document defines how Sieve can plug into
points in the IMAP protocol where messages are created or changed,
adding the option of user-defined or installation-defined
filtering (or, with Sieve extensions, features such as notifications).
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<section anchor="overview" title="Overview">
<t>
Some applications have a need to apply Sieve filters <xref target="RFC5228"/>
in contexts other than initial mail delivery. This
is especially true in diverse service environments, such as
when the client is sporadically connected, is connected through
a high-latency or high-cost channel, or is on a limited-function
device. For such clients, it may be very important, for higher
performance and reliability, to take advantage of server capabilities,
including those provided by Sieve filtering (and Sieve extensions,
such as Notify <xref target="RFC5435"/>).
</t>
<t>
This specification defines extensions to IMAP <xref target="RFC3501"/>
to support the invocation of Sieve scripts at times when the
IMAP server creates new messages or modifies existing ones.
It also defines how Sieve scripts will process these invocations.
Support for IMAP events in Sieve requires support for
IMAP Metadata <xref target="RFC5464"/>
and Sieve Environment <xref target="RFC5183"/>
as well, because Metadata is used to associate scripts with IMAP
mailboxes and
Environment defines an important way for Sieve scripts to test
the conditions under which they have been invoked.
</t>
</section>
<section anchor="differences" title="Differences Between IMAP Events and Mail Delivery">
<t>
Invoking Sieve scripts in a context other than initial mail delivery
introduces new situations, which changes the applicability of Sieve
features and creates implementation challenges and user interface issues.
This section discusses some of those differences, challenges, and issues.
</t>
<t>
At times other than message delivery, delivery "envelope" information might
not be available. With messages added through IMAP APPEND, there might be no
way to even guess who the intended recipient is, and no concept of who "sent"
the message. Sieve actions that relate to contacting the sender, for example,
will not be applicable.
</t>
<t>
Because IMAP events will often be triggered by user actions, and because
user interfaces allow bulk actions that differ from individual message arrival,
it now becomes possible for a single user action, such as drag-and-drop, to
initiate Sieve script processing on a large number of messages at once.
Implementations will have to deal with such situations as a "COPY" action
or flag changes on dozens, or even thousands of messages.
</t>
<t>
Other issues might surface as this extension is deployed and experience with
it develops.
</t>
</section>
<section anchor="conventions" title="Conventions used in this document">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document
are to be interpreted as described in <xref target="RFC2119"/>.
</t>
</section>
</section>
<section anchor="imapspec" title='The IMAP Events in Sieve Extension'>
<section anchor="capability" title='The "imapsieve" Capability Strings'>
<t>
An IMAP server advertises support for IMAP events in Sieve
through the "imapsieve" capability.
A server that advertises "imapsieve" is claiming to be in
compliance with this specification in all aspects.
The syntax of the "imapsieve" capability string is defined as follows:
<list style="hanging" hangIndent="8">
<t hangText="capability /=">"IMAPSIEVE=" sieveurl-server
<vspace/>
; <sieveurl-server> is defined in RFC 5804, Section 3
</t>
</list>
Only one "imapsieve" capability string, specifying one sieveurl-server,
can be present.
The sieveurl-server identifies the ManageSieve server that clients need to
contact for managing Sieve scripts associated with this IMAP server.
</t>
<t>
The corresponding Sieve implementation uses the Sieve capability
string "imapsieve", and Sieve scripts that depend
upon the IMAP events MUST include that string in their "required"
lists.
</t>
<t>
Implementations that support IMAP events in Sieve MUST also support
IMAP Metadata <xref target="RFC5464"/>
and Sieve Environment <xref target="RFC5183"/>,
because Metadata is used to associate scripts with IMAP
mailboxes and
Environment defines an important way for Sieve scripts to test
the conditions under which they have been invoked.
Notwithstanding the support requirement,
scripts that directly use Environment MUST also include
its capability string in their "required" lists.
</t>
</section>
<section anchor="oldfunc" title='Existing IMAP Functions Affected by IMAP events in Sieve'>
<t>
The subsections below describe in detail the IMAP commands and
situations on which IMAP events in Sieve have an effect.
Not all Sieve actions make sense in the case of messages
affected by IMAP commands.
See <xref target="sieveactions"/> for details.
</t>
<t>
It's important to note that since the base Sieve specification (see <xref target="RFC5228"/>)
and its extensions define functions for scripts that are invoked during
initial mail delivery, those function definitions are necessarily tailored to
and limited by that context. This document extends those function definitions
for use during IMAP events. By nature of that, Sieve functions, in this
extended context, may behave somewhat differently, though their extended
behaviour will still be consistent with the functions' goals.
</t>
<t>
If more than one message is affected at the same time,
each message triggers the execution of a Sieve script separately.
The scripts MAY be run in parallel.
</t>
<section anchor="imapappend" title='The IMAP APPEND Command'>
<t>
A message may be added to a mailbox through the IMAP APPEND
command. In a server that advertises "imapsieve", new messages
added in this way MUST trigger the execution of a Sieve script,
subject to the settings defined through Metadata
(see <xref target="metadata-def"/>).
</t>
</section>
<section anchor="imapmultiappend" title='The IMAP MULTIAPPEND Command'>
<t>
If the IMAP server supports the IMAP MultiAppend extension <xref target="RFC3502"/>,
messages may be added to a mailbox through the IMAP MULTIAPPEND
command. In a server that advertises "imapsieve", new messages
added in this way MUST trigger the execution of a Sieve script,
as with the APPEND command, also subject to the settings
defined through Metadata.
</t>
</section>
<section anchor="imapcopy" title='The IMAP COPY Command'>
<t>
One or more messages may be added to a mailbox through the IMAP COPY
command. In a server that advertises "imapsieve", new messages
added in this way MUST trigger the execution of a Sieve script,
subject to the settings defined through Metadata.
</t>
</section>
<section anchor="imapflags" title='Changes to IMAP Message Flags'>
<t>
One or more existing messages can have their flags changed
in a number of ways, including:
<list style="symbols">
<t>The FETCH command (may cause the \Seen flag to be set).</t>
<t>The STORE command (may cause the \Answered, \Deleted,
\Draft, \Flagged, and \Seen flags to be set or reset,
and may cause keywords to be set or reset).</t>
<t>The invocation of a Sieve script on an existing message,
where the Sieve implementation supports the IMAP4Flags extension
<xref target="RFC5232"/>
and the script uses one of the actions defined in that extension.
</t>
</list>
In a server that advertises "imapsieve", messages whose flags
are changed in any way (except as explained in the next sentence)
MUST trigger the execution of a Sieve script,
subject to the settings defined through Metadata.
The exception is that in order to avoid script loops,
flag changes that are made as a result of a script that was
itself invoked because of flag changes SHOULD NOT result in
another script invocation. In any case, implementations MUST
take steps to avoid such loops.
</t>
<t>
For flag-change events, the Sieve script will see the message flags
as they are AFTER the changes.
</t>
</section>
</section>
<section anchor="newfunc" title='New Functions Defined by IMAP events in Sieve'>
<section anchor="metadata-def" title='Interaction with Metadata'>
<t>
Support for IMAP events in Sieve requires support for
IMAP Metadata <xref target="RFC5464"/>
as well, since the latter is used to associate scripts with IMAP
mailboxes.
</t>
<t>
When an applicable event occurs on an IMAP mailbox, if there is an
IMAP metadata entry named "/shared/imapsieve/script" for the mailbox, that entry
is used. If there is not, but there is an IMAP metadata entry named
"/shared/imapsieve/script" for the server, that entry is used (providing a way
to define a global script for all mailboxes on a server). If neither entry
exists, then no script will be invoked.
</t>
<t>
If a "/shared/imapsieve/script" metadata entry was selected above,
its value is used as the name of the Sieve script
that will be invoked in response to the IMAP event.
If the value is empty, then no script is run.
</t>
<t>
This specifies the mechanism for "activating" a script for
a given mailbox (or for all mailboxes), but does not specify a
mechanism for creating, storing, or validating the script.
Implementations MUST support ManageSieve <xref target="RFC5804"/>,
and can use the PUTSCRIPT command
to store the script without using the SETACTIVE command to activate it.
</t>
<t>
Script names used in "/shared/imapsieve/script" metadata entries
are the script names used on the corresponding ManageSieve server.
If a "/shared/imapsieve/script" metadata entry contains a script name that
doesn't exist in the ManageSieve server, then no Sieve script
will be invoked for IMAP Sieve events.
</t>
<t>
Only one Sieve script may currently be defined per mailbox, eliminating the
complexity and possible ambiguity involved with coordinating the
results of multiple scripts. Any sub-filtering is done in the
Sieve script. For example, if it's only necessary to deal with
flag changes, but not with new messages appended or copied, the
Sieve script will still be invoked for all events, and the script
is responsible for checking the event type.
</t>
<t>
The possibility is open for an extension to add support for multiple
scripts -- for example, per-client scripts on a multi-client user's inbox,
or per-user scripts on a mailbox that is shared among users.
</t>
<t>
Because this metadata name is associated with the mailbox,
there can (and it's expected that there will) be different scripts
associated with events for different mailboxes. Indeed, most
mailboxes will probably invoke no script at all.
</t>
</section>
</section>
</section>
<section anchor="sieveactions" title="Applicable Sieve Actions and Interactions">
<t>
Since some Sieve actions relate specifically to the delivery of
mail, not all actions and extensions make sense when the messages are created
by other means or when changes are made to data associated with
existing messages. This section describes how actions in the base
Sieve specification, and those in extensions known at this writing,
relate to this specification.
</t>
<t>
In addition to what is specified here, interactions noted
in the individual specifications apply, and must be considered.
</t>
<section anchor="action-implicitkeep" title="The Implicit Keep">
<t>
For all cases that fall under IMAP events in Sieve, the implicit keep
means that the message is treated as it would have been if no
Sieve script were run. For APPEND, MULTIAPPEND and COPY, the
message is stored into the target mailbox normally. For flag
changes, the message is left in the mailbox.
If actions have been taken that change the message, those
changes are considered transient and MUST NOT be retained for any
keep action (because IMAP messages are immutable).
No error is generated, but the original message, without the changes, is kept.
</t>
</section>
<section anchor="action-keep" title="The Keep Action">
<t>
The keep action is applicable in all cases that fall under IMAP events in Sieve.
Its behaviour is as described for implicit keep, in <xref target="action-implicitkeep"/>.
</t>
</section>
<section anchor="action-fileinto" title="The Fileinto Action">
<t>
If the Sieve implementation supports the fileinto action,
that action is applicable in all cases that fall under IMAP events in Sieve.
If the Copy extension <xref target="RFC3894"/> is available and
the :copy option is specified, the implicit keep is retained;
otherwise, fileinto cancels the implicit keep, as specified in
the base Sieve specification.
</t>
<t>
For APPEND, MULTIAPPEND, and COPY, the message is stored into the
fileinto mailbox IN ADDITION TO the original target mailbox. For flag
changes, the message is COPIED into the fileinto mailbox,
without removing the original.
In all cases, fileinto always creates a new message, separate from the original.
</t>
<t>
If a keep action is NOT also in effect,
the original message is then marked with the \Deleted
flag (and a flag-change Sieve script is NOT invoked).
The implementation MAY then expunge the original message
(WITHOUT expunging other messages in the mailbox),
or it MAY choose to have expunges batched, or done by a user.
If the server does the expunge, the effect is as though a client had flagged the message and done
a UID EXPUNGE (see <xref target="RFC4315"/>) on the affected message(s) only.
Handling it this way
allows clients to handle messages consistently, and avoids hidden
changes that might invalidate their message caches.
</t>
</section>
<section anchor="action-redirect" title="The Redirect Action">
<t>
The redirect action is applicable in all cases that fall under IMAP events in Sieve.
It causes the message to be sent, as specified in the base Sieve
specification, to the designated address.
If the Copy extension <xref target="RFC3894"/> is available and
the :copy option is specified, the implicit keep is retained;
otherwise, redirect cancels the implicit keep, as specified in
the base Sieve specification.
</t>
<t>
It's possible that a message processed in this way does not have
the information necessary to be redirected properly.
It might lack necessary header information, and there might not
be appropriate information for the MAIL FROM command.
In such cases, the "redirect" action uses
Message Submission <xref target="RFC6409"/>, and it is up to the
Sieve engine to supply the missing information.
The redirect address is, of course, used for the "RCPT TO", and the
"MAIL FROM" SHOULD be set to the address of the owner of the mailbox.
The message submission server is allowed, according to the Message Submission
protocol, to perform necessary fix-up to the message (see Section 8 of RFC 6409).
It can also reject the submission attempt, if the message is too ill-formed
for submission.
</t>
<t>
For APPEND, MULTIAPPEND, and COPY, the message is stored into
the target mailbox in addition to being redirected. For flag
changes, the message remains in its original mailbox.
</t>
<t>
If a keep action is NOT also in effect,
the original message is then marked with the \Deleted
flag (and a flag-change Sieve script is NOT invoked).
The implementation MAY then expunge the original message
(WITHOUT expunging other messages in the mailbox),
or it MAY choose to have expunges batched, or done by a user.
If the server does the expunge, the effect is as though a client had flagged the message and done
a UID EXPUNGE (see <xref target="RFC4315"/>) on the affected message(s) only.
Handling it this way
allows clients to handle messages consistently, and avoids hidden
changes that might invalidate their message caches.
</t>
</section>
<section anchor="action-discard" title="The Discard Action">
<t>
The discard action is applicable in all cases that fall under IMAP events in Sieve.
For APPEND, MULTIAPPEND, and COPY, the message is first stored
into the target mailbox.
If an explicit keep action is also in effect,
the discard action now does nothing. Otherwise,
the original message is then marked with the \Deleted
flag (and a flag-change Sieve script is NOT invoked).
The implementation MAY then expunge the original message
(WITHOUT expunging other messages in the mailbox),
or it MAY choose to have expunges batched, or done by a user.
If the server does the expunge, the effect is as though a client had flagged the message and done
a UID EXPUNGE (see <xref target="RFC4315"/>) on the affected message(s) only.
Handling it this way
allows clients to handle messages consistently, and avoids hidden
changes that might invalidate their message caches.
</t>
</section>
<section anchor="action-notify" title="The Notify Action">
<t>
If the Nofity extension <xref target="RFC5435"/> is available, the
notify action is applicable in all cases that fall under IMAP events in Sieve.
The result is that the requested notification is sent, and that
the message is otherwise handled as it would normally have been.
</t>
</section>
<section anchor="action-addheader" title="The Addheader and Deleteheader Actions">
<t>
If the EditHeader extension <xref target="RFC5293"/> is available,
it can be used to make transient changes to header fields,
which aren't saved in place,
such as for "redirect" or "fileinto" actions.
Because messages in IMAP mailboxes are immutable, such changes
are NOT applicable for the "keep" acton (explicit or implicit).
See <xref target="action-implicitkeep"/>.
</t>
</section>
<section anchor="action-imapflags" title="The Setflag, Deleteflag, and Removeflag Actions">
<t>
Implementations of IMAP events in Sieve MUST also support
the IMAP4Flags extension <xref target="RFC5232"/>, and
the actions associated with it are all applicable to any case that
falls under IMAP events in Sieve.
</t>
<t>
It is worth noting also that the "hasflag" test that is defined in
the IMAP4Flags extension might be particularly useful in scripts triggered
by flag changes ("hasflag" will see the new, changed flags).
The flag changes behave as though a client had
made the change.
</t>
<t>
As explained above, in order to avoid script loops
flag changes that are made as a result of a script that was
itself invoked because of flag changes SHOULD NOT result in
another script invocation. In any case, implementations MUST
take steps to avoid such loops.
</t>
</section>
<section anchor="action-mimeloop" title="MIME Part Tests and Replacement">
<t>
If the MIME Part Tests extension <xref target="RFC5703"/> is available,
all of its functions can be used, but any changes made to the message,
using the "replace" or "enclose" action, MUST be considered transient,
and are only applicable with actions such as "redirect" and "fileinto".
Because messages in IMAP mailboxes are immutable, such changes
are NOT applicable for the "keep" acton (explicit or implicit).
See <xref target="action-implicitkeep"/>.
</t>
</section>
<section anchor="action-spamtest" title="Spamtest and Virustest">
<t>
If the Spamtest and Virustest extensions <xref target="RFC5235"/> are available,
they are applicable in all cases that fall under IMAP events in Sieve.
</t>
</section>
<section anchor="action-inapplicable" title="Inapplicable Actions">
<t>
The following actions and extensions are NOT applicable to any case
that falls under IMAP events in Sieve, because they are specifically
designed to respond to delivery of a new email message.
Their appearance in the "require" control or their use in an IMAP event
MUST result in an error condition that will terminate the Sieve script:
<list>
<t>reject <xref target="RFC5228"/></t>
<t>ereject <xref target="RFC5429"/></t>
<t>vacation <xref target="RFC5230"/></t>
</list>
</t>
<t>
Future extensions that are specifically designed to respond to delivery of
a new email message will likewise not be applicable to this extension.
</t>
</section>
</section>
<section anchor="env-items" title="Interaction With Sieve Environment">
<section anchor="env-base" title="Base Sieve Environment Items: location and phase">
<t>
The Sieve Environment extension defines a set of standard environment items
(see <xref target="RFC5183"/>, Section 4.1).
Two of those items are affected when the script is invoked through an IMAP event.
</t>
<t>
The value of "location" is set to "MS" -- evaluation is being performed
by a Message Store.
</t>
<t>
The value of "phase" is set to "post" -- processing is taking place after
(or perhaps instead of, in the case of APPEND) final delivery.
</t>
</section>
<section anchor="env-imapuser" title="New Sieve Environment Items: imapuser and imapemail">
<t>
In the normal case, when Sieve is used in final delivery, there
is no identity for the "filer" -- the user who is creating or
changing the message. In this case, there is such an identity,
and a Sieve script might want to access that identity.
</t>
<t>
Implementations MUST set and make available two new environment
items:
</t>
<t>
"imapuser" -- the identity (login ID) of the IMAP user that
caused the action.
This MUST be the empty string if it is
accessed during normal (final delivery) Sieve processing.
</t>
<t>
"imapemail" -- the primary email address of the IMAP user that
caused the action (the user identified by "imapuser").
In some implementations, "imapuser" and "imapemail" might have
the same value.
This MUST be the empty string if it is
accessed during normal (final delivery) Sieve processing.
</t>
</section>
<section anchor="env-imapcause" title="New Sieve Environment Item: cause">
<t>
Each mailbox uses a single script for all the change
conditions described in this document (append, copy, flag changes).
To support that, the implementation MUST set the
Environment <xref target="RFC5183"/> item
"cause", which contains the name of the
action that caused the script to be invoked. Its value is one of
the following:
<list style="symbols">
<t>APPEND (for invocations resulting from APPEND or MULTIAPPEND)</t>
<t>COPY (for invocations resulting from COPY)</t>
<t>FLAG (for invocations resulting from flag changes)</t>
</list>
</t>
<t>
Future extensions might define new events and, thus, new causes.
Such extensions will come with their own capability strings, and the events
they define will only be presented when their capabilities are requested.
Scripts that do not request those capabilities will not see those events,
and will not encounter the new cause strings.
</t>
</section>
<section anchor="env-imapmailbox" title="New Sieve Environment Item: mailbox">
<t>
The implementation MUST set the Environment <xref target="RFC5183"/> item
"mailbox" to the name of the mailbox that
the affected message is in, in the case of existing messages, or
is targeted to be stored into, in the case of new messages.
The value of this item is fixed when the script begins, and,
in particular, MUST NOT change as a result of any action, such as
"fileinto".
</t>
</section>
<section anchor="env-imapnewflags" title="New Sieve Environment Item: changedflags">
<t>
If the IMAP4Flags extension <xref target="RFC5232"/> is available,
AND the script was invoked because of flag changes to an existing message,
the implementation MUST set the Environment <xref target="RFC5183"/> item
"changedflags" to the name(s) of the flag(s) that have changed.
If the script was not invoked because of flag changes, the value of this item
MUST be the empty string. The script will not know from this item
whether the flags have been set or reset, but it can use the "hasflag"
test to determine the current value. See example 2 in <xref target="examples"/>
for an example of how this might be used.
</t>
</section>
<section anchor="tests" title="Interaction With Sieve Tests (Comparisons)">
<t>
Any tests against message envelope information, including the "envelope" test
in the Sieve base specification, as well as any such test defined in extensions,
are either inapplicable or have serious interoperability issues when performed
at other than final-delivery time. Therefore, envelope tests MUST NOT be
permitted in the cases described here, and their use MUST generate a runtime error.
</t>
<t>
This extension does not affect the operation of other tests or comparisons
in the Sieve base specification.
</t>
</section>
</section>
<section anchor="examples" title="Examples">
<t>
Example 1:<vspace/>
If a new message is added to the "ActionItems" mailbox, a
copy is sent to the address "actionitems@example.com".
<figure>
<artwork>
require ["copy", "environment", "imapsieve"];
if anyof (environment :is "cause" "APPEND",
environment :is "cause" "COPY") {
if environment :is "mailbox" "ActionItems" {
redirect :copy "actionitems@example.com";
}
}
</artwork>
</figure>
</t>
<t>
Example 2:<vspace/>
If the script is called for any message with the \Flagged
flag set (tested through the IMAP4Flags extension <xref target="RFC5232"/>),
a notification is sent using the Notify extension <xref target="RFC5435"/>.
No notification will be sent, though, if we're called with an
existing message that already had that flag set.
<figure>
<artwork>
require ["enotify", "imap4flags", "variables",
"environment", "imapsieve"];
if environment :matches "mailbox" "*" {
set "mailbox" "${1}";
}
if allof (hasflag "\\Flagged",
not environment :contains "changedflags" "\\Flagged") {
notify :message "Important message in ${mailbox}"
"xmpp:tim@example.com?message;subject=SIEVE";
}
</artwork>
</figure>
</t>
<t>
Example 3:<vspace/>
This shows an example IMAP CAPABILITY response when this extension is supported.
The client has done STARTTLS with the server, and is now inspecting capabilities.
(The untagged CAPABILITY response is split here for readability only, but will be
in one response message.)
<figure>
<artwork>
C: A01 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=PLAIN UIDPLUS LIST-EXTENDED
ACL IMAPSIEVE=sieve://sieve.example.com MULTISEARCH
S: A01 OK done
</artwork>
</figure>
</t>
</section>
<section anchor="security" title="Security Considerations">
<t>
It is possible to introduce script processing loops by having
a Sieve script that is triggered by flag changes use the actions
defined in the IMAP4Flags extension <xref target="RFC5232"/>.
Implementations MUST take steps to prevent such loops.
One way to avoid this problem is that if a script
is invoked by flag changes, and that script further changes
the flags, those flag changes SHOULD NOT trigger a Sieve script
invocation.
</t>
<t>
It is also possible to introduce loops through the "redirect" or "notify"
actions. See Section 10 of Sieve <xref target="RFC5228"/>,
Section 8 of Sieve Notify <xref target="RFC5435"/>,
and the Security Considerations sections of the applicable
notification-method documents for loop-prevention information.
This extension does not change any of that advice.
</t>
<t>
Other security considerations are discussed in
IMAP <xref target="RFC3501"/>, and Sieve <xref target="RFC5228"/>,
as well as in some of the other extension documents.
</t>
</section>
<section anchor="iana" title="IANA Considerations">
<section anchor="iana-0" title='Registration of "imapsieve" IMAP capability'>
<t>
IANA is asked to add "IMAPSIEVE=" to the IMAP 4 Capabilities registry,
according to the IMAP 4 specification <xref target="RFC3501"/>.
(http://www.iana.org/assignments/imap4-capabilities)
</t>
</section>
<section anchor="iana-1" title='Registration of "imapsieve" Sieve extension'>
<t>
The following information should be added to the Sieve Extensions registry,
according to the Sieve specification <xref target="RFC5228"/>.
(http://www.iana.org/assignments/sieve-extensions/sieve-extensions.xml)
</t>
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve extension
<vspace/>
Capability name: imapsieve
<vspace/>
Description: Add Sieve processing for IMAP events.
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section title="Registration of Sieve Environment Items">
<t>
The following subsections register items in the Sieve Environment Items
registry, according to the Environment extension <xref target="RFC5183"/>.
(http://www.iana.org/assignments/sieve-environment-items/
sieve-environment-items.xml)
</t>
<section anchor="iana-2" title="Registration of Sieve Environment Item: cause">
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve environment item
<vspace/>
Item name: cause
<vspace/>
Description:
The name of the action that caused the script to be invoked.
Its value is one of the following:
<list style="symbols">
<t>APPEND (for invocations resulting from APPEND or MULTIAPPEND)</t>
<t>COPY (for invocations resulting from COPY)</t>
<t>FLAG (for invocations resulting from flag changes)</t>
</list>
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section anchor="iana-3" title="Registration of Sieve Environment Item: mailbox">
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve environment item
<vspace/>
Item name: mailbox
<vspace/>
Description:
The name of the mailbox that
the affected message is in, in the case of existing messages, or
is targeted to be stored into, in the case of new messages.
The value of this item is fixed when the script begins, and,
in particular, MUST NOT change as a result of any action, such as
"fileinto".
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section anchor="iana-4" title="Registration of Sieve Environment Item: changedflags">
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve environment item
<vspace/>
Item name: changedflags
<vspace/>
Description:
If the script was invoked because of flag changes to an existing message,
this contains the name(s) of the flag(s) that have changed.
Otherwise, the value of this item MUST be the empty string.
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section anchor="iana-5" title="Registration of Sieve Environment Item: imapuser">
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve environment item
<vspace/>
Item name: imapuser
<vspace/>
Description:
The identity (IMAP login ID) of the IMAP user that
caused the action.
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section anchor="iana-6" title="Registration of Sieve Environment Item: imapemail">
<t>
To: iana@iana.org
<vspace/>
Subject: Registration of new Sieve environment item
<vspace/>
Item name: imapemail
<vspace/>
Description:
The primary email address of the IMAP user that
caused the action (the user identified by "imapuser").
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
</section>
<section anchor="iana-7" title="Registration of IMAP METADATA Mailbox Entry Name">
<t>
The following information should be added to the IMAP METADATA Mailbox Entry Registry,
according to the Metadata extension <xref target="RFC5464"/>.
(http://www.iana.org/assignments/imap-metadata/imap-metadata.xml)
</t>
<t>
To: iana@iana.org
<vspace/>
Subject: IMAP METADATA Entry Registration
<vspace/>
Type: Mailbox
<vspace/>
Name: /shared/imapsieve/script
<vspace/>
Description:
This entry name is used to define mailbox metadata associated
with IMAP events in Sieve for the associated mailbox. Specifically,
this specifies the Sieve script that will be invoked when IMAP events
occur on the specified mailbox.
<vspace/>
Content-type: text/plain; charset=utf-8
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
<section anchor="iana-8" title="Registration of IMAP METADATA Server Entry Name">
<t>
The following information should be added to the IMAP METADATA Server Entry Registry,
items according to the Metadata extension <xref target="RFC5464"/>.
(http://www.iana.org/assignments/imap-metadata/imap-metadata.xml)
</t>
<t>
To: iana@iana.org
<vspace/>
Subject: IMAP METADATA Entry Registration
<vspace/>
Type: Server
<vspace/>
Name: /shared/imapsieve/script
<vspace/>
Description:
This entry name is used to define metadata associated globally
with IMAP events in Sieve for the associated server. Specifically,
this specifies the Sieve script that will be invoked when IMAP events
occur on any mailbox in the server that does not have its own mailbox-level
/shared/imapsieve/script entry.
<vspace/>
Content-type: text/plain; charset=utf-8
<vspace/>
RFC number: [[this RFC]]
<vspace/>
Contact address: Sieve mailing list <sieve@ietf.org>
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
&Keywds;
&IMAP;
&Sieve;
&Metadata;
&Environment;
&IMAP4Flags;
&MultiAppend;
&Copy;
&Manage;
&Submit;
</references>
<references title="Informative References">
&Notify;
&EditHeader;
&Vacation;
&Ereject;
&Spamtest;
&UIDPlus;
&MIMEloop;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 17:26:20 |