Apple Inc

One Apple Park Way Cupertino CA 95014 United States of America deggert@apple.com

ART mailmaint IMAP The UIDBATCHES extension of the Internet Message Access Protocol (IMAP) allows clients to retrieve Unique Identifier (UID) ranges that partition a mailbox's messages into equally sized batches. This enables clients to perform operations such as FETCH, SEARCH, and STORE on specific message batches, providing better control over resource usage and response sizes. The extension is particularly useful with the UIDONLY mode where sequence numbers are unavailable.

Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at .

Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents () in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

Table of Contents

• .  Introduction
• .  Document Conventions
• .  The UIDBATCHES Extension
  • .  UIDBATCHES Command
    • .  Example Usage
    • .  Response Format
    • .  Batch Sizes
    • .  UIDs
    • .  Batch Ranges
    • .  Empty Responses
    • .  Large Mailboxes
  • .  Interaction with MESSAGELIMIT Extension
  • .  Interaction with UIDONLY Extension
  • .  Interaction with SEARCHRES Extension
• .  Formal Syntax
• .  Operational Considerations
• .  Security Considerations
• .  IANA Considerations
• .  References
  • .  Normative References
  • .  Informative References
• .  Comparison with Existing Commands and Extensions
  • .  Similarity to UID SEARCH Command
  • .  Similarity to PARTIAL Extension
• Author's Address

Introduction This document defines an extension to the Internet Message Access Protocol (IMAP) that enables clients to retrieve UID ranges that partition a mailbox's messages into evenly sized batches. This extension is compatible with both IMAP4rev1 and IMAP4rev2 . The primary purpose of this extension is to allow clients to predetermine UID ranges that limit the number of messages each command operates on. This capability is especially beneficial when used with the UIDONLY mode , where sequence numbers are unavailable to the client, making it difficult to create message batches using conventional methods.

Document Conventions In protocol examples, "C:" indicates lines sent by a client that is connected to a server and "S:" indicates lines sent by the server to the client. These prefixes are not part of the protocol. Long lines in examples are wrapped using "The Single Backslash Strategy" described in . The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Other capitalized words are IMAP keywords or keywords from this document.

The UIDBATCHES Extension An IMAP server advertises support for the UIDBATCHES extension by including the UIDBATCHES capability in the CAPABILITY response / response code.

UIDBATCHES Command

Arguments:

Message count per batch. OPTIONAL batch range.

Responses:

REQUIRED untagged response: UIDBATCHES

Result:

OK uidbatches completed NO command exceeds limits BAD command unknown or arguments invalid

The UIDBATCHES command requests UID ranges that partition the messages in the currently selected mailbox into equally sized batches. The server returns these ranges in descending UID order, with batch 1 containing the highest UIDs (most recent messages), batch 2 containing the next highest set of UIDs, and so on. For a mailbox with M messages, requesting batches of size N returns UID ranges corresponding to the following sequence number ranges (where sequence numbers are ordered from 1 to M, with M being the most recent message): Batch 1: M:(M-N+1) // Most recent N messages Batch 2: (M-N):(M-2*N+1) // Next N messages Batch 3: (M-2*N):(M-3*N+1) // Next N messages ...and so on

Example Usage The following example demonstrates how a client uses UIDBATCHES to partition a mailbox into manageable batches: ========== NOTE: '\' line wrapping per RFC 8792 =========== C: A142 SELECT INBOX S: * 6823 EXISTS S: * 1 RECENT S: * OK [UNSEEN 12] Message 12 is first unseen S: * OK [UIDVALIDITY 3857529045] UIDs valid S: * OK [UIDNEXT 215296] Predicted next UID S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited S: A142 OK [READ-WRITE] SELECT completed C: A143 UIDBATCHES 2000 S: * UIDBATCHES (TAG "A143") \ 215295:99696,99695:20351,20350:7830,7829:1 S: A143 OK UIDBATCHES Completed The server's response provides four UID ranges:

1. 215295:99696
2. 99695:20351
3. 20350:7830
4. 7829:1

Each range contains up to 2,000 messages, except the last range, which contains the remaining 823 messages. As new messages cannot appear within these UID ranges, the number of messages in each range will not increase. However, it may decrease as messages are deleted. It is only appropriate to resend UIDBATCHES if one of the following conditions is met:

