Section 2. Protocol Overview

2.1.  Link Level
   The IMAP4rev2 protocol assumes a reliable data stream such as that
   provided by TCP.  When TCP is used, an IMAP4rev2 server listens on
   port 143 (cleartext port) or port 993 (Implicit TLS port).
2.2.  Commands and Responses
   An IMAP4rev2 connection consists of the establishment of a client/
   server network connection, an initial greeting from the server, and
   client/server interactions.  These client/server interactions consist
   of a client command, server data, and a server completion result
   response.
   All interactions transmitted by client and server are in the form of
   lines, that is, strings that end with a CRLF.  The protocol receiver
   of an IMAP4rev2 client or server is reading either a line or a
   sequence of octets with a known count followed by a line.
2.2.1.  Client Protocol Sender and Server Protocol Receiver
   The client command begins an operation.  Each client command is
   prefixed with an identifier (typically a short alphanumeric string,
   e.g., A0001, A0002, etc.) called a "tag".  A different tag is
   generated by the client for each command.  More formally: the client
   SHOULD generate a unique tag for every command, but a server MUST
   accept tag reuse.
   Clients MUST follow the syntax outlined in this specification
   strictly.  It is a syntax error to send a command with missing or
   extraneous spaces or arguments.
   There are two cases in which a line from the client does not
   represent a complete command.  In one case, a command argument is
   quoted with an octet count (see the description of literal in
   Section 4.3); in the other case, the command arguments require server
   feedback (see the AUTHENTICATE command in Section 6.2.2).  In either
   case, the server sends a command continuation request response if it
   is ready for the octets (if appropriate) and the remainder of the
   command.  This response is prefixed with the token "+".
      Note: If, instead, the server detected an error in the command, it
      sends a BAD completion response with a tag matching the command
      (as described below) to reject the command and prevent the client
      from sending any more of the command.
      It is also possible for the server to send a completion response
      for some other command (if multiple commands are in progress) or
      untagged data.  In either case, the command continuation request
      is still pending; the client takes the appropriate action for the
      response and reads another response from the server.  In all
      cases, the client MUST send a complete command (including
      receiving all command continuation request responses and sending
      command continuations for the command) before initiating a new
      command.
   The protocol receiver of an IMAP4rev2 server reads a command line
   from the client, parses the command and its arguments, and transmits
   server data and a server command completion result response.
2.2.2.  Server Protocol Sender and Client Protocol Receiver
   Data transmitted by the server to the client and status responses
   that do not indicate command completion are prefixed with the token
   "*" and are called untagged responses.
   Server data MAY be sent as a result of a client command or MAY be
   sent unilaterally by the server.  There is no syntactic difference
   between server data that resulted from a specific command and server
   data that were sent unilaterally.
   The server completion result response indicates the success or
   failure of the operation.  It is tagged with the same tag as the
   client command that began the operation.  Thus, if more than one
   command is in progress, the tag in a server completion response
   identifies the command to which the response applies.  There are
   three possible server completion responses: OK (indicating success),
   NO (indicating failure), or BAD (indicating a protocol error such as
   unrecognized command or command syntax error).
   Servers SHOULD strictly enforce the syntax outlined in this
   specification.  Any client command with a protocol syntax error,
   including (but not limited to) missing or extraneous spaces or
   arguments, SHOULD be rejected and the client given a BAD server
   completion response.
   The protocol receiver of an IMAP4rev2 client reads a response line
   from the server.  It then takes action on the response based upon the
   first token of the response, which can be a tag, a "*", or a "+".
   A client MUST be prepared to accept any server response at all times.
   This includes server data that was not requested.  Server data SHOULD
   be remembered (cached), so that the client can reference its
   remembered copy rather than sending a command to the server to
   request the data.  In the case of certain server data, the data MUST
   be remembered, as specified elsewhere in this document.
   This topic is discussed in greater detail in "Server Responses" (see
   Section 7).
2.3.  Message Attributes
   In addition to message text, each message has several attributes
   associated with it.  These attributes can be retrieved individually
   or in conjunction with other attributes or message texts.
2.3.1.  Message Numbers
   Messages in IMAP4rev2 are accessed by one of two numbers: the Unique
   Identifier (UID) or the message sequence number.
