IMAP UIDBATCHES Extension

3.1.3. Batch Sizes

This extension enforces a hard limit on the minimum batch size that a client can request, and it gives the server some flexibility in the actual size being returned. This ensures the server has implementation flexibility, making the operation less resource-intensive. And to prevent clients from misusing this extension to infer message sequence numbers.¶

The intent of this extension is to work well in combination with [RFC9586] UIDONLY mode without creating a de-facto loophole that re-introduces sequence numbers.¶

Section 3.2 also outlines some reasoning for these limitation.¶

The server MUST support batch sizes of 500 messages or larger.¶

The server MUST respond with BAD and a response code TOOSMALL if the client uses a batch size that is smaller than the minimum allowed by the server, e.g.¶

S: A302 BAD [TOOSMALL] 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). But the server MAY return fewer messages per range, notably if that makes the implementation simpler and/or more efficient.¶

Servers SHOULD NOT return batches that are substantially smaller, and SHOULD aim to be within 90% of the requested size. The client is likely to pick a batch count based on what it wants to display to the user. A client may e.g. request 2 batches of size 1,000 if it wants to be able to display the last 2,000 messages to the user.¶

A server MAY return batches that are substantially smaller if there are changes in mailbox state during the execution of the UIDBATCHES command, namely messages being expunged, such that the overall size of the mailbox changes. The client would be able to infer this from the `EXPUNGE`, `VANISH`, or `EXISTS` messages it receives.¶

If the total number of messages is not evenly divisible by the requested batch size, the last batch will contain the remainder. Thus, the last batch in the mailbox (i.e. the batch with the lowest UIDs) will usually have fewer messages than the requested number of messages.¶

If the requested batch size is equal to or larger than the number of messages in the mailbox, the server MUST return a response with a single UID range that spans all messages.¶

3.1.4. UIDs

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

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 more than 40,000 messages, the server would return the 10th to 20th batches, corresponding to the 20,000th and 40,000th message respectively.¶

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:4

and the selected mailbox has 7,000 messages, the server would then return a UIDBATCHES response with only 4 UID ranges.¶

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 BAD response with the LIMIT response code if the client exceeds this limit.¶

C: A302 UIDBATCHES 2000 1:100
S: A302 BAD [LIMIT] 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, 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