1. A different mailbox has been selected
2. More than N/2 messages have been expunged from the mailbox (where N is the batch size)
3. More than N/2 new messages have been received into the mailbox

To prevent server overload, the client MUST NOT resend UIDBATCHES otherwise. Computing message batches may be resource-intensive for servers. The client can keep track of the number of EXPUNGE or VANISHED messages and re-run UIDBATCHES if many messages are deleted. As new messages arrive into the mailbox, the client should add these to a new message batch (starting at UID 215296 in the above example). Once N/2 or more new messages have been added to the mailbox, the client MAY ask for updated batches by re-running the UIDBATCHES command. The server SHOULD reject UIDBATCHES commands with a NO response with the LIMIT response code if the client exceeds this limit. Servers MAY choose to track client requests and mailbox state changes to enforce these restrictions and prevent resource abuse.

Response Format The server MUST reply with a UIDBATCHES response, even if no ranges are returned (see ). The UIDBATCHES response MUST include the tag of the command it relates to (similar to an ESEARCH response defined in ). The UID ranges in the response MUST be ordered in descending sequence, from the highest to the lowest UIDs.

Batch Sizes To ensure efficient server operation and prevent abuse, this extension enforces constraints on batch sizes. The design balances server efficiency requirements with the primary use case of working effectively with the UIDONLY mode , without creating a mechanism that circumvents the sequence number restrictions of that mode.

Batch Size Summary The following table provides a quick reference for batch size constraints: Batch Size Constraints

Constraint	Client Request	Server Response
Minimum	500 messages	Aim for >= 90% of requested size
Maximum	No limit	Never exceed requested size
Exception	-	May be smaller during mailbox changes

Key principles:

• Clients MUST request at least 500 messages per batch (see Sections and )
• Servers MUST NOT return more messages than requested
• Servers SHOULD return batches close to the requested size (>= 90% when possible)
• Exact batch sizes may vary due to implementation efficiency or mailbox changes

Minimum Batch Size The server MUST support batch sizes of 500 messages or larger. This minimum size prevents clients from misusing the extension to effectively reconstruct sequence numbers while still allowing reasonable batch operations. Note that clients MUST be prepared to handle batches smaller than requested, as detailed in . The server MUST respond with NO and a response code TOOFEW if the client uses a batch size smaller than the minimum allowed by the server: S: A302 NO [TOOFEW] Minimum batch size is 500

Server Response Flexibility While servers SHOULD return batches that correspond exactly to the requested size, they have flexibility in specific circumstances to enable efficient implementations.

Hard Constraints The server MUST NOT return ranges that contain more than the number of messages per batch requested by the client. This is a strict upper bound that cannot be exceeded. If the requested batch size equals or exceeds the total number of messages in the mailbox, the server MUST return a single UID range spanning all messages.

Permitted Variations Servers MAY return fewer messages per range in two specific circumstances:

1. When doing so makes the implementation substantially simpler and/or more efficient
2. When there are changes in mailbox state during the execution of the UIDBATCHES command, particularly when messages are expunged

However, servers SHOULD NOT return batches that are substantially smaller than requested and SHOULD aim to stay within 90% of the requested size. This guideline reflects the fact that clients typically choose batch sizes based on their intended use, such as displaying a specific number of messages to users.

Dynamic Changes Mailbox state changes during UIDBATCHES execution can result in servers returning substantially fewer messages in each batch, particularly when message expungement reduces the overall mailbox size. Clients can detect these situations through the EXPUNGE, VANISHED, or EXISTS responses they receive.

Practical Implications Due to these flexibility provisions, servers may return batches of varying sizes. For instance, when returning 3 batches of a requested size of 1,000, one might contain 990 messages, another 977, and the third 1,000 messages. Clients MUST be prepared to handle such variations. When the total number of messages is not evenly divisible by the requested batch size, the final batch will contain the remainder. Therefore, the last batch in the mailbox (containing the lowest UIDs) will typically have fewer messages than requested.

Design Rationale These restrictions provide servers with implementation flexibility while preventing clients from misusing the extension to effectively reconstruct sequence numbers. also outlines some reasoning for these limitations. The flexibility regarding batch sizes is designed to enable efficient server implementations while maintaining predictable behavior for clients. This leeway is not intended as a general permission to return arbitrarily sized batches but rather to accommodate implementation constraints and dynamic mailbox changes.