2.3.1.1.  Unique Identifier (UID) Message Attribute
   A UID is an unsigned non-zero 32-bit value assigned to each message,
   which when used with the unique identifier validity value (see below)
   forms a 64-bit value that MUST NOT refer to any other message in the
   mailbox or any subsequent mailbox with the same name forever.  Unique
   identifiers are assigned in a strictly ascending fashion in the
   mailbox; as each message is added to the mailbox, it is assigned a
   higher UID than those of all message(s) that are already in the
   mailbox.  Unlike message sequence numbers, unique identifiers are not
   necessarily contiguous.
   The unique identifier of a message MUST NOT change during the session
   and SHOULD NOT change between sessions.  Any change of unique
   identifiers between sessions MUST be detectable using the UIDVALIDITY
   mechanism discussed below.  Persistent unique identifiers are
   required for a client to resynchronize its state from a previous
   session with the server (e.g., disconnected or offline access clients
   [IMAP-MODEL]); this is discussed further in [IMAP-DISC].
   Associated with every mailbox are two 32-bit unsigned non-zero values
   that aid in unique identifier handling: the next unique identifier
   value (UIDNEXT) and the unique identifier validity value
   (UIDVALIDITY).
   The next unique identifier value is the predicted value that will be
   assigned to a new message in the mailbox.  Unless the unique
   identifier validity also changes (see below), the next unique
   identifier value MUST have the following two characteristics.  First,
   the next unique identifier value MUST NOT change unless new messages
   are added to the mailbox; and second, the next unique identifier
   value MUST change whenever new messages are added to the mailbox,
   even if those new messages are subsequently expunged.
      |  Note: The next unique identifier value is intended to provide a
      |  means for a client to determine whether any messages have been
      |  delivered to the mailbox since the previous time it checked
      |  this value.  It is not intended to provide any guarantee that
      |  any message will have this unique identifier.  A client can
      |  only assume, at the time that it obtains the next unique
      |  identifier value, that messages arriving after that time will
      |  have a UID greater than or equal to that value.
   The unique identifier validity value is sent in a UIDVALIDITY
   response code in an OK untagged response at mailbox selection time.
   If unique identifiers from an earlier session fail to persist in this
   session, the unique identifier validity value MUST be greater than
   the one used in the earlier session.  A good UIDVALIDITY value to use
   is a 32-bit representation of the current date/time when the value is
   assigned: this ensures that the value is unique and always increases.
   Another possible alternative is a global counter that gets
   incremented every time a mailbox is created.
      Note: Ideally, unique identifiers SHOULD persist at all times.
      Although this specification recognizes that failure to persist can
      be unavoidable in certain server environments, it strongly
      encourages message store implementation techniques that avoid this
      problem.  For example:
   1.  Unique identifiers MUST be strictly ascending in the mailbox at
       all times.  If the physical message store is reordered by a non-
       IMAP agent, the unique identifiers in the mailbox MUST be
       regenerated, since the former unique identifiers are no longer
       strictly ascending as a result of the reordering.
   2.  If the message store has no mechanism to store unique
       identifiers, it must regenerate unique identifiers at each
       session, and each session must have a unique UIDVALIDITY value.
       Note that this situation can be very disruptive to client message
       caching.
   3.  If the mailbox is deleted/renamed and a new mailbox with the same
       name is created at a later date, the server must either keep
       track of unique identifiers from the previous instance of the
       mailbox or assign a new UIDVALIDITY value to the new instance of
       the mailbox.
   4.  The combination of mailbox name, UIDVALIDITY, and UID must refer
       to a single, immutable (or expunged) message on that server
       forever.  In particular, the internal date, RFC822.SIZE,
       envelope, body structure, and message texts (all BODY[...] fetch
       data items) MUST never change.  This does not include message
       numbers, nor does it include attributes that can be set by a
       STORE command (such as FLAGS).  When a message is expunged, its
       UID MUST NOT be reused under the same UIDVALIDITY value.
2.3.1.2.  Message Sequence Number Message Attribute
   A message sequence number is a relative position from 1 to the number
   of messages in the mailbox.  This position MUST be ordered by
   ascending unique identifiers.  As each new message is added, it is
   assigned a message sequence number that is 1 higher than the number
   of messages in the mailbox before that new message was added.
   Message sequence numbers can be reassigned during the session.  For
   example, when a message is permanently removed (expunged) from the
   mailbox, the message sequence number for all subsequent messages is
   decremented.  The number of messages in the mailbox is also
   decremented.  Similarly, a new message can be assigned a message
   sequence number that was once held by some other message prior to an
   expunge.
   In addition to accessing messages by relative position in the
   mailbox, message sequence numbers can be used in mathematical
   calculations.  For example, if an untagged "11 EXISTS" is received,
   and previously an untagged "8 EXISTS" was received, three new
   messages have arrived with message sequence numbers of 9, 10, and 11.
   As another example, if message 287 in a 523-message mailbox has UID
   12345, there are exactly 286 messages that have lesser UIDs and 236
   messages that have greater UIDs.
