RFC 8970

IMAP4 Extension: Message Preview Generation

📅 published December 2020, from ietf

RFC 8970: IMAP4 Extension: Message Preview Generation 🎀

Okay bestie, this one is from the IETF (Internet Engineering Task Force) 🌈 It's by M. Slusarz at Open-Xchange Inc., dated December 2020, and it's a Standards Track doc with ISSN 2070-1721 💜

Abstract ✨

okay so this doc defines an IMAP (Internet Message Access Protocol) extension that lets a client ask the server to make a short text snippet of a message. The snippet is supposed to work as a preview of the whole message 💖

Status of This Memo 📝

This is an Internet Standards Track document 🦋

It's a product of the IETF, and it reflects the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). For more on Internet Standards, check Section 2 of RFC 7841 🫶

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8970 🔗

Copyright Notice ©️

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please read these carefully, because they explain your rights and restrictions for this document. Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 💅

Table of Contents 🗂️

1.  Introduction
2.  Conventions Used in This Document
3.  FETCH Data Item
  3.1.  Command
  3.2.  Response
  3.3.  Preview Text Format
4.  LAZY Priority Modifier
  4.1.  LAZY
  4.2.  Client Implementation Advice
5.  Examples
6.  Formal Syntax
7.  IANA Considerations
8.  Security Considerations
9.  References
  9.1.  Normative References
  9.2.  Informative References
Acknowledgments
Author's Address

1. Introduction 🧚

Lots of modern mail clients show small bits of the body text so a user can quickly decide if they care about the full message 👀 Mail clients using the Internet Message Access Protocol [RFC3501] would love a standardized, consistent way to make these little text previews.

Making the preview on the server is a whole vibe, for a few reasons 💅 First, it gives consistent previews across every client. Different clients might make pretty different preview text, but if the server makes the preview, people who use multiple clients get a more consistent experience 🎀

Second, server-side previews are more efficient 🔥 A client-based algorithm needs to send at least a FETCH BODYSTRUCTURE command, so it can figure out which MIME [RFC2045] body part(s) should be in the preview. After that, it may need at least one FETCH BODY command to grab the body data for the preview. These FETCH commands can't be pipelined, because the client has to parse the BODYSTRUCTURE answer before it knows which parts to ask for with BODY 😭

It's also hard to predict how much body data you need to grab to make a decent preview, so clients can end up fetching way too much data just to be safe 🙈 For example, a preview algorithm showing a text/html [RFC2854] part will probably strip the markup tags to get the actual text. But without fetching the whole part, there's no way to guarantee there's enough non-tag content, unless either 1) the whole part is retrieved, or 2) the client runs an extra partial FETCH when it finds it doesn't have enough data from the earlier partial FETCH to show a good preview.

Finally, server generation lets you cache in one central place 🌸 Server-generated previews get made once per message, globally, and can be cached for as long as the source message is kept. Pulling message data can be expensive on a server, so a server can be set up to lighten its storage load by pre-generating preview data ✨

A server shows it supports this extension with the "PREVIEW" capability name 🦋

2. Conventions Used in This Document 📚

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

"User" means a human user, and "client" means the software the user runs 🫶

In the examples, "C:" and "S:" mark lines sent by the client and the server. If one "C:" or "S:" label covers several lines, the line breaks between them are only there for editing clarity and aren't part of the actual protocol exchange 💜

As with every IMAP extension doc, the way IMAP protocol elements get written here is picked for editing clarity. Implementations must still pay attention to the numbered rules at the start of Section 9 of [RFC3501] 🧐

3. FETCH Data Item 🍓

3.1. Command 💌

To get a preview for a message, you use the PREVIEW FETCH attribute when you send a FETCH command, like this: PREVIEW 🎀

3.2. Response 🎁

The server sends back a variable-length string, which is the generated preview for that message. The string is meant to be read by the user as a contextual preview of the whole message, and the client software is not supposed to interpret it in any way 🙅‍♀️

Here's an example of retrieving preview info from a SELECTed mailbox:

C: A1 FETCH 1 (PREVIEW)
S: * 1 FETCH (PREVIEW "Preview text!")
S: A1 OK FETCH complete.

A server SHOULD strive to generate the same string for a given message on every request 💖 But previews are understood to be an approximation of the message data, not a canonical view of its contents. So a client MUST NOT assume a message preview is immutable for a given message 🙈 This relaxed requirement lets a server offer previews as an option, without needing storage or processing that's expensive enough to guarantee immutability for a use case that doesn't need that strictness. For example, the underlying IMAP server might change because of a system software upgrade. An account's state information might be kept through the migration, but the new server could generate different preview text than the old one did 🔄

Sometimes the server decides it can't make any meaningful preview text for a message. Examples include encrypted messages, content types the server doesn't support previews of, and other situations where the server can't extract information for a preview 😬 In those cases, the server MUST return a zero-length string. Clients SHOULD NOT send another FETCH for a preview of those messages. (Like we said before, preview data isn't immutable, so the server might be able to make meaningful text someday. But this is expected to be rare, so a client shouldn't keep spamming requests to catch that unlikely case 🥲)

