RFC 4731

IMAP4 Extension to SEARCH Command for Controlling What Kind of Information Is Returned

📅 published November 2006, from ietf

RFC 4731: IMAP4 Extension to SEARCH Command for Controlling What Kind of Information Is Returned 💖

Okay bestie, let's start with the basics ✨ This is RFC 4731, a Standards Track doc from November 2006, written by A. Melnikov (Isode Ltd) and D. Cridland (Inventure Systems Ltd), and it's part of the Network Working Group 🦋 Nothing is listed as obsoleted or updated in the header, so it's not replacing or patching any older RFC. Iconic!

Status of This Memo 📜

This document is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🫶 For the current standardization state and status of this protocol, check the "Internet Official Protocol Standards" (STD 1) 🔍 Distribution of this memo is unlimited, so share it with your whole group chat 💅

Copyright Notice ©️

Abstract 🌈

This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands with several result options, which can control what kind of information is returned. The following result options are defined: minimal value, maximal value, all found messages, and number of found messages.

Table of Contents 📑

   1. Introduction ....................................................2
   2. Conventions Used in This Document ...............................2
   3. IMAP Protocol Changes ...........................................2
      3.1. New SEARCH/UID SEARCH Result Options .......................2
      3.2. Interaction with CONDSTORE extension .......................4
   4. Formal Syntax ...................................................5
   5. Security Considerations .........................................6
   6. IANA Considerations .............................................6
   7. Normative References ............................................6
   8. Acknowledgments .................................................6

1. Introduction ✨

Okay so [IMAPABNF] already extended SEARCH and UID SEARCH commands with result specifiers (also known as result options) 🎀 These let the server control what kind of information comes back, and it's giving organized.

A server that advertises the ESEARCH capability supports these result options: minimal value, maximal value, all found messages, and number of found messages 💜 They let clients get SEARCH results in more convenient forms and save bandwidth on the way back, like finding the first unseen message or getting the count of unseen or deleted messages without downloading a whole list 🍓 Also, when a single MIN or a single MAX result option is specified, servers can optimize how they run SEARCHes 🔥

2. Conventions Used in This Document 📖

In examples, "C:" and "S:" mark lines sent by the client and server, respectively 💅

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [KEYWORDS]. Bestie, these are the official requirement-level words, so read them carefully 🙈

3. IMAP Protocol Changes 🧚

3.1. New SEARCH/UID SEARCH Result Options 💖

The SEARCH/UID SEARCH commands are extended to allow for the following result options:

MIN: Return the lowest message number/UID that satisfies the SEARCH criteria.
- If the SEARCH results in no matches, the server MUST NOT include the MIN result option in the ESEARCH response; however, it still MUST send the ESEARCH response. 😭
MAX: Return the highest message number/UID that satisfies the SEARCH criteria.
- If the SEARCH results in no matches, the server MUST NOT include the MAX result option in the ESEARCH response; however, it still MUST send the ESEARCH response. 😭
ALL: Return all message numbers/UIDs that satisfy the SEARCH criteria. Unlike regular (unextended) SEARCH, the messages are always returned using the sequence-set syntax. A sequence-set representation may be more compact and can be used as is in a subsequent command that accepts sequence-set. Note, the client MUST NOT assume that messages/UIDs will be listed in any particular order. 👑
- If the SEARCH results in no matches, the server MUST NOT include the ALL result option in the ESEARCH response; however, it still MUST send the ESEARCH response.
COUNT: Return number of the messages that satisfy the SEARCH criteria. This result option MUST always be included in the ESEARCH response. 🦋

If one or more result options described above are specified, the extended SEARCH command MUST return a single ESEARCH response [IMAPABNF], instead of the SEARCH response. 🫶

An extended UID SEARCH command MUST cause an ESEARCH response with the UID indicator present. 🌸

Note that future extensions to this document can allow servers to return multiple ESEARCH responses for a single extended SEARCH command. Those extensions will have to describe how results from multiple ESEARCH responses are to be amalgamated 🔮

If the list of result options is empty, that requests the server to return an ESEARCH response instead of the SEARCH response. This is equivalent to "(ALL)" ✨

Example:

C: A282 SEARCH RETURN (MIN COUNT) FLAGGED
   SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A282") MIN 2 COUNT 3
S: A282 OK SEARCH completed

Example:

C: A283 SEARCH RETURN () FLAGGED
   SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A283") ALL 2,10:11
S: A283 OK SEARCH completed

