22 KiB
Supported IMAP Extensions
A complete list of IMAP extension capabilities NIOIMAPCore supports, with links to their RFC specifications.
For more information about IMAP capabilities, see the IANA IMAP Capabilities Registry.
Extension Capabilities
| Capability | RFC | Title | |
|---|---|---|---|
APPENDLIMIT |
Capability/mailboxSpecificAppendLimit + Capability/appendLimit(_:) |
RFC 7889 | IMAP Extensions: APPENDLIMIT |
AUTH= |
Capability/authenticate(_:) |
RFC 3501 | IMAP4rev1 |
BINARY |
Capability/binary |
RFC 3516 | IMAP4 Binary Content Extension |
CATENATE |
Capability/catenate |
RFC 4469 | IMAP CATENATE Extension |
CHILDREN |
Capability/children |
RFC 3348 | IMAP4 Child Mailbox Extension |
CONDSTORE |
Capability/condStore |
RFC 7162 | IMAP Extensions: CONDSTORE and QRESYNC |
CREATE-SPECIAL-USE |
Capability/createSpecialUse |
RFC 6154 | IMAP LIST Extension for Special-Use Mailboxes |
ENABLE |
Capability/enable |
RFC 5161 | The IMAP ENABLE Extension |
ESEARCH |
Capability/extendedSearch |
RFC 4731 | IMAP4 Extension to SEARCH Command for Controlling What Kind of Information is Returned |
ID |
Capability/id |
RFC 2971 | IMAP4 ID Extension |
IDLE |
Capability/idle |
RFC 2177 | IMAP4 IDLE Command |
LIST-EXTENDED |
Capability/listExtended |
RFC 5258 | Internet Message Access Protocol - LIST Command Extensions |
LIST-STATUS |
Capability/listStatus |
RFC 5819 | IMAP4 Extension for Returning STATUS Information in Extended LIST |
LITERAL- |
Capability/literalMinus |
RFC 7888 | IMAP4 Non-synchronizing Literals |
LITERAL+ |
Capability/literalPlus |
RFC 7888 | IMAP4 Non-synchronizing Literals |
LOGIN-REFERRALS |
Capability/loginReferrals |
RFC 2221 | IMAP4 Login Referrals |
LOGINDISABLED |
Capability/loginDisabled |
RFC 3501 | IMAP4rev1 |
MESSAGELIMIT |
Capability/messageLimit(_:) |
RFC 9738 | IMAP4 Extension for Message Limit |
METADATA |
Capability/metadata |
RFC 5464 | The IMAP METADATA Extension |
METADATA-SERVER |
Capability/metadataServer |
RFC 5464 | The IMAP METADATA Extension |
MOVE |
Capability/move |
RFC 6851 | IMAP4 Extension for Moving Messages (MOVE Command) |
MULTIAPPEND |
RFC 3502 | Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension | |
MULTISEARCH |
Capability/multiSearch |
RFC 7377 | IMAP4 Multisearch Extension |
NAMESPACE |
Capability/namespace |
RFC 2342 | IMAP4 Namespace |
OBJECTID |
Capability/objectID |
RFC 8474 | IMAP Extension for Object Identifiers |
PARTIAL |
Capability/partial |
RFC 9394 | IMAP Partial Extension for Fetching Parts of Messages |
PREVIEW |
Capability/preview |
RFC 8970 | IMAP4 PREVIEW Extension |
QRESYNC |
Capability/qresync |
RFC 7162 | IMAP Extensions: CONDSTORE and QRESYNC |
QUOTA |
Capability/quota |
RFC 2087 | IMAP4 Quota Extension |
SASL-IR |
Capability/saslIR |
RFC 4959 | IMAP Extension for Simple Authentication and Security Layer (SASL) Initial Client Response |
SEARCHRES |
Capability/searchRes |
RFC 5182 | IMAP Extension for Referencing the Last SEARCH Result |
SORT |
Capability/sort(_:) |
RFC 5256 | Internet Message Access Protocol - SORT and THREAD Extensions |
SORT=DISPLAY |
Capability/sort(_:) |
RFC 5957 | Display-Based Address Sorting for the IMAP4 SORT Extension |
SPECIAL-USE |
Capability/specialUse |
RFC 6154 | IMAP LIST Extension for Special-Use Mailboxes |
STARTTLS |
Capability/startTLS |
RFC 3501 | IMAP4rev1 |
STATUS=SIZE |
Capability/status(_:) |
RFC 8438 | IMAP4 STATUS Command Extension for Message Size Information |
UIDBATCHES |
Capability/uidBatches |
RFC 10022 | IMAP UIDBATCHES Extension |
UIDONLY |
Capability/uidOnly |
RFC 9586 | IMAP4 UIDONLY Extension |
UIDPLUS |
Capability/uidPlus |
RFC 4315 | Internet Message Access Protocol (IMAP) - UIDPLUS Extension |
UNSELECT |
Capability/unselect |
RFC 3691 | Internet Message Access Protocol (IMAP) UNSELECT Command |
URLAUTH |
Capability/authenticatedURL |
RFC 4467 | Internet Message Access Protocol (IMAP) - URLAUTH Extension |
WITHIN |
Capability/within |
RFC 5032 | WITHIN Search Extension to the IMAP Protocol |
Additional Specifications
In addition to the extension capabilities listed above, NIOIMAP also implements:
- RFC 4466: Collected Extensions to IMAP4 ABNF Syntax
- Gmail IMAP Extensions: Google Gmail IMAP Extension Documentation
Extensions
This section describes each supported IMAP extension and RFC, organized by document. For detailed technical specifications, refer to the relevant RFC.
RFC 3501 and RFC 9051: Base Protocol
RFC 3501 (IMAP4rev1, March 2003) defines the core IMAP protocol, including fundamental operations for accessing and manipulating email messages. RFC 9051 (IMAP4rev2, August 2021) is a modernized revision of the base protocol that updates and clarifies many aspects of RFC 3501.
The base protocol is implemented throughout NIOIMAPCore with types like Command, Response, Flag, MailboxData, and Envelope providing the foundation for all IMAP operations. Additional types include BodyStructure for message MIME structure, and MessageAttribute for message metadata retrieval.
RFC 2087: QUOTA Extension
RFC 2087 (May 1998) defines a mechanism for clients to query mailbox storage quotas on the server. Quotas help users understand their disk usage and help servers manage resources. The extension provides types QuotaLimit, QuotaResource, and QuotaRoot for managing quota-related requests and responses, with quota data returned via ResponsePayload/quota(_:_:) and ResponsePayload/quotaRoot(_:_:).
RFC 2177: IDLE Extension
RFC 2177 (June 1997) introduces the IDLE command, which allows a client to request real-time notifications of mailbox changes from the server instead of polling. This is particularly useful for interactive mail clients that want to display new messages immediately. Use Command/idleStart to initiate idle mode, Response/idleStarted to detect when the server has accepted the idle request, and CommandStreamPart/idleDone to exit idle mode.
RFC 2221: LOGIN-REFERRALS Extension
RFC 2221 (October 1997) extends authentication to support referrals, allowing servers to redirect clients to alternate servers for specific users or mailboxes. The server sends a ResponseTextCode/referral(_:) response code containing an IMAPURL pointing to the appropriate server.
RFC 2342: NAMESPACE Extension
RFC 2342 (May 1998) addresses namespace discovery by defining a NAMESPACE command that allows clients to discover the prefixes and delimiters for personal, other users', and shared mailbox namespaces. This eliminates the need for manual client configuration. The server responds with NamespaceResponse containing NamespaceDescription entries for each namespace.
RFC 2971: ID Extension
RFC 2971 (August 2000) defines an ID command that allows clients and servers to exchange identification information such as name and version, facilitating debugging and feature detection. Clients send identification using Command/id(_:) and servers respond with ResponsePayload/id(_:) containing key-value pairs.
RFC 3348: CHILDREN Extension
RFC 3348 (July 2002) extends mailbox attributes to indicate whether a mailbox has child mailboxes, allowing clients to display appropriate folder hierarchy indicators. Mailboxes use MailboxInfo/Attribute/hasChildren and MailboxInfo/Attribute/hasNoChildren attributes to indicate their hierarchy status.
RFC 3502: MULTIAPPEND Extension
RFC 3502 (April 2003) extends the APPEND command to support appending multiple messages in a single command, improving performance for bulk uploads. The extension uses AppendCommand with support for multiple messages and the AppendCommand/CatenateData type for inline data catenation.
RFC 3516: BINARY Extension
RFC 3516 (October 2003) allows clients to work with message bodies in binary format rather than requiring base64 encoding. The AppendData type supports binary message content, and FetchAttribute provides access to binary message sections.
RFC 3691: UNSELECT Extension
RFC 3691 (February 2004) defines an UNSELECT command that closes the currently selected mailbox without expunging deleted messages, providing an undo-like capability. Use Command/unselect to send the command.
RFC 4315: UIDPLUS Extension
RFC 4315 (December 2005) extends append and copy operations to return the UIDs of newly created messages, allowing clients to track message identities after uploads. The types ResponseCodeAppend and ResponseCodeCopy capture the returned UIDs.
RFC 4466: Collected Extensions to IMAP4 ABNF Syntax
RFC 4466 (April 2006) is a meta-specification that defines generalized ABNF syntax for tagged extensions and recursive option values, used by many subsequent IMAP extensions. Types ParameterValue and OptionValueComp support this extensibility framework.
RFC 4469: CATENATE Extension
RFC 4469 (April 2006) extends the APPEND command to support constructing messages by concatenating existing message parts and new content. This enables efficient message composition without downloading full message bodies. The extension uses AppendCommand with AppendCommand/CatenateData for managing inline data and IUID for message references.
RFC 4467: URLAUTH Extension
RFC 4467 (May 2006) defines URL syntax for referencing IMAP messages and mailboxes, with an optional authorization mechanism (URLAUTH) for secure access without credentials. This enables sharing message links with restricted access. NIOIMAPCore provides comprehensive URL support through types including IMAPURL, FullAuthenticatedURL, AuthenticatedURL, MessagePath, and related URL component types.
RFC 4731: ESEARCH Extension
RFC 4731 (November 2006) extends the SEARCH command with result options that control what information is returned—including minimum/maximum UIDs, all matching message UIDs, or just the count. The ExtendedSearchResponse, SearchReturnOption, and SearchReturnData types support extended search functionality.
RFC 4959: SASL-IR Extension
RFC 4959 (September 2007) allows clients to send the initial SASL response with the AUTHENTICATE command, reducing round trips during authentication. The InitialResponse type captures the initial SASL response data.
RFC 5032: WITHIN Search Extension
RFC 5032 (September 2007) adds a WITHIN search criterion to find messages within a specified number of seconds of a given date, providing fine-grained temporal search capabilities. This is supported through SearchKey criteria.
RFC 5161: ENABLE Extension
RFC 5161 (March 2008) defines an ENABLE command that allows clients to explicitly enable server capabilities, helping coordinate feature support in complex deployments. The server's response is captured in ResponsePayload/enableData(_:) containing an array of enabled Capability values.
RFC 5182: SEARCHRES Extension
RFC 5182 (March 2008) allows search operations to reference the results of the previous search using the $ operator, enabling efficient progressive search refinement. The LastCommandSet type supports this functionality.
RFC 5256 and RFC 5957: SORT and THREAD Extensions
RFC 5256 (June 2008) defines SORT and UID SORT commands for returning search results in a specified order. Use Command/sort(criteria:charset:key:returnOptions:) or Command/uidSort(criteria:charset:key:returnOptions:) with sort order defined by SortCriterion. Display name sorting is also supported via RFC 5957 (July 2010).
RFC 5258: LIST-EXTENDED Extension
RFC 5258 (June 2008) significantly extends the LIST command with selection options and return data options, enabling sophisticated mailbox discovery. Types ListSelectOption, ListSelectBaseOption, and ListSelectIndependentOption provide the selection and filtering capabilities.
RFC 5464: METADATA Extension
RFC 5464 (February 2009) defines a mechanism for storing and retrieving arbitrary metadata (annotations) on mailboxes and the server itself. This enables clients and servers to associate custom data with mailboxes for features like tags, colors, or sync state. Key types include MetadataEntryName, MetadataOption, MetadataResponse, MetadataValue, and related entry types.
RFC 5819: LIST-STATUS Extension
RFC 5819 (March 2010) combines LIST and STATUS command functionality, allowing clients to retrieve mailbox status information (message counts, unseen count) in a single LIST response rather than requiring separate commands. The ReturnOption type supports this combined functionality.
RFC 6154: SPECIAL-USE Mailbox Attributes
RFC 6154 (March 2011) defines standard mailbox attributes for special-use mailboxes such as Drafts, Sent, Trash, and Junk, enabling clients to automatically locate these folders without configuration. Types UseAttribute, ListSelectIndependentOption, and ReturnOption provide special-use support.
RFC 6851: MOVE Extension
RFC 6851 (January 2013) introduces a MOVE command that atomically copies and deletes messages, providing more efficient mailbox organization than separate copy and delete operations. Use Command/move(_:_:) for sequence numbers or Command/uidMove(_:_:) for UIDs.
RFC 7162: CONDSTORE and QRESYNC Extensions
RFC 7162 (May 2014) defines two related extensions for efficient mailbox synchronization. CONDSTORE adds modification sequences (MODSEQs) that allow clients to efficiently detect changed message flags. QRESYNC enables quick resynchronization by allowing clients to check which messages changed since their last access. Relevant types include SearchModificationSequence, FetchModifier, StoreModifier, AttributeFlag, SelectParameter, and ModificationSequenceValue.
RFC 7377: MULTIMAILBOX SEARCH Extension
RFC 7377 (October 2014) extends the SEARCH command to work across multiple mailboxes in a single operation, enabling efficient enterprise-wide searches. Types SearchCorrelator, ExtendedSearchOptions, ExtendedSearchScopeOptions, and ExtendedSearchSourceOptions support multi-mailbox search.
RFC 7888: Non-synchronizing Literals
RFC 7888 (May 2016) introduces LITERAL+ and LITERAL- extensions that allow clients to send literal data without waiting for server synchronization, improving performance for clients that can recover from errors. The AppendData type supports non-synchronizing literal handling.
RFC 7889: APPENDLIMIT Extension
RFC 7889 (May 2016) allows servers to advertise maximum message size limits via a capability parameter, helping clients validate message sizes before attempting to upload. Check Capability/appendLimit(_:) or Capability/mailboxSpecificAppendLimit for limits, and retrieve limits via MailboxStatus/appendLimit in status responses.
RFC 8438: STATUS=SIZE Extension
RFC 8438 (August 2018) extends the STATUS command to return the total size of all messages in a mailbox, providing a way to determine mailbox storage consumption. Request size information using MailboxAttribute/size in status queries, and retrieve it via MailboxStatus/size.
RFC 8474: OBJECTID Extension
RFC 8474 (September 2018) defines persistent object identifiers for messages, mailboxes, and threads, enabling reliable tracking of messages across resynchronizations even when UIDs change. Types EmailID, ThreadID, and MailboxID provide persistent identification for messages, threads, and mailboxes respectively.
RFC 8970: PREVIEW Extension
RFC 8970 (January 2021) extends FETCH to return a server-generated preview (snippet) of message content, allowing clients to display message previews without downloading full message bodies. The FetchAttribute type supports preview retrieval.
RFC 9394: PARTIAL Extension
RFC 9394 (September 2023) allows clients to fetch portions of large messages using range specifications, enabling efficient downloads of specific parts. Types PartialRange, FetchModifier, and SearchReturnData support partial message retrieval.
RFC 9586: UIDONLY Extension
RFC 9586 (August 2023) allows servers to disable sequence-number-based message access, requiring clients to use UIDs exclusively for improved reliability in multi-client scenarios. FETCH responses use FetchResponse/startUID(_:) in UID-only mode.
RFC 9738: MESSAGELIMIT Extension
RFC 9738 (February 2024) allows servers to advertise a maximum number of messages that can be stored in a mailbox. Check Capability/messageLimit(_:) for the server's message limit.
RFC 9979: Further IMAP/JMAP Keywords and Mailbox Name Attributes
RFC 9979 (May 2026) registers a set of message keywords and mailbox name attributes that were already in use across mail servers and clients, so that implementations can rely on their meaning without name collisions. The message keywords are available as Flag/Keyword constants — for example Flag/Keyword/hasAttachment, Flag/Keyword/memo, Flag/Keyword/muted, and Flag/Keyword/notify. The three flag-color keywords Flag/Keyword/colorBit0, Flag/Keyword/colorBit1, and Flag/Keyword/colorBit2 encode one of seven colors on a \Flagged message; use the higher-level FlaggedState (or the lossless RawFlaggedState) to read and update a flagged message's color. The mailbox name attributes are available as UseAttribute/snoozed, UseAttribute/scheduled, and UseAttribute/memos.
RFC 10022: UIDBATCHES Extension
RFC 10022 (July 2026) allows the server to return ranges of UIDs more efficiently when there are large contiguous sequences of UIDs. The UIDBatchesResponse type supports this efficient UID batch representation.
Gmail IMAP Extensions
Google's Gmail IMAP Extensions provide additional capabilities for working with Gmail-specific features like conversation threading and labels. The extensions are indicated by the Capability/gmailExtensions capability and require the X-GM-EXT-1 capability.
Gmail labels, which are equivalent to mailbox tags, are represented using GmailLabel and can be modified via StoreGmailLabels for add, remove, or replace operations. Messages include MessageAttribute/gmailMessageID(_:) for a stable message identifier, MessageAttribute/gmailThreadID(_:) for conversation threading, and MessageAttribute/gmailLabels(_:) for label information. Use FetchAttribute/gmailMessageID, FetchAttribute/gmailThreadID, and FetchAttribute/gmailLabels to retrieve these attributes in FETCH responses.
Messages can also be searched by these identifiers: SearchKey/gmailMessageID(_:) and SearchKey/gmailThreadID(_:) correspond to the X-GM-MSGID and X-GM-THRID search keys, and SearchKey/gmailRaw(_:) sends an X-GM-RAW search using the same query syntax as the Gmail web interface.