UIDs The server MAY return UID ranges with UIDs that do not exist on the server. As a result, the client MUST NOT make assumptions about the existence of messages. If the server returns the response: ========== NOTE: '\' line wrapping per RFC 8792 =========== S: * UIDBATCHES (TAG "A302") \ 163886:99703,99696:20358,20351:7841,7830:1 S: A302 OK UIDBATCHES Completed there may not be any messages on the server with the UIDs such as 163886, 99703, 99696, etc. The range 163886:99703 will span approximately the requested number of messages (may be less, see ), but its start and end UIDs may not correspond to messages on the server. This gives the server implementation some flexibility as to which UID ranges to return. They might, e.g., return 163886:99697 and 99696:20358 instead of 163886:99703 and 99696:20358 -- assuming that there are no messages in the range 99702:99697. If there are fewer messages in the mailbox than the requested batch size, the server would return a single batch that contains all messages in the mailbox. When applying the flexibility described above to the last batch in the mailbox, ending that batch with UID 1 makes it unambiguous to the client that this range is in fact the last range. For example, if the message with the lowest UID is 302, the server can return 7829:1 instead of 7829:302.

Batch Ranges A client can optionally provide a batch range. The server limits its response to UID ranges corresponding to the specified batch indices. For example, if the client sends: C: A302 UIDBATCHES 2000 10:20 for a mailbox with 100,000 messages, the server would return the 10th to 20th batches. The 10th batch would correspond to message sequence numbers `82000:80001` and the 20th batch would correspond to message sequence numbers `62000:60001`. Batches start at the highest UIDs, i.e., batch 1 is the batch with the highest UIDs. The UID ranges that the server returns would still split the mailbox's messages into batches of the requested size (2,000 in the example). If the client requests more batches than exist on the server, the server would return those that do exist. For example, if the client sends: C: A302 UIDBATCHES 2000 1:5 and the selected mailbox has 7,000 messages, the server would then return a UIDBATCHES response with only 4 UID ranges. Batch ranges such as 1:4 in the above example MUST be ordered lowest to highest, i.e., be sent as 1:4 and not as 4:1. Servers MUST reject batch ranges that are in the wrong order with BAD and a response code CLIENTBUG: C: A302 UIDBATCHES 2000 4:1 S: A302 BAD [CLIENTBUG] Invalid batch range If the client requests a range of batches that do not exist on the server, the server MUST still return an empty response. See . The number of messages per batch returned by the server may be approximate, as detailed in . As a result, if the client needs to request consecutive batch ranges such as 1:100, 101:200, 201:300, and so on, the client may want to make these batch ranges overlap by, e.g., requesting 1:100, 100:200, and 200:300. While the UIDs returned may not correspond to existing messages (as described in ) and mailbox state can change between requests, checking whether the returned UID ranges overlap can help clients detect potential inconsistencies, though how to handle such situations depends on the specific client implementation requirements. Clients MUST NOT request batch ranges that span more than 100,000 messages, i.e., the number of batches multiplied by the batch size MUST NOT be larger than 100,000. This restriction applies only when a batch range is specified; when no batch range is provided, the client is requesting all batches but the server may limit its response as described in . The server MAY reject UIDBATCHES commands with a NO response with the TOOMANY response code if the client exceeds this limit. C: A302 UIDBATCHES 2000 1:100 S: A302 NO [TOOMANY] Too many messages

Empty Responses When the client issues any valid UIDBATCHES command and the mailbox is empty, the server MUST reply with a UIDBATCHES response, for example: S: * UIDBATCHES (TAG "A302") S: A302 OK UIDBATCHES Completed If the client requests a range of batches that do not exist, the server MUST reply with an empty UIDBATCHES response. If the mailbox has 7,000 messages, and the client sends: C: A302 UIDBATCHES 2000 6:8 the server would respond with: S: * UIDBATCHES (TAG "A302") S: A302 OK UIDBATCHES Completed

Large Mailboxes The server may not be able to return all UID ranges if the mailbox contains an extremely large number of messages. The server MUST at least support returning UID ranges spanning 100,000 messages. See for details on this limit. If the server cannot return all of the requested UID ranges, it MUST respond with a NO response with the TOOMANY response code. Notably, when the client requests all UID ranges and the mailbox has more than 100,000 messages, the server MAY reply with a NO response. For example: C: A302 UIDBATCHES 2000 S: A302 NO [TOOMANY] Too many messages in mailbox The client should know what the message count in the mailbox is, and if the message count exceeds 100,000, it may choose to always request batch ranges as discussed in instead of requesting all batches.

