The IMAP METADATA Extension
Extracted elements (29)
Support for private annotations is made OPTIONAL (not required) because it may introduce significantly more complexity to a server in terms of tracking ownership of annotations and determining per-user quota based on their own annotations.
The SETMETADATA and GETMETADATA commands are available only in authenticated or selected IMAP state as defined in [RFC3501]. Servers advertising METADATA-SERVER rather than METADATA indicate support only for server-level annotations, not per-mailbox annotations.
A server that supports unsolicited annotation change responses MUST support the ENABLE [RFC5161] extension and MUST only send unsolicited METADATA responses if the client first used the ENABLE command with 'METADATA' or 'METADATA-SERVER'.
Entry names MUST be specified in a Standards Track or IESG-approved Experimental RFC, or fall under the vendor namespace (using /shared/vendor/<vendor-token> or /private/vendor/<vendor-token>). Vendor tokens MUST be registered with IANA using the ACAP vendor subtree registry.
Entry names MUST NOT contain two consecutive '/' characters, MUST NOT end with '/', MUST NOT contain '*' or '%' characters, and MUST NOT contain non-ASCII characters or octets in the range 0x00–0x19. Entry names are case-insensitive. Invalid entry names result in a BAD response.
If SETMETADATA fails because a value is too large, the server MUST return a tagged NO with '[METADATA MAXSIZE NNN]'. If the annotation count limit is reached, it MUST return '[METADATA TOOMANY]'. If private annotations are unsupported on the mailbox, it MUST return '[METADATA NOPRIVATE]'.
If the METADATA extension is present, support for shared annotations is REQUIRED, whilst support for private annotations is OPTIONAL. When private annotations are restricted, the server MUST return NO when SETMETADATA attempts to create a private server annotation.
In the absence of the ACL extension, users can only set and retrieve annotations on a mailbox returned via LIST/LSUB on which they have read or write access to message content. If the ACL extension is present, users must have the 'l' right and at least one of 'r', 's', 'w', 'i', or 'p' rights. Servers MUST respond with NO if conditions are not met.
Servers SHOULD delete annotations for a mailbox when the mailbox is deleted, so that a new mailbox created with the same name does not inherit the old mailbox's annotations.
Servers SHOULD ensure that mailbox annotations are automatically moved when a mailbox is renamed (annotations follow the mailbox). When INBOX is renamed, annotations are copied to the renamed mailbox so that INBOX retains its annotations.
The server MUST accept an annotation data size of at least 1024 bytes and an annotation count per server or mailbox of at least 10. Servers may impose further limits beyond these minimums.
The server SHOULD NOT return a METADATA response containing updated annotation data after a SETMETADATA command. Clients MUST NOT assume a METADATA response will be sent, and MUST assume that if the command succeeds, the annotation has been changed.
Unsolicited METADATA responses MUST only contain entry names, not values. When a client receives an unsolicited METADATA response and wants current values, it must explicitly issue a GETMETADATA command to retrieve them.
When any one annotation in a SETMETADATA command fails to be set (resulting in a tagged NO), the server MUST NOT change the values of any other annotations specified in the same command. The operation is atomic across all entries in the command.
Each annotation entry has a hierarchical slash-separated name. The first component MUST be either '/private' (per-user, not visible to others) or '/shared' (shared among authorized users with appropriate access). Vendor-specific entries use /shared/vendor/<vendor-token> or /private/vendor/<vendor-token> prefixes.
The DEPTH GETMETADATA option extends results to include child entries. DEPTH 0 returns only the specified entry; DEPTH 1 returns the entry and its immediate children; DEPTH infinity returns the entry and all descendants. If DEPTH is omitted, DEPTH 0 is assumed.
The GETMETADATA command retrieves server or mailbox annotations. An empty mailbox-name string retrieves server annotations; a non-empty string retrieves annotations on the named mailbox. It is available only in authenticated or selected state. Optional MAXSIZE and DEPTH options may be included.
The MAXSIZE GETMETADATA option restricts returned entry values to those whose octet size is less than or equal to the specified limit. If any entries exceed the limit, the server MUST include the METADATA LONGENTRIES response code in the tagged OK response, reporting the size of the largest excluded entry.
The METADATA extension adds two new IMAP commands (SETMETADATA and GETMETADATA), one new untagged response (METADATA), and a new METADATA response code. A server supporting both server and mailbox annotations advertises 'METADATA'; a server supporting only server annotations advertises 'METADATA-SERVER'.
The METADATA untagged response returns results for GETMETADATA or is sent unsolicited when annotations change due to a third party. It contains either entry-value pairs (solicited) or entry names only (unsolicited). Multiple entries may appear in a single response or across multiple responses.
The SETMETADATA command sets one or more entry-value pairs on a mailbox or the server (empty mailbox string). Setting a value to NIL removes the entry. Multiple entries can be set atomically in a single command.
Initial mailbox entries registered: '/shared/comment' (text/plain; charset=utf-8, a shared comment associated with the mailbox) and '/private/comment' (text/plain; charset=utf-8, a per-user private comment associated with the mailbox).
Initial server entries registered: '/shared/comment' (text/plain; charset=utf-8, a shared comment associated with the server) and '/shared/admin' (text/plain; charset=utf-8, a read-only URI for contacting the server administrator).
This document creates an IANA registry for IMAP METADATA entries. Each registration requires: Type (Mailbox or Server), Name (entry path), Description, Content-type with charset, RFC Number, and Contact. All entries must have '/shared' or '/private' as a prefix, and non-vendor entries must be defined in a Standards Track or IESG-approved Experimental RFC.
Annotations whose values are intended to remain private MUST be stored only in entries with the '/private' prefix. Servers MAY choose to only support METADATA extensions after a privacy layer (e.g., TLS) has been negotiated by the client, to protect annotations from snooping.
Servers MUST enforce annotation size limits to prevent a user from consuming all available server space. Clients MUST treat annotation data values as an 'untrusted' source, as annotation values may contain malicious content.
Entry names are encoded as IMAP astrings (slash-separated paths). Values are encoded as nstring or literal8, allowing NIL, quoted strings, or binary literals. Multi-line string values MUST use CRLF (0x0D 0x0A) to represent line endings. The ABNF is defined in Section 5.
New response codes defined: 'METADATA LONGENTRIES' SP number (size of largest entry exceeding MAXSIZE), 'METADATA MAXSIZE' SP number (server's max accepted annotation size), 'METADATA TOOMANY' (annotation count limit reached), and 'METADATA NOPRIVATE' (private annotations unsupported on this mailbox).
The METADATA response syntax is: 'METADATA' SP mailbox SP (entry-values / entry-list), where entry-values is a parenthesized list of entry SP value pairs, and entry-list is a space-separated list of entry names only (for unsolicited responses). An empty string mailbox implies server annotation.