RFC 9590

IMAP Extension for Returning Mailbox METADATA in Extended LIS

📅 published May 2024, from ietf

RFC 9590: IMAP Extension for Returning Mailbox METADATA in Extended LIST 💖

okay bestie, this one is from May 2024 and it's on the Standards Track 🎀 It's authored by Kenneth Murchison and Bron Gondwana, both at Fastmail 🦋 The ISSN is 2070-1721. The title block has no Obsoletes or Updates line, so it doesn't list anything it replaces or changes.

Here's the whole table of contents, verbatim so you can find your way around:

   1.  Introduction
   2.  Conventions Used in This Document
   3.  METADATA Return Option to LIST Command
   4.  Examples
   5.  Formal Syntax
   6.  Security Considerations
   7.  Privacy Considerations
   8.  IANA Considerations
     8.1.  Registration of IMAP Capability LIST-METADATA
     8.2.  Registration of LIST-EXTENDED Option METADATA
   9.  References
     9.1.  Normative References
     9.2.  Informative References
   Authors' Addresses

Abstract ✨

okay so this document adds an extension to the IMAP LIST command 🌸 It lets the client ask for mailbox annotations (metadata) in the same request, alongside the other stuff LIST already gives you. It's giving efficiency, no cap 💅

Status of This Memo 📋

This is an Internet Standards Track document 🎀

It's a product of the Internet Engineering Task Force (IETF) 🌈 It represents the consensus of the IETF community, has been through public review, and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 7841.

For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc9590 🦋

Copyright (c) 2024 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. Please review those documents carefully, because they describe your rights and restrictions for 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 they're provided without warranty as described in the Revised BSD License 😭

1. Introduction ✨

bestie, IMAP clients sometimes fetch mailbox metadata (for example, color) so they can make the mailbox list look nicer for the logged-in user 🌸 The annoying part is that the client has to send a LIST or LSUB command to get every mailbox, and then send a GETMETADATA command for each mailbox it found. So many round trips 🙈

This document defines an extension to the IMAP LIST command, advertised with the capability string LIST-METADATA 🧚 With it, the client can ask for annotations on the available mailboxes, along with the other info LIST normally returns. Main character energy for the LIST command 👑

2. Conventions Used in This Document 📚

In the examples, C: marks lines sent by a client connected to a server, and S: marks lines sent by the server to the client 💅

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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🫶

Long lines in examples are wrapped using "The Single Backslash Strategy" described in [RFC8792] ✨

3. METADATA Return Option to LIST Command 🎀

[RFC5464] defines the GETMETADATA command, which an IMAP client uses to retrieve mailbox annotations 🦋 Sometimes a client has to look up metadata for some or all of the mailboxes that LIST returned. Doing that with multiple GETMETADATA commands wastes bandwidth, and it can hurt performance if the client doesn't pipeline the requests 😭

So this document extends LIST with a new return option, "METADATA", which lets the client grab everything it wants in one command 🔥 For each listable mailbox that matches the list pattern and selection options, the server MUST return an untagged LIST response, followed by one or more untagged METADATA responses containing the mailbox annotations the client asked for. The untagged METADATA responses to an extended LIST command have the same syntax and semantics as the ones GETMETADATA would return for the same set of listable mailboxes (see Section 4.4.1 of [RFC5464]). As per Section 4.4 of [RFC5464], the server may return all the requested annotations in a single METADATA response per mailbox, or it may split them across multiple METADATA responses for each mailbox 🌈

If the server can't look up the annotations for a given mailbox, it MAY drop the corresponding METADATA response 🙈 In that case, the LIST command still gets a tagged OK reply. Not the vibe we wanted, but it's still a success 💖

4. Examples 🍓

These examples fetch metadata from only the top-level hierarchy of the mailbox, using different selection criteria (see Section 6.3.9 of [RFC9051]) ✨

In this example:

  • The "color" annotation for the "foo" mailbox hasn't been set, so the METADATA response has a value of "NIL" (i.e., it has no value) 🌸
  • "bar" has children but isn't an actual mailbox itself, so it gets no METADATA response 🙈
NOTE: '' line wrapping per RFC 8792
  C: A00 CAPABILITY
  S: * CAPABILITY IMAP4rev1 IMAP4rev2 \
                  LIST-EXTENDED LIST-METADATA METADATA
  S: A00 OK Completed.
  C: A01 LIST "" % \
              RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
  S: * LIST () "." "INBOX"
  S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
  S: * LIST () "." "foo"
  S: * METADATA "foo" ("/shared/vendor/cmu/cyrus-imapd/color" NIL)
  S: * LIST (\NonExistent) "." "bar"
  S: A01 OK List completed.

In this one, the LIST response for "foo" comes back because it has matching children 🧚 But there's no METADATA response for "foo" itself, since "foo" doesn't match the selection criteria 💅

NOTE: '' line wrapping per RFC 8792
  C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" % \
              RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
  S: * LIST (\Subscribed) "." "INBOX"
  S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
  S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED"))
  S: A02 OK List completed.

5. Formal Syntax 📐

The grammar below uses the Augmented Backus-Naur Form (ABNF) described in [RFC5234]. "return-option" is defined in [RFC5258], and "entry" is defined in [RFC5464] 🎀

   return-option =/ "METADATA" SP "(" entry *(SP entry) ")"

6. Security Considerations 🔐

This specification doesn't introduce any security concerns beyond the ones described in [RFC5258] and [RFC5464] 😭🔐

7. Privacy Considerations 🫣

This specification doesn't introduce any privacy concerns beyond the ones described in [RFC5464] 🫶

8. IANA Considerations 🗂️

8.1. Registration of IMAP Capability LIST-METADATA

IANA has added the "LIST-METADATA" IMAP capability to the "IMAP Capabilities" registry, located at <https://www.iana.org/assignments/imap4-capabilities/> 🌸

8.2. Registration of LIST-EXTENDED Option METADATA

IANA has registered the "METADATA" LIST-EXTENDED option in the "LIST-EXTENDED options" registry, located at <https://www.iana.org/assignments/imap-list-extended/> 💜 The registration looks like this:

   LIST-EXTENDED option name:
      METADATA

   LIST-EXTENDED option type:
      RETURN

   LIST-EXTENDED option description:
      Causes the LIST command to return METADATA responses in addition
      to LIST responses.

   Published specification:
      RFC 9590, Section 3

   Security considerations:
      RFC 9590, Section 6

   Intended usage:
      COMMON

   Person and email address to contact for further information:
      Kenneth Murchison <murch@fastmailteam.com> and
      Bron Gondwana <brong@fastmailteam.com>

   Owner/Change controller:
      IESG <iesg@ietf.org>

9. References 📚

9.1. Normative References

9.2. Informative References

Authors' Addresses 📮

   Kenneth Murchison
   Fastmail US LLC
   1429 Walnut Street
   Suite 1201
   Philadelphia, PA 19102
   United States of America
   Email: murch@fastmailteam.com


   Bron Gondwana
   Fastmail Pty Ltd
   Level 2, 114 William Street
   Melbourne VIC 3000
   Australia
   Email: brong@fastmailteam.com
📦 where this page comes from