Interaction with MESSAGELIMIT Extension When the server supports both the MESSAGELIMIT and UIDBATCHES extension, the client SHOULD request batches no larger than the specified maximum number of messages that can be processed in a single command. The client MAY choose to use a smaller batch size. Additionally, since servers MAY limit the number of UIDs returned in response to UIDBATCHES, it is reasonable to assume that they would at most return N UIDs, where N is the limit the server announced as its MESSAGELIMIT.

Interaction with UIDONLY Extension The UIDBATCHES extension allows clients to create UID ranges for message batches even when the connection operates in UIDONLY mode, which otherwise doesn't allow for using message sequence numbers. This interaction is particularly important because the UIDONLY extension disallows the use of sequence numbers. While the PARTIAL extension provides paged SEARCH and FETCH operations, some clients need to predetermine UID ranges for batches upfront. UIDBATCHES enables such clients to use the same overall batching strategy, regardless of whether the server supports UIDONLY, PARTIAL, or neither, making client implementations simpler and more consistent. When operating in UIDONLY mode, clients SHOULD use UIDBATCHES to determine appropriate UID ranges for batch operations rather than attempting to construct batches using sequence-number-based approaches that would violate UIDONLY restrictions. The batch size constraints defined in serve dual purposes: ensuring server efficiency and preventing UIDBATCHES from becoming a mechanism to effectively reconstruct sequence numbers. Without these constraints, clients could request very small batch sizes to obtain fine-grained positional information about messages, which would circumvent the sequence number restrictions of UIDONLY mode. The extension is designed specifically to support the legitimate need of predetermining message batches upfront while maintaining the architectural intent of UIDONLY mode.

Interaction with SEARCHRES Extension UIDBATCHES is not a SEARCH nor UID SEARCH command. Servers that support SEARCHRES MUST NOT store the result of UIDBATCHES in the $ variable.

Formal Syntax The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in . Non-terminals referenced but not defined below are as defined by IMAP4 . Except as noted otherwise, all alphabetic characters are case-insensitive. The use of upper or lower case characters to define token strings is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion. capability =/ "UIDBATCHES" ;; <capability> from [RFC9051] command-select =/ message-batches message-batches = "UIDBATCHES" SP nz-number [SP nz-number ":" nz-number] uidbatches-response = "UIDBATCHES" search-correlator [SP uid-range *("," uid-range) ] mailbox-data =/ uidbatches-response resp-text-code =/ "TOOFEW" / "TOOMANY"

Operational Considerations This document defines an optimization that can reduce both the amount of work performed by the server and the amount of data returned to the client. Use of this extension is likely to cause the server and the client to use less memory than when the extension is not used. However, as this is going to be new code in both the client and the server, rigorous testing of such code is required in order to avoid the introduction of new implementation bugs.

Security Considerations This document defines an additional IMAP4 capability. As such, it does not change the underlying security considerations of IMAP4rev1 and IMAP4rev2 . The author and reviewers believe that no new security issues are introduced with this additional IMAP4 capability. One consideration during the design of this extension was the potential for clients to cause servers to perform excessive computational work by repeatedly requesting batch calculations. The restrictions on when clients may re-run UIDBATCHES () and the batch size constraints () are designed to mitigate this concern. Server implementations are strongly advised to implement enforcement of these rate-limiting restrictions rather than relying solely on client compliance. Servers SHOULD track UIDBATCHES requests per mailbox and reject requests that violate the conditions in , as failure to do so may allow malicious or buggy clients to cause resource exhaustion through repeated batch calculations. Servers may reject requests that exceed these limits with the LIMIT, TOOFEW, or TOOMANY response codes. As this extension involves new code in both clients and servers, rigorous testing of such code is required in order to avoid introducing new implementation bugs.