2.3.2.  Flags Message Attribute
   A message has a list of zero or more named tokens, known as "flags",
   associated with it.  A flag is set by its addition to this list and
   is cleared by its removal.  There are two types of flags in
   IMAP4rev2: system flags and keywords.  A flag of either type can be
   permanent or session-only.
   A system flag is a flag name that is predefined in this specification
   and begins with "\".  Certain system flags (\Deleted and \Seen) have
   special semantics described elsewhere in this document.  The
   currently defined system flags are:
   \Seen         Message has been read
   \Answered     Message has been answered
   \Flagged      Message is "flagged" for urgent/special attention
   \Deleted      Message is "deleted" for removal by later EXPUNGE
   \Draft        Message has not completed composition (marked as a
                 draft).
   \Recent       This flag was in use in IMAP4rev1 and is now
                 deprecated.
   A keyword is defined by the server implementation.  Keywords do not
   begin with "\".  Servers MAY permit the client to define new keywords
   in the mailbox (see the description of the PERMANENTFLAGS response
   code for more information).  Some keywords that start with "$" are
   also defined in this specification.
   This document defines several keywords that were not originally
   defined in [RFC3501] but were found to be useful by client
   implementations.  These keywords SHOULD be supported (allowed in
   SEARCH and allowed and preserved in APPEND, COPY, and MOVE commands)
   by server implementations:
   $Forwarded
      Message has been forwarded to another email address by being
      embedded within, or attached to a new message.  An email client
      sets this keyword when it successfully forwards the message to
      another email address.  Typical usage of this keyword is to show a
      different (or additional) icon for a message that has been
      forwarded.  Once set, the flag SHOULD NOT be cleared.
   $MDNSent
      Message Disposition Notification [RFC8098] was generated and sent
      for this message.  See [RFC3503] for more details on how this
      keyword is used and for requirements on clients and servers.
   $Junk
      The user (or a delivery agent on behalf of the user) may choose to
      mark a message as definitely containing junk ($Junk; see also the
      related keyword $NotJunk).  The $Junk keyword can be used to mark,
      group, or hide undesirable messages (and such messages might be
      moved or deleted later).  See [IMAP-KEYWORDS-REG] for more
      information.
   $NotJunk
      The user (or a delivery agent on behalf of the user) may choose to
      mark a message as definitely not containing junk ($NotJunk; see
      also the related keyword $Junk).  The $NotJunk keyword can be used
      to mark, group, or show messages that the user wants to see.  See
      [IMAP-KEYWORDS-REG] for more information.
   $Phishing
      The $Phishing keyword can be used by a delivery agent to mark a
      message as highly likely to be a phishing email.  A message that's
      determined to be a phishing email by the delivery agent should
      also be considered a junk email and have the appropriate junk
      filtering applied, including setting the $Junk flag and placing
      the message in the \Junk special-use mailbox (see Section 7.3.1),
      if available.
      If both the $Phishing flag and the $Junk flag are set, the user
      agent should display an additional warning message to the user.
      Additionally, the user agent might display a warning, such as
      something of the form, "This message may be trying to steal your
      personal information," when the user clicks on any hyperlinks
      within the message.
      The requirement for both $Phishing and $Junk to be set before a
      user agent displays a warning is for better backwards
      compatibility with existing clients that understand the $Junk flag
      but not the $Phishing flag.  This is so that when an unextended
      client removes the $Junk flag, an extended client will also show
      the correct state.  See [IMAP-KEYWORDS-REG] for more information.
   $Junk and $NotJunk are mutually exclusive.  If more than one of these
   is set for a message, the client MUST treat it as if none are set,
   and it SHOULD unset both of them on the IMAP server.
   Other registered keywords can be found in the "IMAP and JMAP
   Keywords" registry [IMAP-KEYWORDS-REG].  New keywords SHOULD be
   registered in this registry using the procedure specified in
   [RFC5788].
   A flag can be permanent or session-only on a per-flag basis.
   Permanent flags are those that the client can add or remove from the
   message flags permanently; that is, concurrent and subsequent
   sessions will see any change in permanent flags.  Changes to session
   flags are valid only in that session.
2.3.3.  Internal Date Message Attribute
   An Internal Date message attribute is the internal date and time of
   the message on the server.  This is not the date and time in the
   [RFC5322] header but rather a date and time that reflects when the
   message was received.  In the case of messages delivered via [SMTP],
   this is the date and time of final delivery of the message as defined
   by [SMTP].  In the case of messages created by the IMAP4rev2 COPY or
   MOVE command, this SHOULD be the same as the Internal Date attribute
   of the source message.  In the case of messages created by the
   IMAP4rev2 APPEND command, this SHOULD be the date and time as
   specified in the APPEND command description.  All other cases are
   implementation defined.
2.3.4.  RFC822.SIZE Message Attribute
   RFC822.SIZE is the number of octets in the message when the message
   is expressed in [RFC5322] format.  This size SHOULD match the result
   of a "FETCH BODY[]" command.  If the message is internally stored in
   some other format, the server calculates the size and often stores it
   for later use to avoid the need for recalculation.
2.3.5.  Envelope Structure Message Attribute
   An envelope structure is a parsed representation of the [RFC5322]
   header of the message.  Note that the IMAP envelope structure is not
   the same as an [SMTP] envelope.
2.3.6.  Body Structure Message Attribute
   A body structure is a parsed representation of the [MIME-IMB] body
   structure information of the message.
2.4.  Message Texts
   In addition to being able to fetch the full [RFC5322] text of a
   message, IMAP4rev2 permits the fetching of portions of the full
   message text.  Specifically, it is possible to fetch the [RFC5322]
   message header, the [RFC5322] message body, a [MIME-IMB] body part,
   or a [MIME-IMB] header.