Coffey Labs LLC

Arizona United States of America john@coffeylabs.org https://coffeylabs.org

Applications and Real-Time Network Working Group JMAP undelete retention recovery This document specifies an extension to the JSON Meta Application Protocol (JMAP) that lets a client find and restore objects that were permanently destroyed within a server-defined retention period. It defines a new capability, a DeletedItem data type that describes a destroyed object of any supported data type, and a DeletedItem/restore method that recreates it. Rules are given for Email, ContactCard, CalendarEvent, FileNode, and SieveScript objects. Servers can already keep destroyed data for a time. This extension gives clients an interoperable way to show what can be recovered, for how long, and to recover it. About This Document Discussion of this document takes place on the JMAP Working Group mailing list (jmap@ietf.org).

Introduction Deleting data by mistake is common. A user empties the Trash mailbox, a filter removes the wrong messages, a client expunges a folder, or a synchronisation error destroys contacts or calendar events. Many servers keep destroyed data for some time so that an administrator can recover it, but there is no standard way for a client to see what is recoverable or to recover it. Each server that offers recovery to end users does so through its own interface. This document defines that interface for JMAP . When a server supports it, destroying an object of a supported data type leaves behind a DeletedItem record for a retention period. The DeletedItem describes the destroyed object, gives access to its content as a blob, and can be restored with the DeletedItem/restore method, which recreates the object in its original place where that is still possible. When the retention period ends, or when the user purges the DeletedItem, the object is gone for good. The extension is generic: any data type registered in the "JMAP Data Types" registry can take part. This document gives specific rules for Email , ContactCard , CalendarEvent , FileNode , and SieveScript . This extension is about mistakes. It is not a backup mechanism, since it does not protect against loss of the server, and it is not a legal hold, since a user can purge their own deleted items. See .

Notational Conventions 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 when, and only when, they appear in all capitals, as shown here. Type signatures, examples, and property descriptions in this document follow the conventions established in . Data types defined in the core specification are also used in this document.

Terminology

Destroy:

To remove an object from an account permanently, so that it no longer appears in that data type's /get or /query results. This includes a JMAP /set destroy and removals made through any other protocol, such as an IMAP EXPUNGE. Moving an object to a mailbox, calendar, or folder with a "trash" role is not destroying it.

Deleted item:

The record that a server keeps of a destroyed object, as described by a DeletedItem object ().

Container:

The object or objects that hold an object of a given data type: Mailboxes for an Email, AddressBooks for a ContactCard, Calendars for a CalendarEvent, the parent FileNode for a FileNode. A SieveScript has no container.

Retention period:

The length of time for which a deleted item stays restorable.

Purge:

To destroy a deleted item before its retention period ends.

Addition to the Capabilities Object The capability "urn:ietf:params:jmap:undelete" is added to the Session object's "capabilities" property. Its value in the "capabilities" property of the Session object is an empty object. An account supports this extension if this capability is present in the account's "accountCapabilities" property. Its value there is an object with the following properties:

objectTypes: String[]

The names of the data types for which this account keeps deleted items, from the "JMAP Data Types" registry or defined by a private extension. The list MUST NOT be empty. A data type appears here only if the server keeps deleted items for it at the time the Session object is fetched.

retentionPeriod: UnsignedInt|null

The number of seconds a newly destroyed object stays restorable, or null if the server does not keep deleted items for a fixed time (for example, because the period depends on the object). Clients use this to tell the user how long they have to change their mind. The "expiresAt" property of each DeletedItem is authoritative.

mayPurge: Boolean

Whether the user may purge deleted items in this account with DeletedItem/set ().

Keeping Deleted Items While an account advertises this capability, a server MUST create a DeletedItem whenever an object of a data type listed in "objectTypes" is destroyed in that account, whatever protocol or process destroyed it. This includes, for example, an Email destroyed with Email/set, expunged over IMAP, deleted over POP3, removed by the automatic emptying of a Trash mailbox, or destroyed because its only Mailbox was destroyed with "onDestroyRemoveEmails" (). A server MUST NOT create a DeletedItem:

• for an object that never existed in the account, such as a message rejected before delivery;
• when a DeletedItem is itself purged or expires; or
• when an object is moved between accounts with a /copy method that has "onSuccessDestroyOriginal" set to true, because the object still exists in the destination account.