IANA Considerations IANA has added the UIDBATCHES capability to the "Internet Message Access Protocol (IMAP) Capabilities Registry", with a reference to this document. IANA has added TOOMANY and TOOFEW to the "IMAP Response Codes" registry, with a reference to this document.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev1 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev1 also provides the capability for an offline client to resynchronize with the server. IMAP4rev1 includes operations for creating, deleting, and renaming mailboxes, checking for new messages, permanently removing messages, setting and clearing flags, RFC 2822 and RFC 2045 parsing, searching, and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev1 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev1 supports a single server. A mechanism for accessing configuration information to support multiple IMAP4rev1 servers is discussed in RFC 2244. IMAP4rev1 does not specify a means of posting mail; this function is handled by a mail transfer protocol such as RFC 2821. [STANDARDS-TRACK] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The Internet Message Access Protocol Version 4rev2 (IMAP4rev2) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev2 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev2 also provides the capability for an offline client to resynchronize with the server. IMAP4rev2 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; removing messages permanently; setting and clearing flags; parsing per RFCs 5322, 2045, and 2231; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev2 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev2 does not specify a means of posting mail; this function is handled by a mail submission protocol such as the one specified in RFC 6409. The MESSAGELIMIT extension of the Internet Message Access Protocol (RFCs 3501 and 9051) allows servers to announce a limit on the number of messages that can be processed in a single FETCH, SEARCH, STORE, COPY, or MOVE command (or their UID variants), or in a single APPEND or UID EXPUNGE command. This helps servers to control resource usage when performing various IMAP operations. This helps clients to know the message limit enforced by the corresponding IMAP server and avoid issuing commands that would exceed such limit. Informative References This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands with several result options, which can control what kind of information is returned. The following result options are defined: minimal value, maximal value, all found messages, and number of found messages. [STANDARDS-TRACK] Many IMAP clients use the result of a SEARCH command as the input to perform another operation, for example, fetching the found messages, deleting them, or copying them to another mailbox. This can be achieved using standard IMAP operations described in RFC 3501; however, this would be suboptimal. The server will send the list of found messages to the client; after that, the client will have to parse the list, reformat it, and send it back to the server. The client can't pipeline the SEARCH command with the subsequent command, and, as a result, the server might not be able to perform some optimizations. This document proposes an IMAP extension that allows a client to tell a server to use the result of a SEARCH (or Unique Identifier (UID) SEARCH) command as an input to any subsequent command. [STANDARDS-TRACK] This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. The PARTIAL extension of the Internet Message Access Protocol (see RFCs 3501 and 9051) allows clients to limit the number of SEARCH results returned, as well as to perform incremental (paged) searches. This also helps servers to optimize resource usage when performing searches. This document extends the PARTIAL SEARCH return option originally specified in RFC 5267. It also clarifies some interactions between RFC 5267 and RFCs 4731 and 9051. This document updates RFCs 4731 and 5267. The UIDONLY extension to the Internet Message Access Protocol (RFCs 3501 and 9051) allows clients to enable a mode in which information about mailbox changes is returned using only Unique Identifiers (UIDs). Message numbers are not returned in responses and cannot be used in requests once this extension is enabled. This helps both clients and servers to reduce resource usage required to maintain a map between message numbers and UIDs. This document defines an experimental IMAP extension.

Comparison with Existing Commands and Extensions

Similarity to UID SEARCH Command UIDBATCHES is in effect nothing more than shorthand for a UID SEARCH command of the form C: A145 UID SEARCH RETURN () <M>,<M-N>,<M-2*N>,<M-3*N>,... where M is the number of messages in the mailbox and N is the requested batch count. However, the special purpose UIDBATCHES command tries to address two problems:

1. For many servers, UID SEARCH commands specifying sequence numbers are costly, especially for mailboxes with many messages.
2. The UIDONLY extension disallows the use of sequence numbers and thus makes it difficult for the client to split its commands into batches of a size that works well for the client and server.

By providing a special purpose command, servers can implement a different, optimized code path for determining message batches. And servers using the UIDONLY extension can provide a facility to let the client determine message batches without using sequence numbers in a UID SEARCH command. describes some implementation restrictions to ensure this.

Similarity to PARTIAL Extension The PARTIAL extension in provides a different way for the client to split its commands into batches by using paged SEARCH and FETCH. The intention of the UIDBATCHES command is to let the client predetermine message batches of a desired size. This makes it easier for the client to share implementation between servers, regardless of their support of PARTIAL. And additionally, because the client can issue a corresponding UID SEARCH command to servers that do not implement UIDBATCHES, the client can use similar batching implementations for servers that support UIDBATCHES and those that do not.

Author's Address Apple Inc

One Apple Park Way Cupertino CA 95014 United States of America deggert@apple.com