IMAP Response Code for Command Progress Notifications
Extracted elements (22)
CMD-TAG is included in the notification so clients running multiple concurrent in-flight commands can correlate progress updates to specific commands; using NIL is still useful for single-command scenarios.
The extension was introduced because existing IMAP mechanisms allowed servers to send generic untagged OK messages (e.g., '* OK Still on it, 57% done') but provided no standard structure for progress reporting, leaving clients unable to parse or act on such information systematically.
When GOAL changes or PROGRESS goes backward, the RECOMMENDED interpretation is that the previous GOAL has been reached but the server discovered further long-running work is required with a new (known or unknown) GOAL, accommodating multi-phase operations.
A client can ensure reception of notifications with non-NIL CMD-TAG by refraining from using the character ']' in originating command tags, since that character would force CMD-TAG to NIL.
INPROGRESS notifications MAY be sent for any IMAP command; the client MAY disregard them entirely or process them only in relation to specific commands.
If the server elects to send INPROGRESS notifications, it is RECOMMENDED that these are sent every 10-15 seconds.
IMAP servers that support this extension MUST include 'INPROGRESS' in the response list to the CAPABILITY command.
PROGRESS and GOAL SHOULD be counts of the kind of item being processed (usually message counts); if not possible, SHOULD be percentages with GOAL set to 100.
The client MUST assume PROGRESS to be 0 and GOAL to be unknown until the server issues a notification for the command.
The client MUST be prepared to handle cases where the server cannot keep GOAL constant and/or PROGRESS monotonically increasing.
The client MUST NOT consider PROGRESS or GOAL values authoritative for any purpose other than evaluating command progress; for example, GOAL must not be used to determine message counts in a folder.
The CMD-TAG field MUST be set to NIL if the tag is not available or if it contains the ']' character.
The GOAL number MUST be positive, MUST be greater than PROGRESS, SHOULD NOT change between successive notifications for the same command tag, and MUST be set to NIL if the goal is not known.
The INPROGRESS response code MUST NOT appear in a tagged response; it is only valid as an untagged OK reply while the command is still executing.
The PROGRESS number MUST be non-negative and SHOULD be monotonically increasing; if PROGRESS is not available, both PROGRESS and GOAL MUST be set to NIL.
The server SHOULD NOT send a progress notification where PROGRESS equals GOAL; in that case the proper tagged response should be emitted instead.
The INPROGRESS IMAP capability signals that the server emits progress notifications via the INPROGRESS response code. Clients discover this via the CAPABILITY command response.
The INPROGRESS response code is an untagged OK reply embedding an optional list of details: CMD-TAG (quoted string or NIL), PROGRESS (non-negative number or NIL), and GOAL (positive number or NIL). It signals command execution progress or serves as a keepalive.
IANA added 'INPROGRESS' to the 'IMAP Response Codes' registry and to the 'IMAP Capabilities' registry, both with a reference to RFC 9585.
The client must protect itself against data from a malicious server, specifically guarding against values causing arithmetic exceptions such as GOAL=0, GOAL/VALUE < 0, GOAL/VALUE >= 2^32, or VALUE > GOAL; in these cases the notification MUST be disregarded.
The INPROGRESS response code is not expected to disclose information beyond what is already available from command output, since progress details could be inferred by sending commands with different workloads.
The INPROGRESS resp-text-code is defined as: 'INPROGRESS' optionally followed by SP '(' inprogress-tag SP inprogress-state ')'. The inprogress-tag is a quoted string or NIL; inprogress-state is one of: NIL SP NIL (unknown), number SP NIL (counting), or number SP nz-number (known goal).