If the LAZY modifier (Section 4.1) is used, the server MAY return NIL for the preview response. That means the preview couldn't be finished without causing undue delay 🐢 A server MUST NOT return NIL to a FETCH PREVIEW request made without the LAZY modifier 🚫

3.3. Preview Text Format 📏

The generated preview text MUST be treated as text/plain [RFC2046] media type data by the client 💅

The generated string MUST NOT be content transfer encoded, and MUST be encoded in UTF-8 [RFC3629]. The server SHOULD remove any formatting markup and do whatever processing might help render the preview as plain text ✨

For this section, a "preview character" is defined as a single Universal Character Set (UCS) character encoded in UTF-8. Heads up: a single preview character can be multiple octets, so any buffers built to meet the string limits in this doc should be sized to avoid possible overflow errors 🚨

The server SHOULD limit the preview text to 200 preview characters. That length should give enough data to generally support a lot of languages (with their different average word lengths) and different client display sizes 📱

The server MUST NOT output preview text longer than 256 preview characters 🛑

If the preview isn't generated from the body content of the message, and the server supports the LANGUAGE extension [RFC5255], the preview text SHOULD be generated using the language rules that apply to human-readable text. For example, a message made of a single image MIME part has no human-readable text to make a preview from. Instead, the server may want to output a description saying the message contains an image, and describe some attributes of the image, like image format, size, and filename 🖼️ This descriptive text isn't a product of the message body itself. It's auto-generated data from the server, so it should use the human-readable text rules described in the LANGUAGE extension (if the server supports it) 🧠

4. LAZY Priority Modifier ⚡

4.1. LAZY 🦥

The LAZY modifier tells the server to return the preview only if that data can come back without undue delay to the client ⏳

If this modifier is used and the server can't return preview data without undue delay, the server MUST return NIL as the preview response 💀

The LAZY modifier MUST be implemented by any server that supports the PREVIEW extension 👑

4.2. Client Implementation Advice 💅

Okay so, when a client opens a mailbox, it usually FETCHes message details (like ENVELOPE data) to build the listing the user sees 💌 With this extension, a client might also want to show preview text in that listing ✨ But the main goal is getting the basic listing back fast, because that's what lets the user actually start poking around the mailbox 🫶 Previews are kinda secondary. They give useful context, but you don't need them to do message actions 🦋 A client can load the missing previews in the background and show them asynchronously as the server hands them over 🧚

So the client adds the PREVIEW data item, with the LAZY modifier, to the list of FETCH items it needs for the mailbox listing 🎀 That lets the server return preview data when it can, without blocking the speedy return of the basic message details the listing is built from. Main character energy for the listing 👑

Once that initial FETCH is done, the client can send FETCH requests without the LAZY modifier to load the PREVIEW data item for the messages that didn't get one back. It is RECOMMENDED that these be sent in small batches, e.g., 50 messages per FETCH command 🍓 Preview generation can be expensive, and one giant request might blow past the server's resource limits 💀

See Example 2 in Section 5 for this strategy in action 🌸

A client SHOULD NOT keep spamming FETCH PREVIEW requests with the LAZY modifier in a selected mailbox 🙈 The server isn't required to return preview info for that command, so doing it over and over could waste system and network resources. Not it 🚫

5. Examples 🧚

Example 1: Requesting preview without LAZY modifier.

  C: A1 CAPABILITY
  S: * CAPABILITY IMAP4rev1 PREVIEW
  S: A1 OK Capability command completed.
  [...a mailbox is SELECTed...]
  C: A2 FETCH 1 (RFC822.SIZE PREVIEW)
  S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200}
  S: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue.
  S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla
  S: ligula nullam
  S: )
  S: A2 OK FETCH complete.

Example 2: Requesting preview with LAZY modifier, to obtain previews during initial mailbox listing if readily available; otherwise, load previews in background.

  C: B1 FETCH 1:4 (ENVELOPE PREVIEW (LAZY))
  S: * 1 FETCH (ENVELOPE ("Wed, 23 Sep 2020 15:03:11 +0000" [...])
     PREVIEW "Preview text for message 1.")
  S: * 2 FETCH (PREVIEW "" ENVELOPE
     ("Thu, 24 Sep 2020 12:17:23 +0000" [...]))
  S: * 3 FETCH (ENVELOPE ("Fri, 25 Sep 2020 09:13:45 +0000" [...])
     PREVIEW NIL)
  S: * 4 FETCH (ENVELOPE ("Sat, 26 Sep 2020 07:11:18 +0000" [...])
     PREVIEW NIL)
  S: B1 OK FETCH completed.
  [...Client has preview for message 1 and knows that message 2 has
      a preview that is empty; only need to request preview of
      messages 3 & 4 (e.g., in background)...]
  C: B2 FETCH 3:4 (PREVIEW)
  S: * 3 FETCH (PREVIEW {30}
  S: Message data from message 3.
  S: )
  S: * 4 FETCH (PREVIEW "Message 4 preview")
  S: B2 OK Fetch completed.