Modifying an object, including removing it from some but not all of its containers, does not create a DeletedItem. This extension recovers destroyed objects. It does not recover earlier versions of objects that still exist. When an account stops advertising a data type in "objectTypes", or stops advertising the capability, deleted items already kept SHOULD remain restorable until their own "expiresAt" time. A server MUST NOT shorten the "expiresAt" of an existing DeletedItem because its retention settings changed. A user who was told that an object could be recovered until a given time should be able to rely on it.

DeletedItem A DeletedItem object describes one destroyed object. It has the following properties:

id: Id (immutable; server-set)

The id of the DeletedItem.

objectType: String (immutable; server-set)

The name of the data type of the destroyed object, as registered in the "JMAP Data Types" registry, for example, "Email". The naming follows the ShareNotification object of .

objectId: Id (immutable; server-set)

The id the destroyed object had. Clients can use this to offer "undo" for an object they have just destroyed (see ).

deletedAt: UTCDate (immutable; server-set)

When the object was destroyed.

expiresAt: UTCDate|null (immutable; server-set)

When the deleted item stops being restorable, or null if the server keeps it until it is purged. After this time the server MUST NOT restore it.

size: UnsignedInt (immutable; server-set)

The size, in octets, of the blob referenced by "blobId".

blobId: Id|null (immutable; server-set)

The id of a blob holding the destroyed object's content in the representation given in , or null if the server does not offer one for this data type. The blob can be downloaded without restoring the object, for example to preview it.

snapshot: Object (immutable; server-set)

Some of the destroyed object's properties as they were when it was destroyed, with the names and values the object's own /get method would have returned. The server MUST include the properties listed for the data type in where the object had them, and MAY include others. The "id" property is not included, because it is given by "objectId".

Snapshot Properties The following properties MUST appear in "snapshot" for the data types defined so far. They give a client enough to show a useful list ("what was it, and where was it") without restoring anything. Required Snapshot Properties

objectType	Properties
Email	mailboxIds, keywords, receivedAt, size, subject, from, preview
ContactCard	addressBookIds, name, kind
CalendarEvent	calendarIds, title, start, duration, timeZone
FileNode	parentId, name, type, size
SieveScript	name, isActive

A specification that adds a data type to this extension SHOULD list its required snapshot properties in the same way.

Blob Representations When "blobId" is not null, the blob holds the destroyed object in the following representation: Deleted Item Blob Representations

objectType	Representation
Email	The message as stored, as the Email's own "blobId" referenced it (message/rfc822)
ContactCard	The JSContact Card (application/jscontact+json)
CalendarEvent	The JSCalendar Event (application/jscalendar+json)
FileNode	The file's content, as the FileNode's own "blobId" referenced it; a FileNode with no content (a folder) has null
SieveScript	The script, as the SieveScript's own "blobId" referenced it (application/sieve)

A server MAY return the same blobId the destroyed object had. The blob MUST remain downloadable for as long as the DeletedItem exists.

Access in Shared Accounts In an account the user owns, every DeletedItem is visible to them. In an account shared with the user , a DeletedItem MUST be visible only if, when the object was destroyed, the user had the right to read it in at least one of its containers. A server MAY limit visibility further, for example to the account's owner only. A DeletedItem that is not visible to the user MUST be treated as if it did not exist by every method in this document.

DeletedItem/get This is a standard "/get" method as described in . A DeletedItem past its "expiresAt" time MUST be returned in "notFound", even if the server has not yet removed it.

DeletedItem/changes This is a standard "/changes" method as described in . A DeletedItem that is restored, purged, or expires is reported as destroyed. Since DeletedItem objects are immutable, they are never reported as updated.

DeletedItem/query This is a standard "/query" method as described in . A FilterCondition object has the following properties, any of which may be omitted:

objectType: String

The "objectType" property must be equal to this.

objectIds: Id[]

The "objectId" property must be in this list.

deletedBefore: UTCDate

The "deletedAt" property must be before this date-time.

deletedAfter: UTCDate

The "deletedAt" property must be the same as or after this date-time.

inContainer: Id

The destroyed object must have been in this container: its snapshot's "mailboxIds", "addressBookIds", or "calendarIds" must contain this id, or its "parentId" must equal it. The container does not have to exist any more.

text: String

Looks for the text in the string values of the snapshot. For an Email, this includes the subject and the names and addresses of the "from" property. A server MAY also search the content of the blob.

If more than one property is given, the deleted item must match all of them. The following values for the "property" field of a Comparator object MUST be supported for sorting:

