5Internet Engineering Task Force (IETF) M. Slusarz
6Request for Comments: 8970 Open-Xchange Inc.
7Category: Standards Track December 2020
11 IMAP4 Extension: Message Preview Generation
15 This document specifies an Internet Message Access Protocol (IMAP)
16 protocol extension that allows a client to request a server-generated
17 abbreviated text representation of message data that is useful as a
18 contextual preview of the entire message.
22 This is an Internet Standards Track document.
24 This document is a product of the Internet Engineering Task Force
25 (IETF). It represents the consensus of the IETF community. It has
26 received public review and has been approved for publication by the
27 Internet Engineering Steering Group (IESG). Further information on
28 Internet Standards is available in Section 2 of RFC 7841.
30 Information about the current status of this document, any errata,
31 and how to provide feedback on it may be obtained at
32 https://www.rfc-editor.org/info/rfc8970.
36 Copyright (c) 2020 IETF Trust and the persons identified as the
37 document authors. All rights reserved.
39 This document is subject to BCP 78 and the IETF Trust's Legal
40 Provisions Relating to IETF Documents
41 (https://trustee.ietf.org/license-info) in effect on the date of
42 publication of this document. Please review these documents
43 carefully, as they describe your rights and restrictions with respect
44 to this document. Code Components extracted from this document must
45 include Simplified BSD License text as described in Section 4.e of
46 the Trust Legal Provisions and are provided without warranty as
47 described in the Simplified BSD License.
52 2. Conventions Used in This Document
56 3.3. Preview Text Format
57 4. LAZY Priority Modifier
59 4.2. Client Implementation Advice
62 7. IANA Considerations
63 8. Security Considerations
65 9.1. Normative References
66 9.2. Informative References
72 Many modern mail clients display small extracts of the body text as
73 an aid to allow a user to quickly decide whether they are interested
74 in viewing the full message contents. Mail clients implementing the
75 Internet Message Access Protocol [RFC3501] would benefit from a
76 standardized, consistent way to generate these brief textual previews
79 Generation of a preview on the server has several benefits. First,
80 it allows consistent representation of previews across all clients.
81 While different clients might generate quite different preview text,
82 having common preview text generated by the server can give a more
83 consistent user experience to those who use multiple clients.
85 Second, server-side preview generation is more efficient. A client-
86 based algorithm needs to issue, at a minimum, a FETCH BODYSTRUCTURE
87 command in order to determine which MIME [RFC2045] body part(s)
88 should be represented in the preview. Subsequently, at least one
89 FETCH BODY command may be needed to retrieve body data used in
90 preview generation. These FETCH commands cannot be pipelined since
91 the BODYSTRUCTURE query must be parsed on the client before the list
92 of parts to be retrieved via the BODY command(s) can be determined.
94 Additionally, it may be difficult to predict the amount of body data
95 that must be retrieved to adequately represent the part via a
96 preview, therefore requiring inefficient fetching of excessive data
97 in order to account for this uncertainty. For example, a preview
98 algorithm to display data contained in a text/html [RFC2854] part
99 will likely strip the markup tags to obtain textual content.
100 However, without fetching the entire content of the part, there is no
101 way to guarantee that sufficient non-tag content will exist unless
102 either 1) the entire part is retrieved or 2) an additional partial
103 FETCH is executed when the client determines that it does not possess
104 sufficient data from a previous partial FETCH to display an adequate
105 representation of the preview.
107 Finally, server generation allows caching in a centralized location.
108 Using server-generated previews allows global generation once per
109 message, and that preview can be cached for the retention period of
110 the source message. Retrieval of message data may be expensive
111 within a server, for example, so a server can be configured to reduce
112 its storage retrieval load by pre-generating preview data.
114 A server indicates support for this extension via the "PREVIEW"
1172. Conventions Used in This Document
119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
121 "OPTIONAL" in this document are to be interpreted as described in
122 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
123 capitals, as shown here.
125 "User" is used to refer to a human user, whereas "client" refers to
126 the software being run by the user.
128 In examples, "C:" and "S:" indicate lines sent by the client and
129 server, respectively. If a single "C:" or "S:" label applies to
130 multiple lines, then the line breaks between those lines are for
131 editorial clarity only and are not part of the actual protocol
134 As with all IMAP extension documents, the case used in writing IMAP
135 protocol elements herein is chosen for editorial clarity, and
136 implementations must pay attention to the numbered rules at the
137 beginning of Section 9 of [RFC3501].
143 To retrieve a preview for a message, the PREVIEW FETCH attribute is
144 used when issuing a FETCH command.
148 The server returns a variable-length string that is the generated
149 preview for that message. This string is intended to be viewed by
150 the user as a contextual preview of the entire message and is not
151 intended to be interpreted in any way by the client software.
153 Example: Retrieving preview information in a SELECTed mailbox.
155 C: A1 FETCH 1 (PREVIEW)
156 S: * 1 FETCH (PREVIEW "Preview text!")
157 S: A1 OK FETCH complete.
159 A server SHOULD strive to generate the same string for a given
160 message for each request. However, since previews are understood to
161 be an approximation of the message data and not a canonical view of
162 its contents, a client MUST NOT assume that a message preview is
163 immutable for a given message. This relaxed requirement permits a
164 server to offer previews as an option without requiring potentially
165 burdensome storage and/or processing requirements to guarantee
166 immutability for a use case that does not require this strictness.
167 For example, the underlying IMAP server may change due to a system
168 software upgrade; an account's state information may be retained in
169 the migration, but the new server may generate different preview text
172 It is possible that the server has determined that no meaningful
173 preview text can be generated for a particular message. Examples of
174 this involve encrypted messages, content types the server does not
175 support previews of, and other situations where the server is not
176 able to extract information for a preview. In such cases, the server
177 MUST return a zero-length string. Clients SHOULD NOT send another
178 FETCH for a preview for such messages. (As discussed previously,
179 preview data is not immutable, so there is chance that at some point
180 in the future the server would be able to generate meaningful text.
181 However, this scenario is expected to be rare, so a client should not
182 continually send out requests to try to detect this infrequent
185 If the LAZY modifier (Section 4.1) is used, the server MAY return NIL
186 for the preview response, indicating that preview generation could
187 not be completed without causing undue delay. A server MUST NOT
188 return NIL to a FETCH PREVIEW request made without the LAZY modifier.
1903.3. Preview Text Format
192 The generated preview text MUST be treated as text/plain [RFC2046]
193 media type data by the client.
195 The generated string MUST NOT be content transfer encoded and MUST be
196 encoded in UTF-8 [RFC3629]. The server SHOULD remove any formatting
197 markup and do whatever processing might be useful in rendering the
198 preview as plain text.
200 For purposes of this section, a "preview character" is defined as a
201 single Universal Character Set (UCS) character encoded in UTF-8.
202 Note: a single preview character may comprise multiple octets, so any
203 buffers implemented to conform to the string limitations identified
204 in this document should be sized to prevent possible overflow errors.
206 The server SHOULD limit the length of the preview text to 200 preview
207 characters. This length should provide sufficient data to generally
208 support both various languages (and their different average word
209 lengths) and diverse client display size requirements.
211 The server MUST NOT output preview text longer than 256 preview
214 If the preview is not generated based on the body content of the
215 message, and the LANGUAGE extension [RFC5255] is supported by the
216 server, the preview text SHOULD be generated according to the
217 language rules that apply to human-readable text. For example, a
218 message that consists of a single image MIME part has no human-
219 readable text from which to generate preview information. Instead,
220 the server may wish to output a description that the message contains
221 an image and describe some attributes of the image, such as image
222 format, size, and filename. This descriptive text is not a product
223 of the message body itself but is rather auto-generated data by the
224 server; it should thus use the rules defined for human-readable text
225 described in the LANGUAGE extension (if supported on the server).
2274. LAZY Priority Modifier
231 The LAZY modifier directs the server to return the preview
232 representation only if that data can be returned without undue delay
235 If this modifier is used, and the server is unable to return preview
236 data without undue delay, the server MUST return NIL as the preview
239 The LAZY modifier MUST be implemented by any server that supports the
2424.2. Client Implementation Advice
244 Upon opening a mailbox, a client generally performs a FETCH of
245 message details in order to create a listing to present to the user
246 (e.g., ENVELOPE data). Using this extension, a client may want to
247 additionally display preview information as part of this listing.
248 Quickly providing the base mailbox listing with basic message details
249 is the primary goal of this command as this is required to allow the
250 user to begin interacting with the mailbox. Preview data is likely
251 to be of secondary importance; it provides useful context, but it is
252 not necessary to perform message actions. A client can load
253 unavailable previews in the background and display them
254 asynchronously to the user as the preview data is provided by the
257 In this scenario, the client would add the PREVIEW data item, with
258 the LAZY modifier, to the list of FETCH items needed to generate the
259 mailbox listing. This allows the server to advantageously return
260 preview data without blocking the primary goal of quickly returning
261 the basic message details used to generate the mailbox listing.
263 Once this initial FETCH is complete, the client can then issue FETCH
264 requests, without the LAZY modifier, to load the PREVIEW data item
265 for the messages in which preview data was not returned. It is
266 RECOMMENDED that these FETCH requests be issued in small batches,
267 e.g., 50 messages per FETCH command, since preview generation may be
268 expensive and a single large request may exceed server resource
271 See Example 2 in Section 5 for an implementation of this strategy.
273 A client SHOULD NOT continually issue FETCH PREVIEW requests with the
274 LAZY modifier in a selected mailbox as the server is under no
275 requirement to return preview information for this command, which
276 could lead to an unnecessary waste of system and network resources.
280 Example 1: Requesting preview without LAZY modifier.
283 S: * CAPABILITY IMAP4rev1 PREVIEW
284 S: A1 OK Capability command completed.
285 [...a mailbox is SELECTed...]
286 C: A2 FETCH 1 (RFC822.SIZE PREVIEW)
287 S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200}
288 S: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
289 S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue.
290 S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla
293 S: A2 OK FETCH complete.
295 Example 2: Requesting preview with LAZY modifier, to obtain previews
296 during initial mailbox listing if readily available; otherwise, load
297 previews in background.
299 C: B1 FETCH 1:4 (ENVELOPE PREVIEW (LAZY))
300 S: * 1 FETCH (ENVELOPE ("Wed, 23 Sep 2020 15:03:11 +0000" [...])
301 PREVIEW "Preview text for message 1.")
302 S: * 2 FETCH (PREVIEW "" ENVELOPE
303 ("Thu, 24 Sep 2020 12:17:23 +0000" [...]))
304 S: * 3 FETCH (ENVELOPE ("Fri, 25 Sep 2020 09:13:45 +0000" [...])
306 S: * 4 FETCH (ENVELOPE ("Sat, 26 Sep 2020 07:11:18 +0000" [...])
308 S: B1 OK FETCH completed.
309 [...Client has preview for message 1 and knows that message 2 has
310 a preview that is empty; only need to request preview of
311 messages 3 & 4 (e.g., in background)...]
312 C: B2 FETCH 3:4 (PREVIEW)
313 S: * 3 FETCH (PREVIEW {30}
314 S: Message data from message 3.
316 S: * 4 FETCH (PREVIEW "Message 4 preview")
317 S: B2 OK Fetch completed.
319 Example 3: Requesting preview for search results within a single
320 mailbox. Use the SEARCHRES extension [RFC5182] to save a round-trip.
323 S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES
324 S: C1 OK Capability command completed.
325 [...a mailbox is SELECTed...]
326 C: C2 SEARCH RETURN (SAVE) FROM "FOO"
327 C: C3 FETCH $ (UID PREVIEW (LAZY))
328 S: C2 OK SEARCH completed.
329 S: * 5 FETCH (UID 13 PREVIEW "Preview!")
330 S: * 9 FETCH (UID 23 PREVIEW NIL)
331 S: C3 OK FETCH completed.
332 [...Retrieve message 9 preview in background...]
333 C: C4 UID FETCH 23 (PREVIEW)
334 S: * 9 FETCH (UID 23 PREVIEW "Another preview!")
335 S: C4 OK FETCH completed.
339 The following syntax specification uses the Augmented Backus-Naur
340 Form (ABNF) as described in [RFC5234]. It includes definitions from
343 capability =/ "PREVIEW"
345 fetch-att =/ "PREVIEW" [SP "(" preview-mod *(SP
348 msg-att-dynamic =/ "PREVIEW" SP nstring
3527. IANA Considerations
354 IMAP [RFC3501] capabilities are registered by publishing a Standards
355 Track or IESG-approved Experimental RFC in the "IMAP Capabilities"
356 registry located at <http://www.iana.org/assignments/imap-
359 IANA has added the "PREVIEW" capability to this registry.
3618. Security Considerations
363 Implementation of this extension might enable denial-of-service
364 attacks against server resources, due to excessive memory or CPU
365 usage during preview generation or increased storage usage if preview
366 results are stored on the server after generation. In order to
367 mitigate such attacks, servers SHOULD log the client authentication
368 identity on FETCH PREVIEW operations in order to facilitate tracking
371 Servers MAY limit the resources that preview generation uses. Such
372 resource limitations might, in an extreme example, cause a server to
373 return a preview that is the empty string for a message that
374 otherwise would have had a non-empty preview. However, it is
375 recommended that at least some preview text be provided in this
376 situation, even if the quality of the preview is degraded.
378 Just as the messages they summarize, preview data may contain
379 sensitive information. If generated preview data is stored on the
380 server, e.g., for caching purposes, these previews MUST be protected
381 with equivalent authorization and confidentiality controls as the
3869.1. Normative References
388 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
389 Extensions (MIME) Part Two: Media Types", RFC 2046,
390 DOI 10.17487/RFC2046, November 1996,
391 <https://www.rfc-editor.org/info/rfc2046>.
393 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
394 Requirement Levels", BCP 14, RFC 2119,
395 DOI 10.17487/RFC2119, March 1997,
396 <https://www.rfc-editor.org/info/rfc2119>.
398 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
399 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
400 <https://www.rfc-editor.org/info/rfc3501>.
402 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
403 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
404 2003, <https://www.rfc-editor.org/info/rfc3629>.
406 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
407 Specifications: ABNF", STD 68, RFC 5234,
408 DOI 10.17487/RFC5234, January 2008,
409 <https://www.rfc-editor.org/info/rfc5234>.
411 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
412 Message Access Protocol Internationalization", RFC 5255,
413 DOI 10.17487/RFC5255, June 2008,
414 <https://www.rfc-editor.org/info/rfc5255>.
416 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
417 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
418 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
4209.2. Informative References
422 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
423 Extensions (MIME) Part One: Format of Internet Message
424 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
425 <https://www.rfc-editor.org/info/rfc2045>.
427 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media
428 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000,
429 <https://www.rfc-editor.org/info/rfc2854>.
431 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last
432 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March
433 2008, <https://www.rfc-editor.org/info/rfc5182>.
437 The author would like to thank the following people for their
438 comments and contributions to this document: Stephan Bosch, Bron
439 Gondwana, Teemu Huovila, Neil Jenkins, Steffen Lehmann, Barry Leiba,
440 Alexey Melnikov, Chris Newman, Pete Resnick, Jeff Sipek, Timo
441 Sirainen, Steffen Templin, and Aki Tuomi.
448 Palo Alto, California 94301
449 United States of America
451 Email: michael.slusarz@open-xchange.com