IMAP REPLACE Extension
Extracted elements (24)
Quota implications of the APPEND portion of REPLACE are evaluated within the context of the pending EXPUNGE, so that only the net quota consumption is considered. This avoids the failure mode of the legacy APPEND/STORE/EXPUNGE sequence where APPEND could fail due to an over-quota condition even though the subsequent expunge would free sufficient space.
REPLACE requires the selected state (unlike APPEND, which is valid in the authenticated state) because it operates on message sequence numbers. The UID variant likewise does not support use from the authenticated state, following the convention for UID commands in RFC 3501 Section 6.4.8.
Server developers are encouraged to implement REPLACE as an atomic operation to simplify error handling, minimize operational concerns, and reduce potential security problems. For systems where atomicity is not possible, communication with the requesting client must ensure no confusion of message store state.
Similar to MOVE (RFC 6851), REPLACE ensures that intermediate states — such as a message flagged \Deleted before expunge — do not occur and are not visible to other clients or Sieve scripts. The response codes for APPEND and EXPUNGE are returned, but the STORE response code is suppressed.
The REPLACE extension explicitly has no interaction with MULTIAPPEND (RFC 3502) and does not define a method for replacing multiple messages concurrently, keeping the semantics simple and focused on the single-message replacement use case.
The REPLACE extension intentionally does not require the target mailbox to match the selected mailbox, enabling use cases such as moving a finalized draft directly to \Sent by replacing a \Drafts message with submission to a different special-use mailbox.
UIDPLUS implementations are advised to send APPENDUID in an untagged OK before EXPUNGE responses rather than in the tagged OK. Sending APPENDUID in the tagged OK causes the client to receive EXPUNGE for the old message before learning the UID of the new message, which is unnecessarily difficult to process usefully.
REPLACE applies to IMAP Events in Sieve (RFC 6785) the same way APPEND does: it can cause a Sieve script to be invoked with imap.cause set to "APPEND". Because the intermediate STORE +FLAGS.SILENT \DELETED state is not exposed, no action will result in an imap.cause of FLAG.
The ACL rights required for UID REPLACE are the union of the ACL rights required for UID STORE and UID EXPUNGE in the current mailbox, and APPEND in the target mailbox.
A server MUST NOT generate a response code for the STORE +flags \DELETED portion of the implicit REPLACE sequence. The intermediate store state must remain invisible to clients.
Implementations MUST accept the REPLACE capability string and command tokens in a case-insensitive fashion, consistent with general IMAP conventions.
REPLACE and UID REPLACE MUST only be valid in the selected state. Unlike APPEND, which is valid in the authenticated state, REPLACE operates on message sequence numbers and therefore requires a selected mailbox.
Servers implementing both REPLACE and CONDSTORE/QRESYNC (RFC 7162) MUST treat the message being replaced as if it were being removed with a UID EXPUNGE command, per Sections 3.2.9 and 3.2.10 of RFC 7162.
Servers implementing both REPLACE and OBJECTID (RFC 8474) MUST return different EMAILIDs for the replaced and replacing messages, unless the server detects that both messages' immutable content is identical per Section 5.1 of RFC 8474.
Servers supporting both REPLACE and CATENATE (RFC 4469) MUST support the additional append-data and resp-text-code elements defined in Section 5 of RFC 4469 in conjunction with the REPLACE command.
Servers supporting both REPLACE and UIDPLUS (RFC 4315) SHOULD send APPENDUID in response to a UID REPLACE command, and are advised to send the APPENDUID response code in an untagged OK before sending EXPUNGE or replaced responses.
Servers supporting REPLACE MUST NOT infer any inheritance of content, flags, or annotations from the message being replaced; the replacement message stands entirely on its own.
When an error occurs while processing REPLACE or UID REPLACE, the server MUST NOT leave the selected mailbox in an inconsistent state; any untagged EXPUNGE response MUST NOT be sent until all actions are successfully completed.
Servers that implement the REPLACE extension advertise support by returning the string "REPLACE" in the CAPABILITY command response.
The REPLACE command takes five arguments: a message sequence number, a named mailbox, an optional flag list, an optional date/time string, and a message literal. The new message is appended to the named mailbox and the identified message is removed from the selected mailbox, appearing to the client as a single action.
UID REPLACE extends the UID command to accept REPLACE as a valid argument, using a UID rather than a sequence number as its first parameter. It is otherwise semantically identical to REPLACE.
IANA has added "REPLACE" to the IMAP Capabilities registry at https://www.iana.org/assignments/imap-capabilities.
The REPLACE command is believed to add no security problems beyond those of the base IMAP specification. It may actually prevent some potential security problems because it avoids the intermediate message states (message temporarily flagged \Deleted but not yet expunged) that could be exploited by an attacker observing or interacting with the mailbox.
The ABNF grammar adds 'REPLACE' to the capability production, defines 'replace' as 'REPLACE SP seq-number SP mailbox append-message', and extends 'uid' with 'UID SP replace'. The 'append-message' non-terminal is inherited from RFC 4466.