IMAP4 Extension for Named Searches (Filters)
Extracted elements (22)
Filter names are restricted to a subset of US-ASCII (ATOM-CHAR minus '/') rather than allowing UTF-8. Because filter names may not always be meaningful or displayable to users, a separate human-readable description annotation hierarchy was introduced to compensate.
The extension reuses GETMETADATA/SETMETADATA commands from the METADATA extension rather than introducing new commands, leveraging existing server-annotation infrastructure for filter lifecycle management (create, read, update, delete, rename).
A client storing a filter value SHOULD wrap any SEARCH key not defined in RFC 3501 in parentheses, to assist other clients in partially parsing the filter for editing purposes. For example, an extension key 'x-dsfa from 5' should be stored as '(x-dsfa from 5)'.
A reference to a nonexistent or unaccessible filter MUST cause failure of the SEARCH command with a tagged NO response that includes the UNDEFINED-FILTER response code followed by the filter name.
Any server compliant with this document MUST either implement the METADATA-SERVER (or METADATA) extension or implement SETMETADATA/GETMETADATA commands for the empty mailbox name case (server annotations).
If a loop is detected or a FILTER search-key remains after at least 3 substitution passes, the implementation MUST behave as if the specified filter does not exist, returning UNDEFINED-FILTER.
If both a private and a public filter with the same name exist, the FILTER search criterion MUST use the value of the private filter; otherwise it MUST use the value of the filter that exists.
If the server cannot create a new filter because the maximum allowed number has been reached, it MUST return a tagged NO response with a [METADATA TOOMANY] response code.
Implementations MUST be able to perform at least 3 substitution passes when a filter references another filter via the FILTER search-key. If more passes are allowed, the implementation MUST implement loop detection.
The server SHOULD verify that each search criterion stored in or referenced by a filter entry is a full and correct search criterion, failing the SEARCH command if not.
Use of the FILTER search key implies CHARSET UTF-8. If the SEARCH/UID SEARCH command includes an explicit CHARSET other than UTF-8 or US-ASCII, the server MUST return a tagged BAD response containing the BADCHARSET response code.
Values of all search keys stored in a filter MUST be encoded in UTF-8.
Filters are created or modified by storing a non-NIL value in the /private/filters/values/<filter_name> or /shared/filters/values/<filter_name> server annotation via SETMETADATA. Deletion is done by storing NIL in both entries.
Filters have two scopes: private (only accessible to the logged-in user) stored under /private/filters/values/<filter_name>, and public (all logged-in users) stored under /shared/filters/values/<filter_name>. Both may coexist with the same name.
Human-readable filter descriptions are stored under /private/filters/descriptions/<filter_name> and /shared/filters/descriptions/<filter_name>, encoded in UTF-8, with optional language tags per RFC 4646.
The FILTER search criterion accepts a filter name and substitutes the stored search criteria verbatim at the point of the FILTER search-key. Syntax: FILTER <filter_name>.
The FILTERS IMAP capability string advertises server support for persistent named searches. Clients discover support via the CAPABILITY response or response code.
The UNDEFINED-FILTER response code is a new resp-text-code extension: 'UNDEFINED-FILTER SP filter-name', returned in the tagged NO response when a referenced filter does not exist or is inaccessible.
IANA registered the FILTERS capability in the IMAP4 capabilities registry. Four IMAP METADATA server entries were also registered: /private/filters/values/<filter_name>, /shared/filters/values/<filter_name>, /private/filters/descriptions/<filter_name>, and /shared/filters/descriptions/<filter_name>.
Excessive use of filters can simplify denial-of-service attacks, especially if loop detection is absent. Servers allowing anonymous access SHOULD NOT allow anonymous users to create, edit, or delete filters.
Stored filters can disclose personal information about users. When confidentiality matters, clients MUST use TLS and/or a SASL security layer as recommended in RFC 3501. Clients should prefer private filters over public ones to limit disclosure.
filter-name is defined as 1*<any ATOM-CHAR except '/'>; it disallows UTF-8 and the characters '(', ')', '{', ' ', '%', '*', ']', restricting names to a subset of US-ASCII.