• "deletedAt"
• "expiresAt"
• "size"

If no sort is given, the results are sorted by "deletedAt", newest first.

DeletedItem/queryChanges This is a standard "/queryChanges" method as described in .

DeletedItem/set This is a standard "/set" method as described in , used only to purge deleted items. DeletedItem objects cannot be created or updated with this method: the server MUST reject every create and every update with a "forbidden" SetError. Destroying a DeletedItem purges it. The server MUST then make the object unrecoverable through this extension and MUST release the blob as for any destroyed object. If the account's "mayPurge" is false, or the user does not have the right to remove the object from the containers it was in, the server MUST reject the destroy with a "forbidden" SetError.

DeletedItem/restore This method recreates the objects described by one or more DeletedItems. It takes the following arguments:

accountId: Id

The id of the account to use.

ids: Id[]

The ids of the DeletedItems to restore. The number of ids MUST NOT exceed the "maxObjectsInSet" limit of the core capability.

ifInState: String|null

As for /set (), against the DeletedItem state.

The response has the following arguments:

accountId: Id

The id of the account used for the call.

oldState: String|null

The DeletedItem state before the call.

newState: String

The DeletedItem state after the call.

restored: Id[Object]|null

A map from the id of each DeletedItem that was restored to an object with two properties: "objectType", the data type of the object, and "object", an object holding the "id" of the recreated object and any other properties whose values differ from the snapshot (for example, the containers it was restored to, or a new name). This is null if nothing was restored.

notRestored: Id[SetError]|null

A map from the id of each DeletedItem that could not be restored to a SetError, or null if there were none.

The following SetError types may be returned in "notRestored":

• "notFound": The DeletedItem does not exist, is not visible to the user, or is past its "expiresAt" time.
• "forbidden": The user may not create the object in any container it could be restored to.
• "overQuota": Restoring the object would take the account past a quota.
• "tooLarge": The object is larger than the server now accepts for that data type.

Restoring is atomic for each DeletedItem: either the object is recreated and the DeletedItem is removed, or neither happens. If the same id appears more than once in "ids", or a restore of the same DeletedItem is already in progress, the object is restored once. A restored object is a new object of its data type, created by the server. It gets a new id, which may or may not equal "objectId". The data type's state changes as for any created object, so clients learn about it through the usual /changes calls and push notifications. A client MUST NOT assume that the restored object has its old id. A restored object MUST have the property values in its snapshot, and the server SHOULD restore the other properties it had, except where the following sections say otherwise. Server-set properties (such as an Email's "threadId") are set as for a new object.

Containers An object is restored to the containers it was in when it was destroyed, leaving out any that no longer exist or that the user may not add objects to. If none remain, it is restored to the default container for its type:

• Email: the Mailbox with the "inbox" role.
• ContactCard: the AddressBook with "isDefault" true.
• CalendarEvent: the Calendar with "isDefault" true.
• FileNode: the root of the file tree.

If the user may not add objects to the default container either, the restore fails with "forbidden". An Email that was only in the Mailbox with the "trash" role when it was destroyed is restored there. An Email that was in the Trash and other Mailboxes is restored to the other Mailboxes only. This follows what the user most likely intends: the message was emptied from the Trash, or deleted from a folder it was filed in.

Email A restored Email MUST have the "keywords" it had when destroyed, including "$seen", and the same "receivedAt". It joins a thread according to the server's normal threading rules, so it will usually rejoin its earlier conversation. A restored Email is not new mail: the server MUST NOT run delivery-time processing (such as Sieve scripts, spam filtering, or vacation responses) on it.

FileNode and SieveScript If a FileNode's name is already in use in the folder it is restored to, or a SieveScript's name is already in use, the server MUST choose a new name for the restored object and report it in the "object" of the "restored" entry. How the new name is formed is up to the server. A folder FileNode is restored without its content. Its children that were destroyed with it have DeletedItems of their own, and a client restores them by restoring each one, parents first. A client can find them with the "inContainer" filter. A restored SieveScript MUST NOT be active, even if it was active when destroyed. Activating a script changes how incoming mail is handled, so the user must do it on purpose.

Expiry When a DeletedItem's "expiresAt" time passes, the server MUST stop offering it through every method in this document at once, and SHOULD destroy it and release its blob soon after. It is reported as destroyed by DeletedItem/changes no later than the next state change after its expiry.

