JMAP Undelete: Recovering Destroyed Objects

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 30 April 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. 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 [RFC8620]. 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 [IANA-JMAP] can take part. This document gives specific rules for Email [RFC8621], ContactCard [RFC9610], CalendarEvent [I-D.ietf-jmap-calendars], FileNode [I-D.ietf-jmap-filenode], and SieveScript [RFC9661].¶

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 Section 8.¶

2. 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" (Section 2.5 of [RFC8621]).¶

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

3. 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 [RFC9670].¶

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 Section 3.6).¶

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 Section 3.2, 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 Section 3.1 where the object had them, and MAY include others. The "id" property is not included, because it is given by "objectId".¶

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

5. 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 [RFC9425] 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.¶

6. 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" ]]

7. Security Considerations

All security considerations of JMAP [RFC8620] 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 Section 3.3 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 (Section 3.9.3).¶

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

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

9. IANA Considerations

10. Implementation Status

This section is to be removed before publishing as an RFC.¶

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 [RFC7942].¶

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

Appendix A. Open Issues

This section is to be removed before publishing as an RFC.¶

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

Author's Address