The following example shows finding the first unseen message, as returned in the UNSEEN response code on a successful SELECT command 👀

Example:

C: A284 SEARCH RETURN (MIN) UNSEEN
S: * ESEARCH (TAG "A284") MIN 4
S: A284 OK SEARCH completed

The following example shows that if the ESEARCH UID indicator is present, all data in the ESEARCH response refers to UIDs. For example, the MIN result specifier will be followed by a UID. 🆔

Example:

C: A285 UID SEARCH RETURN (MIN MAX) 1:5000
S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
S: A285 OK SEARCH completed

The following example shows returning the number of deleted messages 🗑️

Example:

C: A286 SEARCH RETURN (COUNT) DELETED
S: * ESEARCH (TAG "A286") COUNT 15
S: A286 OK SEARCH completed

3.2. Interaction with CONDSTORE extension 🦋

When the server supports both the ESEARCH and the CONDSTORE [CONDSTORE] extension, and the client requests one or more result option described in section 3.1 together with the MODSEQ search criterion in the same SEARCH/UID SEARCH command, then the server MUST return the ESEARCH response containing the MODSEQ result option (described in the following paragraph) instead of the extended SEARCH response described in section 3.5 of [CONDSTORE]. This is the plot twist, so pay attention! 😳

If the SEARCH/UID SEARCH command contained a single MIN or MAX result option, the MODSEQ result option contains the mod-sequence for the found message. If the SEARCH/UID SEARCH command contained both MIN and MAX result options and no ALL/COUNT option, the MODSEQ result option contains the highest mod-sequence for the two returned messages. Otherwise, the MODSEQ result option contains the highest mod-sequence for all messages being returned. 🧮

Example: The following example shows how Example 15 from [CONDSTORE] would look in the presence of one or more result options 💜

      C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft"
          all 620162338
      S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488
      S: a1 OK Search complete

      C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft"
          all 620162338
      S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321
      S: a2 OK Search complete

      C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft"
          all 620162338
      S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488
      S: a3 OK Search complete

      C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft"
          all 620162338
      S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500
      S: a4 OK Search complete

Authors' Addresses ✨

Here are the people who wrote this one, plus how to reach them 💌

Alexey Melnikov 🦋 is at Isode Limited:

Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex, TW12 2BX
UK

Email: Alexey.Melnikov@isode.com

Dave A. Cridland 🌸 is at Inventure Systems Limited. Email: dave.cridland@inventuresystems.co.uk. His website is http://invsys.co.uk/dave/ 💖

Full Copyright Statement 🎀

Okay, the legal bit, but make it cute: the copyright is held by The IETF Trust (2006) 📜

This document is covered by the rights, licenses and restrictions in BCP 78. The authors keep all their rights, except where BCP 78 says otherwise 🔒

The document and everything in it is handed over "AS IS" 🫶 The contributor, the organization they represent or are sponsored by (if any), the Internet Society, the IETF Trust, and the Internet Engineering Task Force all disclaim every warranty, whether express or implied. That covers the promise that using the info won't infringe anyone's rights, and it also covers implied warranties of merchantability and fitness for a particular purpose 💅

Intellectual Property 🌈

The IETF doesn't take a side on whether any Intellectual Property Rights or other rights that someone might claim over the tech in here are valid or how far they reach. It also doesn't say whether licenses under those rights are available 🤷‍♀️ It hasn't tried to hunt down those rights either. If you want the process for rights in RFC documents, check BCP 78 and BCP 79 📚

Copies of IPR disclosures sent to the IETF Secretariat live in the IETF's online IPR repository at http://www.ietf.org/ipr. You'll also find any promised licenses there, plus results from anyone who tried to get a general license or permission to use the proprietary rights as an implementer or user of this spec 🔍

The IETF also really wants to hear from you 🙋‍♀️ If you know about copyrights, patents, patent applications or other proprietary rights that might cover tech needed to implement this standard, tell the IETF at ietf-ipr@ietf.org ✨

Acknowledgement 🫶

Shoutout to the funders! The RFC Editor function is currently funded by the Internet Society 💜

🌟 That's the whole doc, bestie. The specs are the stars, the boring legal stuff is the glitter that keeps everything legit ✨

Thanks for reading all the way through! 🦋

📦 where this page comes from

ietf: rfc4731 2006-11
💖 girlified by claude-haiku-5-5 on 2026-10-16: a language model's rewrite of the original, under its terms