Quotas A server decides whether deleted items count toward an account's quotas. Counting them is NOT RECOMMENDED, since a user who deletes data to free space would otherwise gain nothing until the retention period ends. A server that does count them and supports JMAP Quotas SHOULD include "DeletedItem" in the "types" of each Quota they count toward. A restored object counts toward quotas as a new object would, whether or not the DeletedItem did.

Examples A client shows a "Recently deleted" view of email: [[ "DeletedItem/query", { "accountId": "u1", "filter": { "objectType": "Email" }, "sort": [{ "property": "deletedAt", "isAscending": false }], "limit": 50 }, "0" ], [ "DeletedItem/get", { "accountId": "u1", "#ids": { "resultOf": "0", "name": "DeletedItem/query", "path": "/ids" } }, "1" ]] The server responds: [[ "DeletedItem/query", { "accountId": "u1", "queryState": "q73", "canCalculateChanges": true, "position": 0, "ids": [ "d42" ] }, "0" ], [ "DeletedItem/get", { "accountId": "u1", "state": "s9", "list": [{ "id": "d42", "objectType": "Email", "objectId": "M8f2", "deletedAt": "2026-10-26T18:03:11Z", "expiresAt": "2026-11-25T18:03:11Z", "size": 48211, "blobId": "G3a91", "snapshot": { "mailboxIds": { "mb-inbox": true, "mb-invoices": true }, "keywords": { "$seen": true, "$flagged": true }, "receivedAt": "2026-10-20T09:15:00Z", "size": 48211, "subject": "Invoice 2026-118", "from": [{ "name": "Accounts", "email": "accounts@example.com" }], "preview": "Please find attached the invoice for October..." } }], "notFound": [] }, "1" ]] The user restores it. The "invoices" Mailbox has since been destroyed, so the message goes back to the Inbox only: [[ "DeletedItem/restore", { "accountId": "u1", "ids": [ "d42" ] }, "0" ]] [[ "DeletedItem/restore", { "accountId": "u1", "oldState": "s9", "newState": "s10", "restored": { "d42": { "objectType": "Email", "object": { "id": "M9c07", "mailboxIds": { "mb-inbox": true } } } }, "notRestored": null }, "0" ]] A client that has just destroyed an Email with id "M8f2" offers "Undo" by looking up its DeletedItem: [[ "DeletedItem/query", { "accountId": "u1", "filter": { "objectIds": [ "M8f2" ] } }, "0" ]]

Security Considerations All security considerations of JMAP and of the specifications defining each supported data type apply. Deleted items extend the time for which data stays reachable through the account. Anyone who gains access to an account, through stolen credentials or a delegated session, can read recently destroyed data as well as current data. Deleting something sensitive does not protect it from such a person until it has been purged. Clients SHOULD make purging easy to find. In shared accounts, deleted items can disclose what another user deleted and when. The visibility rule in limits this to people who could already read the object. A server that cannot track this reliably SHOULD show deleted items only to the account's owner. Restoring an object recreates content that may have been destroyed because it was harmful, such as a phishing message removed by an administrator or by a filter. Servers MAY refuse to keep deleted items for objects removed for such reasons, and MAY refuse to restore them with "forbidden". Restoring a SieveScript must not change how incoming mail is handled without the user's deliberate action. This is why a restored script is always inactive (). DeletedItem/restore can create many objects in one call. Servers apply the "maxObjectsInSet" limit and their normal rate limits to it, as they would to /set.

Privacy Considerations Users expect deletion to remove data. Keeping deleted data, even for a short time, has to be visible to the user and under their control. This extension does both: "retentionPeriod" and "expiresAt" say how long data is kept, and DeletedItem/set lets the user purge it at once when "mayPurge" is true. Servers SHOULD set "mayPurge" to true for the account's owner, so that a user can make a deletion final. Operators may have legal or contractual reasons to keep data longer than the user can see it, such as a litigation hold. Such retention is outside the scope of this extension. A server that keeps data after a purge or after expiry MUST NOT offer it through this extension, and operators are expected to tell users of such policies through other means. The "snapshot" and the blob hold the same personal data as the destroyed object. Data protection rules that apply to the object apply equally to them.

IANA Considerations

JMAP Capability Registration for "undelete" IANA is requested to register the "undelete" JMAP Capability as follows:

Capability Name:

urn:ietf:params:jmap:undelete

Specification document:

this document

Intended use:

common

Change Controller:

IETF

Security and privacy considerations:

this document, and

JMAP Data Type Registration for "DeletedItem" IANA is requested to register "DeletedItem" in the "JMAP Data Types" registry as follows:

Type Name:

DeletedItem

Can Reference Blobs:

Yes

Can Use for State Change:

Yes

Capability:

urn:ietf:params:jmap:undelete

Reference:

this document

Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . inbuxa server, an open-source (AGPL-3.0) mail and collaboration server from Coffey Labs, keeps and restores deleted Email, ContactCard, CalendarEvent, FileNode, and SieveScript objects with the restoration rules described here, through its own interface. The JMAP interface in this document is not implemented yet. An implementation is planned.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document specifies a protocol for clients to efficiently query, fetch, and modify JSON-based data objects, with support for push notification of changes and fast resynchronisation and for out-of- band binary data upload/download. This document specifies a data model for synchronising email data with a server using the JSON Meta Application Protocol (JMAP). Clients can use this to efficiently search, access, organise, and send messages, and to get push notifications for fast resynchronisation when new messages are delivered or a change is made in another client. This document specifies a data model for synchronising contact data with a server using the JSON Meta Application Protocol (JMAP). This document specifies a data model for managing Sieve scripts on a server using the JSON Meta Application Protocol (JMAP). Clients can use this protocol to efficiently search, access, organize, and validate Sieve scripts. This document specifies a data model for sharing data between users using the JSON Meta Application Protocol (JMAP). Future documents can reference this document when defining data types to support a consistent model of sharing. This specification defines a data model and JavaScript Object Notation (JSON) representation of contact card information that can be used for data storage and exchange in address book or directory applications. It aims to be an alternative to the vCard data format and to be unambiguous, extendable, and simple to process. In contrast to the JSON-based jCard format, it is not a direct mapping from the vCard data model and expands semantics where appropriate. Two additional specifications define new vCard elements and how to convert between JSContact and vCard. This specification defines a data model and JSON representation of calendar data that can be used for storage and data exchange in a calendaring and scheduling environment. It aims to be an alternative and, over time, successor to the widely deployed iCalendar data format. It also aims to be unambiguous, extendable, and simple to process. In contrast to the jCal format, which is also based on JSON, JSCalendar is not a direct mapping from iCalendar but defines the data model independently and expands semantics where appropriate. Fastmail Spherical Cow Group This document specifies a data model for synchronizing calendar data with a server using JMAP. Clients can use this to efficiently read, write, and share calendars and events, receive push notifications for changes or event reminders, and keep track of changes made by others in a multi-user environment. The JMAP base protocol (RFC 8620) provides the ability to upload and download arbitrary binary data. This binary data is called a "blob", and can be used in all other JMAP extensions. This extension adds a FileNode data type and methods to expose blobs as a filesystem, along with the types of metadata that are provided by other remote filesystem protocols. Informative References This document describes a language for filtering email messages at time of final delivery. It is designed to be implementable on either a mail client or mail server. It is meant to be extensible, simple, and independent of access protocol, mail architecture, and operating system. It is suitable for running on a mail server where users may not be allowed to execute arbitrary programs, such as on black box Internet Message Access Protocol (IMAP) servers, as the base language has no variables, loops, or ability to shell out to external programs. [STANDARDS-TRACK] This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice. The Internet Message Access Protocol Version 4rev2 (IMAP4rev2) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev2 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev2 also provides the capability for an offline client to resynchronize with the server. IMAP4rev2 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; removing messages permanently; setting and clearing flags; parsing per RFCs 5322, 2045, and 2231; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev2 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev2 does not specify a means of posting mail; this function is handled by a mail submission protocol such as the one specified in RFC 6409. This document specifies a data model for handling quotas on accounts with a server using the JSON Meta Application Protocol (JMAP). IANA

Open Issues

• Should a restored object keep its old id when the server can guarantee it was never reused? Keeping it helps clients that cached the object; a new id is simpler and matches what clients already handle for created objects.
• Destroyed containers (Mailbox, AddressBook, Calendar) are not recoverable here; only their contents are. Is container recovery needed, or is restoring contents to the default container enough?
• Restoring large FileNode trees may need an asynchronous form, or a "restore with children" option.
• Should a /set destroy response optionally return the ids of the DeletedItems it created, to save the "Undo" lookup?
• Whether an IMAP or WebDAV counterpart is wanted, or JMAP alone is enough.