RFC 10022: IMAP UIDBATCHES Extension

3.1.1. 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.¶

3.1.2. Response Format

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 defined in [RFC4731]).¶

The UID ranges in the response MUST be ordered in descending sequence, from the highest to the lowest UIDs.¶

3.1.3. 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 [RFC9586], without creating a mechanism that circumvents the sequence number restrictions of that mode.¶

S: A302 NO [TOOFEW] Minimum batch size is 500

3.1.4. 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 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 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.¶

3.1.5. 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 Section 3.1.6.¶

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. While the UIDs returned may not correspond to existing messages (as described in Section 3.1.4) 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 Section 3.1.7. 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

3.1.6. 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

3.1.7. 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 Section 3.1.5 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 Section 3.1.5 instead of requesting all batches.¶