| Internet-Draft | IMAP UIDBATCHES Extension | July 2025 |
| Eggert | Expires 3 January 2026 | [Page] |
The UIDBATCHES extension of the Internet Message Access Protocol (IMAP) allows clients to retrieve 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.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 3 January 2026.¶
Copyright (c) 2025 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 (https://trustee.ietf.org/license-info) 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.¶
This document defines an extension to the Internet Message Access Protocol [RFC3501] that enables clients to retrieve UID ranges which partition a mailbox's messages into evenly sized batches. This extension is compatible with both IMAP4rev1 [RFC3501] and IMAP4rev2 [RFC9051].¶
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 [RFC9586] UIDONLY mode, where sequence numbers are unavailable to the client, making it difficult to create message batches using traditional methods.¶
In protocol examples, this document uses a prefix of "C: " to denote lines sent by the client to the server, and "S: " for lines sent by the server to the client. Lines prefixed with "// " are comments explaining the previous protocol line. These prefixes and comments are not part of the protocol. Lines without any of these prefixes are continuations of the previous line, and no line break is present in the protocol unless specifically mentioned.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
Other capitalised words are IMAP keywords [RFC3501] or keywords from this document.¶
An IMAP server advertises support for the UIDBATCHES extension by including the UIDBATCHES capability in the CAPABILITY response / response code.¶
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 the first batch containing the highest UIDs (most recent messages).¶
Batches are conceptually organized by descending UID order, meaning batch 1 contains the highest UIDs in the mailbox, batch 2 contains 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¶
The following example demonstrates how a client uses UIDBATCHES to partition a mailbox into manageable batches:¶
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:¶
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. It may decrease, though, as messages are deleted.¶
To prevent server overload, the client MUST NOT re-run UIDBATCHES unless at least one of the following conditions is met:¶
These restrictions protect servers from expensive operations, as computing message batches may be resource-intensive. The client MUST NOT excessively re-run UIDBATCHES while the same mailbox remains selected.¶
The client can keep track of the number of EXPUNGE or VANISH 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 can ask for updated batches by re-running the UIDBATCHES command.¶
The server MAY reject UIDBATCHES commands with a NO response with the LIMIT response code if the client exceeds this limit.¶
The server MUST reply with a UIDBATCHES response, even if no ranges are returned (see Section 3.1.6). The UIDBATCHES response MUST include the tag of the command it relates to (similar to an ESEARCH response).¶
The UID ranges in the response MUST be ordered in descending sequence, from the highest to the lowest UIDs.¶
To ensure efficient server operation and prevent abuse, this extension enforces constraints on batch sizes. These restrictions provide servers with implementation flexibility while preventing clients from misusing the extension to effectively reconstruct sequence numbers.¶
The design balances server efficiency requirements with the primary use case of working effectively with the [RFC9586] UIDONLY mode, without creating a mechanism that circumvents the sequence number restrictions of that mode.¶
Section 3.2 also outlines some reasoning for these limitations.¶
The server MUST support batch sizes of 500 messages or larger.¶
The server MUST respond with NO and a response code TOOFEW if the client uses a batch size that is smaller than the minimum allowed by the server, e.g.¶
S: A302 NO [TOOFEW] Minimum batch size is 500¶
The server MUST NOT return ranges that contain more than the number of messages per batch requested by the client (2,000 in the above example).¶
While servers SHOULD ideally return batches that correspond exactly to the requested size, they MAY return fewer messages per range in two specific circumstances:¶
UIDBATCHES command, particularly when messages are expunged.¶
The flexibility regarding batch sizes is designed to enable efficient server implementations while maintaining predictable behavior for clients. Servers MUST return batches as close as possible to the requested size, provided they can do so efficiently. This leeway is not intended as a general permission to return arbitrarily sized batches, but rather to accommodate implementation constraints and dynamic mailbox changes. When messages are removed from a mailbox during command execution, it may become difficult for servers to maintain exact batch sizes.¶
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. For example, a client requesting 2 batches of 1,000 messages likely intends to display the most recent 2,000 messages.¶
The only exception to this sizing guideline occurs when mailbox state changes during UIDBATCHES execution. In such cases, servers MAY return substantially smaller batches due to message expungement that reduces the overall mailbox size. Clients can detect these situations through the EXPUNGE, VANISHED, or EXISTS responses they receive.¶
Due to these flexibility provisions, servers may return batches of varying sizes. For instance, when returning 3 batches, 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.¶
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.¶
The server MAY return UID ranges with UIDs that do not exist on the server. The client as a result MUST NOT make assumptions about the existence of messages. If the server returns the response¶
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 Section 3.1.3), 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 99704: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.¶
Servers SHOULD end the last UID batch in the mailbox with UID 1 even if this UID does not exist on the server. This makes it unambiguous to the client that this range is in fact the last range.¶
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 more than 100,000 messages, the server would return the 10th to 20th batches. The 10th batch would correspond to message sequence numbers 78,999 through 80,000 and the 20th batch would correspond to message sequence numbers 58,999 through 60,000.¶
Note that batches start at the highest UIDs: 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 section Section 3.1.6.¶
Note that the number of messages per batch returned by the server may be approximate as detailed in Section 3.1.3. 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. The client would then be able to check if the resulting UIDs do in fact overlap.¶
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. 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¶
When the client issues any valid UIDBATCHES command and the mailbox is empty, the server MUST reply with a UIDBATCHES response, e.g.¶
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¶
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 Section 3.1.5 for details on this limit.¶
If the server can not 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 Section 3.1.5 instead of requesting all batches.¶
The 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.¶
The special purpose UIDBATCHES command, though, tries to address two problems:¶
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.¶
Section 3.1.3 describes some implementation restrictions to ensure this.¶
The PARTIAL extension 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 pre-determine 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.¶
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.¶
As noted above, the UIDBATCHES extension allows for 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.¶
UIDBATCHES is not a SEARCH nor UID SEARCH command. Servers that support SEARCHRES [RFC5182] MUST NOT store the result of UIDBATCHES in the $ variable.¶
The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in [RFC5234].¶
Non-terminals referenced but not defined below are as defined by IMAP4 [RFC9051].¶
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 [RFC3501]
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"
¶
This document defines an additional IMAP4 capability. As such, it does not change the underlying security considerations of [RFC3501] and IMAP4rev2 [RFC9051].¶
This document defines an optimization that can both reduce the amount of work performed by the server, as well as 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.¶
IMAP4 capabilities are registered by publishing a standards track or IESG approved Informational or Experimental RFC. The registry is currently located at:¶
https://www.iana.org/assignments/imap4-capabilities¶
IANA is requested to add registrations of the "UIDBATCHES" capability to this registry, pointing to this document.¶
IMAP4 response codes are registered by publishing a standards track or IESG approved Informational or Experimental RFC. The registry is currently located at:¶
https://www.iana.org/assignments/imap-response-codes¶
IANA is requested to add registrations of TOOMANY and TOOFEW to this registry, pointing to this document.¶