Example 3: Requesting preview for search results within a single mailbox. Use the SEARCHRES extension [RFC5182] to save a round-trip.

  C: C1 CAPABILITY
  S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES
  S: C1 OK Capability command completed.
  [...a mailbox is SELECTed...]
  C: C2 SEARCH RETURN (SAVE) FROM "FOO"
  C: C3 FETCH $ (UID PREVIEW (LAZY))
  S: C2 OK SEARCH completed.
  S: * 5 FETCH (UID 13 PREVIEW "Preview!")
  S: * 9 FETCH (UID 23 PREVIEW NIL)
  S: C3 OK FETCH completed.
  [...Retrieve message 9 preview in background...]
  C: C4 UID FETCH 23 (PREVIEW)
  S: * 9 FETCH (UID 23 PREVIEW "Another preview!")
  S: C4 OK FETCH completed.

6. Formal Syntax 💜

Okay so the syntax below is written in Augmented Backus-Naur Form (ABNF), as described in [RFC5234]. It also pulls in definitions from IMAP [RFC3501] 🧠

  capability        =/ "PREVIEW"

  fetch-att         =/ "PREVIEW" [SP "(" preview-mod *(SP
                       preview-mod) ")"]

  msg-att-dynamic   =/ "PREVIEW" SP nstring

  preview-mod       =  "LAZY"

7. IANA Considerations 🌸

IMAP [RFC3501] capabilities get registered by publishing a Standards Track or IESG-approved Experimental RFC in the "IMAP Capabilities" registry, which lives at <http://www.iana.org/assignments/imap-capabilities> 📋

IANA has added the "PREVIEW" capability to this registry ✅

8. Security Considerations 🔥

Okay, security time, and this one's a big deal 😭 Implementing this extension might enable denial-of-service attacks against server resources, because of excessive memory or CPU usage during preview generation, or increased storage usage if preview results get stored on the server after they're generated. To help mitigate these attacks, servers SHOULD log the client authentication identity on FETCH PREVIEW operations, so it's easier to track abusive clients 🚨

Servers MAY limit the resources that preview generation uses. In an extreme example, those resource limits might cause a server to return an empty-string preview for a message that would otherwise have had a non-empty one. It is recommended that at least some preview text still be provided in that situation, even if the quality of the preview is degraded 🥺

Just like the messages they summarize, preview data may contain sensitive information. If generated preview data is stored on the server, e.g., for caching purposes, these previews MUST be protected with equivalent authorization and confidentiality controls as the source message. No leaks, bestie 🔒

9. References 📚

9.1. Normative References

  [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
             Extensions (MIME) Part Two: Media Types", RFC 2046,
             DOI 10.17487/RFC2046, November 1996,
             <https://www.rfc-editor.org/info/rfc2046>.

  [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
             Requirement Levels", BCP 14, RFC 2119,
             DOI 10.17487/RFC2119, March 1997,
             <https://www.rfc-editor.org/info/rfc2119>.

  [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
             4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
             <https://www.rfc-editor.org/info/rfc3501>.

  [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
             10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
             2003, <https://www.rfc-editor.org/info/rfc3629>.

  [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
             Specifications: ABNF", STD 68, RFC 5234,
             DOI 10.17487/RFC5234, January 2008,
             <https://www.rfc-editor.org/info/rfc5234>.

  [RFC5255]  Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
             Message Access Protocol Internationalization", RFC 5255,
             DOI 10.17487/RFC5255, June 2008,
             <https://www.rfc-editor.org/info/rfc5255>.

  [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
             2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
             May 2017, <https://www.rfc-editor.org/info/rfc8174>.

9.2. Informative References

  [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
             Extensions (MIME) Part One: Format of Internet Message
             Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
             <https://www.rfc-editor.org/info/rfc2045>.

  [RFC2854]  Connolly, D. and L. Masinter, "The 'text/html' Media
             Type", RFC 2854, DOI 10.17487/RFC2854, June 2000,
             <https://www.rfc-editor.org/info/rfc2854>.

  [RFC5182]  Melnikov, A., "IMAP Extension for Referencing the Last
             SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March
             2008, <https://www.rfc-editor.org/info/rfc5182>.

Acknowledgments 🫶

The author would like to thank the following people for their comments and contributions to this document: Stephan Bosch, Bron Gondwana, Teemu Huovila, Neil Jenkins, Steffen Lehmann, Barry Leiba, Alexey Melnikov, Chris Newman, Pete Resnick, Jeff Sipek, Timo Sirainen, Steffen Templin, and Aki Tuomi. Thank you all, you're the real MVPs 🌈

Author's Address 🎀

  Michael M. Slusarz
  Open-Xchange Inc.
  530 Lytton Avenue
  Palo Alto, California 94301
  United States of America

  Email: michael.slusarz@open-xchange.com

📦 where this page comes from

ietf: rfc8970 2020-12
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms