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

6.1.1. CAPABILITY Command

Arguments:

none¶

Responses:

REQUIRED untagged response:

CAPABILITY¶

Result:

OK -

capability completed¶

BAD -

arguments invalid¶

The CAPABILITY command requests a listing of capabilities (e.g., extensions and/or modifications of server behavior) that the server supports. The server MUST send a single untagged CAPABILITY response with "IMAP4rev2" as one of the listed capabilities before the (tagged) OK response.¶

A capability name that begins with "AUTH=" indicates that the server supports that particular authentication mechanism as defined in the Simple Authentication and Security Layer (SASL) [SASL]. All such names are, by definition, part of this specification.¶

Other capability names refer to extensions, revisions, or amendments to this specification. See the documentation of the CAPABILITY response in Section 7.2.2 for additional information. If IMAP4rev1 capability is not advertised, no capabilities, beyond the base IMAP4rev2 set defined in this specification, are enabled without explicit client action to invoke the capability. If both IMAP4rev1 and IMAP4rev2 capabilities are advertised, no capabilities, beyond the base IMAP4rev1 set specified in [RFC3501], are enabled without explicit client action to invoke the capability.¶

Client and server implementations MUST implement the STARTTLS (Section 6.2.1) and LOGINDISABLED capabilities on cleartext ports. Client and server implementations MUST also implement AUTH=PLAIN (described in [PLAIN]) capability on both cleartext and Implicit TLS ports. See the Security Considerations (Section 11) for important information.¶

Unless otherwise specified, all registered extensions to IMAP4rev1 are also valid extensions to IMAP4rev2.¶

Example:¶

  C: abcd CAPABILITY
  S: * CAPABILITY IMAP4rev2 STARTTLS AUTH=GSSAPI
   LOGINDISABLED
  S: abcd OK CAPABILITY completed
  C: efgh STARTTLS
  S: efgh OK STARTTLS completed
  <TLS negotiation, further commands are under TLS layer>
  C: ijkl CAPABILITY
  S: * CAPABILITY IMAP4rev2 AUTH=GSSAPI AUTH=PLAIN
  S: ijkl OK CAPABILITY completed

6.2.1. STARTTLS Command

Arguments:

none¶

Responses:

no specific response for this command¶

Result:

OK -

starttls completed, begin TLS negotiation¶

NO -

TLS negotiation can't be initiated, due to server configuration error¶

BAD -

STARTTLS received after a successful TLS negotiation or arguments invalid¶

Note that the STARTTLS command is available only on cleartext ports. The server MUST always respond with a tagged BAD response when the STARTTLS command is received on an Implicit TLS port.¶

A TLS [TLS-1.3] negotiation begins immediately after the CRLF at the end of the tagged OK response from the server. Once a client issues a STARTTLS command, it MUST NOT issue further commands until a server response is seen and the TLS negotiation is complete. Some past server implementations incorrectly implemented STARTTLS processing and are known to contain STARTTLS plaintext command injection vulnerability [CERT-555316]. In order to avoid this vulnerability, server implementations MUST do one of the following if any data is received in the same TCP buffer after the CRLF that starts the STARTTLS command:¶

1. Extra data from the TCP buffer is interpreted as the beginning of the TLS handshake. (If the data is in cleartext, this will result in the TLS handshake failing.)¶
2. Extra data from the TCP buffer is thrown away.¶

Note that the first option is friendlier to clients that pipeline the beginning of the STARTTLS command with TLS handshake data.¶

After successful TLS negotiation, the server remains in the non-authenticated state, even if client credentials are supplied during the TLS negotiation. This does not preclude an authentication mechanism such as EXTERNAL (defined in [SASL]) from using client identity determined by the TLS negotiation.¶

Once TLS has been started, the client MUST discard cached information about server capabilities and SHOULD reissue the CAPABILITY command. This is necessary to protect against active attacks that alter the capabilities list prior to STARTTLS. The server MAY advertise different capabilities and, in particular, SHOULD NOT advertise the STARTTLS capability, after a successful STARTTLS command.¶

Example:¶

   C: a001 CAPABILITY
   S: * CAPABILITY IMAP4rev2 STARTTLS LOGINDISABLED
   S: a001 OK CAPABILITY completed
   C: a002 STARTTLS
   S: a002 OK Begin TLS negotiation now
   <TLS negotiation, further commands are under TLS layer>
   C: a003 CAPABILITY
   S: * CAPABILITY IMAP4rev2 AUTH=PLAIN
   S: a003 OK CAPABILITY completed
   C: a004 AUTHENTICATE PLAIN dGVzdAB0ZXN0AHRlc3Q=
   S: a004 OK Success (tls protection)

6.2.2. AUTHENTICATE Command

Arguments:

SASL authentication mechanism name¶

OPTIONAL initial response¶

Responses:

continuation data can be requested¶

Result:

OK -

authenticate completed, now in authenticated state¶

NO -

authenticate failure: unsupported authentication mechanism, credentials rejected¶

BAD -

command unknown or arguments invalid, authentication exchange canceled¶

The AUTHENTICATE command indicates a [SASL] authentication mechanism to the server. If the server supports the requested authentication mechanism, it performs an authentication protocol exchange to authenticate and identify the client. It MAY also negotiate an OPTIONAL security layer for subsequent protocol interactions. If the requested authentication mechanism is not supported, the server SHOULD reject the AUTHENTICATE command by sending a tagged NO response.¶

The AUTHENTICATE command supports the optional "initial response" feature defined in Section 4 of [SASL]. The client doesn't need to use it. If a SASL mechanism supports "initial response", but it is not specified by the client, the server handles it as specified in Section 3 of [SASL].¶

The service name specified by this protocol's profile of [SASL] is "imap".¶

The authentication protocol exchange consists of a series of server challenges and client responses that are specific to the authentication mechanism. A server challenge consists of a command continuation request response with the "+" token followed by a base64-encoded (see Section 4 of [RFC4648]) string. The client response consists of a single line consisting of a base64-encoded string. If the client wishes to cancel an authentication exchange, it issues a line consisting of a single "*". If the server receives such a response, or if it receives an invalid base64 string (e.g., characters outside the base64 alphabet or non-terminal "="), it MUST reject the AUTHENTICATE command by sending a tagged BAD response.¶

As with any other client response, the initial response MUST be encoded as base64. It also MUST be transmitted outside of a quoted string or literal. To send a zero-length initial response, the client MUST send a single pad character ("="). This indicates that the response is present, but it is a zero-length string.¶

When decoding the base64 data in the initial response, decoding errors MUST be treated as in any normal SASL client response, i.e., with a tagged BAD response. In particular, the server should check for any characters not explicitly allowed by the base64 alphabet, as well as any sequence of base64 characters that contains the pad character ('=') anywhere other than the end of the string (e.g., "=AAA" and "AAA=BBB" are not allowed).¶

If the client uses an initial response with a SASL mechanism that does not support an initial response, the server MUST reject the command with a tagged BAD response.¶

If a security layer is negotiated through the [SASL] authentication exchange, it takes effect immediately following the CRLF that concludes the authentication exchange for the client and the CRLF of the tagged OK response for the server.¶

While client and server implementations MUST implement the AUTHENTICATE command itself, it is not required to implement any authentication mechanisms other than the PLAIN mechanism described in [PLAIN]. Also, an authentication mechanism is not required to support any security layers.¶

Note: a server implementation MUST implement a configuration in which it does NOT permit any plaintext password mechanisms, unless the STARTTLS command has been negotiated, TLS has been negotiated on an Implicit TLS port, or some other mechanism that protects the session from password snooping has been provided. Server sites SHOULD NOT use any configuration that permits a plaintext password mechanism without such a protection mechanism against password snooping. Client and server implementations SHOULD implement additional [SASL] mechanisms that do not use plaintext passwords, such as the GSSAPI mechanism described in [RFC4752], the SCRAM-SHA-256/SCRAM-SHA-256-PLUS [SCRAM-SHA-256] mechanisms, and/or the EXTERNAL [SASL] mechanism for mutual TLS authentication. (Note that the SASL framework allows for the creation of SASL mechanisms that support 2-factor authentication (2FA); however, none are fully ready to be recommended by this document.)¶

Servers and clients can support multiple authentication mechanisms. The server SHOULD list its supported authentication mechanisms in the response to the CAPABILITY command so that the client knows which authentication mechanisms to use.¶

A server MAY include a CAPABILITY response code in the tagged OK response of a successful AUTHENTICATE command in order to send capabilities automatically. It is unnecessary for a client to send a separate CAPABILITY command if it recognizes these automatic capabilities. This should only be done if a security layer was not negotiated by the AUTHENTICATE command, because the tagged OK response as part of an AUTHENTICATE command is not protected by encryption/integrity checking. [SASL] requires the client to re-issue a CAPABILITY command in this case. The server MAY advertise different capabilities after a successful AUTHENTICATE command.¶

If an AUTHENTICATE command fails with a NO response, the client MAY try another authentication mechanism by issuing another AUTHENTICATE command. It MAY also attempt to authenticate by using the LOGIN command (see Section 6.2.3 for more detail). In other words, the client MAY request authentication types in decreasing order of preference, with the LOGIN command as a last resort.¶

The authorization identity passed from the client to the server during the authentication exchange is interpreted by the server as the user name whose privileges the client is requesting.¶

Example:¶

  S: * OK [CAPABILITY IMAP4rev2 STARTTLS AUTH=GSSAPI]
   Capabilities
  C: A001 AUTHENTICATE GSSAPI
  S: +
  C: YIIB+wYJKoZIhvcSAQICAQBuggHqMIIB5qADAgEFoQMCAQ6iBw
     MFACAAAACjggEmYYIBIjCCAR6gAwIBBaESGxB1Lndhc2hpbmd0
     b24uZWR1oi0wK6ADAgEDoSQwIhsEaW1hcBsac2hpdmFtcy5jYW
     Mud2FzaGluZ3Rvbi5lZHWjgdMwgdCgAwIBAaEDAgEDooHDBIHA
     cS1GSa5b+fXnPZNmXB9SjL8Ollj2SKyb+3S0iXMljen/jNkpJX
     AleKTz6BQPzj8duz8EtoOuNfKgweViyn/9B9bccy1uuAE2HI0y
     C/PHXNNU9ZrBziJ8Lm0tTNc98kUpjXnHZhsMcz5Mx2GR6dGknb
     I0iaGcRerMUsWOuBmKKKRmVMMdR9T3EZdpqsBd7jZCNMWotjhi
     vd5zovQlFqQ2Wjc2+y46vKP/iXxWIuQJuDiisyXF0Y8+5GTpAL
     pHDc1/pIGmMIGjoAMCAQGigZsEgZg2on5mSuxoDHEA1w9bcW9n
     FdFxDKpdrQhVGVRDIzcCMCTzvUboqb5KjY1NJKJsfjRQiBYBdE
     NKfzK+g5DlV8nrw81uOcP8NOQCLR5XkoMHC0Dr/80ziQzbNqhx
     O6652Npft0LQwJvenwDI13YxpwOdMXzkWZN/XrEqOWp6GCgXTB
     vCyLWLlWnbaUkZdEYbKHBPjd8t/1x5Yg==
  S: + YGgGCSqGSIb3EgECAgIAb1kwV6ADAgEFoQMCAQ+iSzBJoAMC
     AQGiQgRAtHTEuOP2BXb9sBYFR4SJlDZxmg39IxmRBOhXRKdDA0
     uHTCOT9Bq3OsUTXUlk0CsFLoa8j+gvGDlgHuqzWHPSQg==
  C:
  S: + YDMGCSqGSIb3EgECAgIBAAD/////6jcyG4GE3KkTzBeBiVHe
     ceP2CWY0SR0fAQAgAAQEBAQ=
  C: YDMGCSqGSIb3EgECAgIBAAD/////3LQBHXTpFfZgrejpLlLImP
     wkhbfa2QteAQAgAG1yYwE=
  S: A001 OK GSSAPI authentication successful

The following example demonstrates the use of an initial response.¶

Example:¶

  S: * OK [CAPABILITY IMAP4rev2 STARTTLS AUTH=GSSAPI
   LOGINDISABLED] Server ready
  C: A01 STARTTLS
  S: A01 OK STARTTLS completed
  <TLS negotiation, further commands are under TLS layer>
  C: A02 CAPABILITY
  S: * CAPABILITY IMAP4rev2 AUTH=GSSAPI AUTH=PLAIN
  S: A02 OK CAPABILITY completed
  C: A03 AUTHENTICATE PLAIN dGVzdAB0ZXN0AHRlc3Q=
  S: A03 OK Success (tls protection)

Note that because the initial response is optional, the following negotiation (which does not use the initial response) is still valid and MUST be supported by the server:¶

  ... client connects to server and negotiates a TLS
      protection layer ...
  C: C01 CAPABILITY
  S: * CAPABILITY IMAP4rev2 AUTH=PLAIN
  S: C01 OK Completed
  C: A01 AUTHENTICATE PLAIN
  S: +
  C: dGVzdAB0ZXN0AHRlc3Q=
  S: A01 OK Success (tls protection)

Note that in the above example there is a space following the "+" from the server.¶

The following is an example authentication using the SASL EXTERNAL mechanism (defined in [SASL]) under a TLS protection layer and an empty initial response:¶

  ... client connects to server and negotiates a TLS
      protection layer ...
  C: C01 CAPABILITY
  S: * CAPABILITY IMAP4rev2 AUTH=PLAIN AUTH=EXTERNAL
  S: C01 OK Completed
  C: A01 AUTHENTICATE EXTERNAL =
  S: A01 OK Success (tls protection)

Note: The line breaks within server challenges and client responses are for editorial clarity and are not in real authenticators.¶

6.2.3. LOGIN Command

Arguments:

user name¶

password¶

Responses:

no specific responses for this command¶

Result:

OK -

login completed, now in authenticated state¶

NO -

login failure: user name or password rejected¶

BAD -

command unknown or arguments invalid¶

The LOGIN command identifies the client to the server and carries the plaintext password authenticating this user. The LOGIN command SHOULD NOT be used except as a last resort (after attempting and failing to authenticate using the AUTHENTICATE command one or more times), and it is recommended that client implementations have a means to disable any automatic use of the LOGIN command.¶

A server MAY include a CAPABILITY response code in the tagged OK response to a successful LOGIN command in order to send capabilities automatically. It is unnecessary for a client to send a separate CAPABILITY command if it recognizes these automatic capabilities.¶

Example:¶

  C: a001 LOGIN SMITH SESAME
  S: a001 OK LOGIN completed

Note: Use of the LOGIN command over an insecure network (such as the Internet) is a security risk, because anyone monitoring network traffic can obtain plaintext passwords. For that reason, clients MUST NOT use LOGIN on unsecure networks.¶

Unless the client is accessing IMAP service on an Implicit TLS port [RFC8314], the STARTTLS command has been negotiated, or some other mechanism that protects the session from password snooping has been provided, a server implementation MUST implement a configuration in which it advertises the LOGINDISABLED capability and does NOT permit the LOGIN command. Server sites SHOULD NOT use any configuration that permits the LOGIN command without such a protection mechanism against password snooping. A client implementation MUST NOT send a LOGIN command if the LOGINDISABLED capability is advertised.¶

6.3.1. ENABLE Command

Arguments:

capability names¶

Responses:

no specific responses for this command¶

Result:

OK -

Relevant capabilities enabled¶

BAD -

No arguments, or syntax error in an argument¶

Several IMAP extensions allow the server to return unsolicited responses specific to these extensions in certain circumstances. However, servers cannot send those unsolicited responses (with the exception of response codes (see Section 7.1) included in tagged or untagged OK/NO/BAD responses, which can always be sent) until they know that the clients support such extensions and thus will be able to correctly parse and process the extension response data.¶

The ENABLE command provides an explicit indication from the client that it supports particular extensions. It is designed such that the client can send a simple constant string with the extensions it supports, and the server will enable the shared subset that both support.¶

The ENABLE command takes a list of capability names and requests the server to enable the named extensions. Once enabled using ENABLE, each extension remains active until the IMAP connection is closed. For each argument, the server does the following:¶

• If the argument is not an extension known to the server, the server MUST ignore the argument.¶
• If the argument is an extension known to the server, and it is not specifically permitted to be enabled using ENABLE, the server MUST ignore the argument. (Note that knowing about an extension doesn't necessarily imply supporting that extension.)¶
• If the argument is an extension that is supported by the server and that needs to be enabled, the server MUST enable the extension for the duration of the connection. Note that once an extension is enabled, there is no way to disable it.¶

If the ENABLE command is successful, the server MUST send an untagged ENABLED response (Section 7.2.1), which includes all enabled extensions as specified above. The ENABLED response is sent even if no extensions were enabled.¶

Clients SHOULD only include extensions that need to be enabled by the server. For example, a client can enable IMAP4rev2-specific behavior when both IMAP4rev1 and IMAP4rev2 are advertised in the CAPABILITY response. Future RFCs may add to this list.¶

The ENABLE command is only valid in the authenticated state, before any mailbox is selected. Clients MUST NOT issue ENABLE once they SELECT/EXAMINE a mailbox; however, server implementations don't have to check that no mailbox is selected or was previously selected during the duration of a connection.¶

The ENABLE command can be issued multiple times in a session. It is additive; that is, "ENABLE a b", followed by "ENABLE c", is the same as a single command "ENABLE a b c". When multiple ENABLE commands are issued, each corresponding ENABLED response SHOULD only contain extensions enabled by the corresponding ENABLE command, i.e., for the above example, the ENABLED response to "ENABLE c" should not contain "a" or "b".¶

There are no limitations on pipelining ENABLE. For example, it is possible to send ENABLE and then immediately SELECT, or a LOGIN immediately followed by ENABLE.¶

The server MUST NOT change the CAPABILITY list as a result of executing ENABLE; that is, a CAPABILITY command issued right after an ENABLE command MUST list the same capabilities as a CAPABILITY command issued before the ENABLE command. This is demonstrated in the following example. Note that below "X-GOOD-IDEA" is a fictitious extension capability that can be ENABLED.¶

  C: t1 CAPABILITY
  S: * CAPABILITY IMAP4rev2 ID LITERAL+ X-GOOD-IDEA
  S: t1 OK foo
  C: t2 ENABLE CONDSTORE X-GOOD-IDEA
  S: * ENABLED X-GOOD-IDEA
  S: t2 OK foo
  C: t3 CAPABILITY
  S: * CAPABILITY IMAP4rev2 ID LITERAL+ X-GOOD-IDEA
  S: t3 OK foo again

In the following example, the client enables the Conditional Store (CONDSTORE) extension [RFC7162]:¶

  C: a1 ENABLE CONDSTORE
  S: * ENABLED CONDSTORE
  S: a1 OK Conditional Store enabled

6.3.9. LIST Command

Arguments (basic):

• reference name¶
• mailbox name with possible wildcards¶

Arguments (extended):

• selection options (OPTIONAL)¶
• reference name¶
• mailbox patterns¶
• return options (OPTIONAL)¶

Responses:

untagged responses: LIST¶

Result:

OK -

list completed¶

NO -

list failure: can't list that reference or mailbox name¶

BAD -

command unknown or arguments invalid¶

The LIST command returns a subset of mailbox names from the complete set of all mailbox names available to the client. Zero or more untagged LIST responses are returned, containing the name attributes, hierarchy delimiter, name, and possible extension information; see the description of the LIST response (Section 7.3.1) for more detail.¶

The LIST command SHOULD return its data quickly, without undue delay. For example, it should not go to excess trouble to calculate the \Marked or \Unmarked status or perform other processing; if each name requires 1 second of processing, then a list of 1200 names would take 20 minutes!¶

The extended LIST command, originally introduced in [RFC5258], provides capabilities beyond that of the original IMAP LIST command. The extended syntax is being used if one or more of the following conditions is true:¶

1. the first word after the command name begins with a parenthesis ("LIST selection options");¶
2. the second word after the command name begins with a parenthesis; and¶
3. the LIST command has more than 2 parameters ("LIST return options").¶

An empty ("" string) reference name argument indicates that the mailbox name is interpreted as by SELECT. The returned mailbox names MUST match the supplied mailbox name pattern(s). A non-empty reference name argument is the name of a mailbox or a level of mailbox hierarchy, and it indicates the context in which the mailbox name is interpreted. Clients SHOULD use the empty reference argument.¶

In the basic syntax only, an empty ("" string) mailbox name argument is a special request to return the hierarchy delimiter and the root name of the name given in the reference. The value returned as the root MAY be the empty string if the reference is non-rooted or is an empty string. In all cases, a hierarchy delimiter (or NIL if there is no hierarchy) is returned. This permits a client to get the hierarchy delimiter (or find out that the mailbox names are flat) even when no mailboxes by that name currently exist.¶

In the extended syntax, any mailbox name arguments that are empty strings are ignored. There is no special meaning for empty mailbox names when the extended syntax is used.¶

The reference and mailbox name arguments are interpreted into a canonical form that represents an unambiguous left-to-right hierarchy. The returned mailbox names will be in the interpreted form, which we call a "canonical LIST pattern": the canonical pattern constructed internally by the server from the reference and mailbox name arguments.¶

Note: The interpretation of the reference argument is implementation defined. It depends on whether the server implementation has a concept of the "current working directory" and leading "break out characters", which override the current working directory.¶

For example, on a server that exports a UNIX or NT file system, the reference argument contains the current working directory, and the mailbox name argument contains the name as interpreted in the current working directory.¶

If a server implementation has no concept of break out characters, the canonical form is normally the reference name appended with the mailbox name. Note that if the server implements the namespace convention (Section 5.1.2.1), "#" is a break out character and must be treated as such.¶

If the reference argument is not a level of mailbox hierarchy (that is, it is a \NoInferiors name), and/or the reference argument does not end with the hierarchy delimiter, it is interpreted as implementation dependent. For example, a reference of "foo/bar" and mailbox name of "rag/baz" could be interpreted as "foo/bar/rag/baz", "foo/barrag/baz", or "foo/rag/baz". A client SHOULD NOT use such a reference argument except at the explicit request of the user. A hierarchical browser MUST NOT make any assumptions about server interpretation of the reference unless the reference is a level of mailbox hierarchy AND ends with the hierarchy delimiter.¶

Any part of the reference argument that is included in the interpreted form SHOULD prefix the interpreted form. It SHOULD also be in the same form as the reference name argument. This rule permits the client to determine if the returned mailbox name is in the context of the reference argument or if something about the mailbox argument overrode the reference argument. Without this rule, the client would have to have knowledge of the server's naming semantics including what characters are "breakouts" that override a naming context.¶

Here are some examples of how references and mailbox names might be interpreted on a UNIX-based server:¶

The first three examples above demonstrate interpretations in the context of the reference argument. Note that "~smith/Mail" SHOULD NOT be transformed into something like "/u2/users/smith/Mail", or it would be impossible for the client to determine that the interpretation was in the context of the reference.¶

The character "*" is a wildcard and matches zero or more characters at this position. The character "%" is similar to "*", but it does not match a hierarchy delimiter. If the "%" wildcard is the last character of a mailbox name argument, matching levels of hierarchy are also returned. If these levels of hierarchy are not also selectable mailboxes, they are returned with the \Noselect mailbox name attribute (see the description of the LIST response (Section 7.3.1) for more details).¶

Any syntactically valid pattern that is not accepted by a server for any reason MUST be silently ignored, i.e., it results in no LIST responses, and the LIST command still returns a tagged OK response.¶

Selection options tell the server to limit the mailbox names that are selected by the LIST operation. If selection options are used, the mailboxes returned are those that match both the list of canonical LIST patterns and the selection options. Unless a particular selection option provides special rules, the selection options are cumulative: a mailbox that matches the mailbox patterns is selected only if it also matches all of the selection options. (An example of a selection option with special rules is the RECURSIVEMATCH option.)¶

Return options control what information is returned for each matched mailbox. Return options MUST NOT cause the server to report information about additional mailbox names other than those that match the canonical LIST patterns and selection options. If no return options are specified, the client is only expecting information about mailbox attributes. The server MAY return other information about the matched mailboxes, and clients MUST be able to handle that situation.¶

Initial selection options and return options are defined in the following subsections, and new ones will also be defined in extensions. Initial options defined in this document MUST be supported. Each non-initial option will be enabled by a capability string (one capability may enable multiple options), and a client MUST NOT send an option for which the server has not advertised support. A server MUST respond to options it does not recognize with a BAD response. The client SHOULD NOT specify any option more than once; however, if the client does this, the server MUST act as if it received the option only once. The order in which options are specified by the client is not significant.¶

In general, each selection option except RECURSIVEMATCH will have a corresponding return option with the same name. The REMOTE selection option is an anomaly in this regard and does not have a corresponding return option. That is because it expands, rather than restricts, the set of mailboxes that are returned. Future extensions to this specification should keep this parallelism in mind and define a pair of corresponding selection and return options.¶

Server implementations are permitted to "hide" otherwise accessible mailboxes from the wildcard characters, by preventing certain characters or names from matching a wildcard in certain situations. For example, a UNIX-based server might restrict the interpretation of "*" so that an initial "/" character does not match.¶

The special name INBOX is included in the output from LIST, if INBOX is supported by this server for this user and if the uppercase string "INBOX" matches the interpreted reference and mailbox name arguments with wildcards as described above. The criteria for omitting INBOX is whether SELECT INBOX will return a failure; it is not relevant whether the user's real INBOX resides on this or some other server.¶

  S: * LIST (\NonExistent) "." "INBOX.DeletedMailbox"

  S: * LIST () "/" "NewMailbox" ("OLDNAME" ("OldMailbox"))

  C: A101 LIST "" ""
  S: * LIST (\Noselect) "/" ""
  S: A101 OK LIST Completed
  C: A102 LIST #news.comp.mail.misc ""
  S: * LIST (\Noselect) "." #news.
  S: A102 OK LIST Completed
  C: A103 LIST /usr/staff/jones ""
  S: * LIST (\Noselect) "/" /
  S: A103 OK LIST Completed
  C: A202 LIST ~/Mail/ %
  S: * LIST (\Noselect) "/" ~/Mail/foo
  S: * LIST () "/" ~/Mail/meetings
  S: A202 OK LIST completed

6.3.11. STATUS Command

Arguments:

mailbox name¶

status data item names¶

Responses:

REQUIRED untagged responses:

STATUS¶

Result:

OK -

status completed¶

NO -

status failure: no status for that name¶

BAD -

command unknown or arguments invalid¶

The STATUS command requests the status of the indicated mailbox. It does not change the currently selected mailbox, nor does it affect the state of any messages in the queried mailbox.¶

The STATUS command provides an alternative to opening a second IMAP4rev2 connection and doing an EXAMINE command on a mailbox to query that mailbox's status without deselecting the current mailbox in the first IMAP4rev2 connection.¶

Unlike the LIST command, the STATUS command is not guaranteed to be fast in its response. Under certain circumstances, it can be quite slow. In some implementations, the server is obliged to open the mailbox as "read-only" internally to obtain certain status information. Also unlike the LIST command, the STATUS command does not accept wildcards.¶

Note: The STATUS command is intended to access the status of mailboxes other than the currently selected mailbox. Because the STATUS command can cause the mailbox to be opened internally, and because this information is available by other means on the selected mailbox, the STATUS command SHOULD NOT be used on the currently selected mailbox. However, servers MUST be able to execute the STATUS command on the selected mailbox. (This might also implicitly happen when the STATUS return option is used in a LIST command.)¶

The STATUS command MUST NOT be used as a "check for new messages in the selected mailbox" operation (refer to Sections 7 and 7.4.1 for more information about the proper method for new message checking).¶

STATUS SIZE (see below) can take a significant amount of time, depending upon server implementation. Clients should use STATUS SIZE cautiously.¶

The currently defined status data items that can be requested are:¶

MESSAGES

The number of messages in the mailbox.¶

UIDNEXT

The next unique identifier value of the mailbox. Refer to Section 2.3.1.1 for more information.¶

UIDVALIDITY

The unique identifier validity value of the mailbox. Refer to Section 2.3.1.1 for more information.¶

UNSEEN

The number of messages that do not have the \Seen flag set.¶

DELETED

The number of messages that have the \Deleted flag set.¶

SIZE

The total size of the mailbox in octets. This is not strictly required to be an exact value, but it MUST be equal to or greater than the sum of the values of the RFC822.SIZE FETCH message data items (see Section 6.4.5) of all messages in the mailbox.¶

Example:¶

  C: A042 STATUS blurdybloop (UIDNEXT MESSAGES)
  S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
  S: A042 OK STATUS completed

6.3.13. IDLE Command

Arguments:

none¶

Responses:

continuation data will be requested; the client sends the continuation data "DONE" to end the command¶

Result:

OK -

IDLE completed after client sent "DONE"¶

NO -

failure: the server will not allow the IDLE command at this time¶

BAD -

command unknown or arguments invalid¶

Without the IDLE command, a client would need to poll the server for changes to the selected mailbox (new mail, deletions, and flag changes). It's often more desirable to have the server transmit updates to the client in real time. This allows a user to see new mail immediately. The IDLE command allows a client to tell the server that it's ready to accept such real-time updates.¶

The IDLE command is sent from the client to the server when the client is ready to accept unsolicited update messages. The server requests a response to the IDLE command using the continuation ("+") response. The IDLE command remains active until the client responds to the continuation, and as long as an IDLE command is active, the server is now free to send untagged EXISTS, EXPUNGE, FETCH, and other responses at any time. If the server chooses to send unsolicited FETCH responses, they MUST include a UID FETCH item.¶

The IDLE command is terminated by the receipt of a "DONE" continuation from the client; such response satisfies the server's continuation request. At that point, the server MAY send any remaining queued untagged responses and then MUST immediately send the tagged response to the IDLE command and prepare to process other commands. As for other commands, the processing of any new command may cause the sending of unsolicited untagged responses, subject to the ambiguity limitations. The client MUST NOT send a command while the server is waiting for the DONE, since the server will not be able to distinguish a command from a continuation.¶

The server MAY consider a client inactive if it has an IDLE command running, and if such a server has an inactivity timeout, it MAY log the client off implicitly at the end of its timeout period. Because of that, clients using IDLE are advised to terminate IDLE and reissue it at least every 29 minutes to avoid being logged off. This still allows a client to receive immediate mailbox updates even though it need only "poll" at half hour intervals.¶

Example:¶

  C: A001 SELECT INBOX
  S: * FLAGS (\Deleted \Seen \Flagged)
  S: * OK [PERMANENTFLAGS (\Deleted \Seen \Flagged)] Limited
  S: * 3 EXISTS
  S: * OK [UIDVALIDITY 1]
  S: * OK [UIDNEXT 1]
  S: * LIST () "/" INBOX
  S: A001 OK [READ-WRITE] SELECT completed
  C: A002 IDLE
  S: + idling
  ...time passes; new mail arrives...
  S: * 4 EXISTS
  C: DONE
  S: A002 OK IDLE terminated
  ...another client expunges message 2 now...
  C: A003 FETCH 4 ALL
  S: * 4 FETCH (...)
  S: A003 OK FETCH completed
  C: A004 IDLE
  S: * 2 EXPUNGE
  S: * 3 EXISTS
  S: + idling
  ...time passes; another client expunges message 3...
  S: * 3 EXPUNGE
  S: * 2 EXISTS
  ...time passes; new mail arrives...
  S: * 3 EXISTS
  C: DONE
  S: A004 OK IDLE terminated
  C: A005 FETCH 3 ALL
  S: * 3 FETCH (...)
  S: A005 OK FETCH completed
  C: A006 IDLE

6.4.5. FETCH Command

Arguments:

sequence set¶

message data item names or macro¶

Responses:

untagged responses:

FETCH¶

Result:

OK -

fetch completed¶

NO -

fetch error: can't fetch that data¶

BAD -

command unknown or arguments invalid¶

The FETCH command retrieves data associated with a message in the mailbox. The data items to be fetched can be either a single atom or a parenthesized list.¶

Most data items, identified in the formal syntax (Section 9) under the msg-att-static rule, are static and MUST NOT change for any particular message. Other data items, identified in the formal syntax under the msg-att-dynamic rule, MAY change either as a result of a STORE command or due to external events.¶

• For example, if a client receives an ENVELOPE for a message when it already knows the envelope, it can safely ignore the newly transmitted envelope.¶

There are three macros that specify commonly used sets of data items and can be used instead of data items. A macro must be used by itself and not in conjunction with other macros or data items.¶

ALL

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)¶

FAST

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE)¶

FULL

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY)¶

Several data items reference "section" or "section-binary". See Section 6.4.5.1 for their detailed definition.¶

The currently defined data items that can be fetched are:¶

BINARY[<section-binary>]<<partial>>

Requests that the specified section be transmitted after performing decoding of the section's Content-Transfer-Encoding.¶

The <partial> argument, if present, requests that a subset of the data be returned. The semantics of a partial FETCH BINARY command are the same as for a partial FETCH BODY command, with the exception that the <partial> arguments refer to the DECODED section data.¶

Note that this data item can only be requested for leaf body parts: those that have media types other than multipart/*, message/rfc822, or message/global.¶

BINARY.PEEK[<section-binary>]<<partial>>

An alternate form of BINARY[<section-binary>] that does not implicitly set the \Seen flag.¶

BINARY.SIZE[<section-binary>]

Requests the decoded size of the section (i.e., the size to expect in response to the corresponding FETCH BINARY request).¶

Note: client authors are cautioned that this might be an expensive operation for some server implementations. Needlessly issuing this request could result in degraded performance due to servers having to calculate the value every time the request is issued.¶

Note that this data item can only be requested for leaf body parts: those that have media types other than multipart/*, message/rfc822, or message/global.¶

BODY

Non-extensible form of BODYSTRUCTURE.¶

BODY[<section>]<<partial>>

The text of a particular body section. If BODY[] is specified (the section specification is omitted), the FETCH is requesting the [RFC5322] expression of the entire message.¶

It is possible to fetch a substring of the designated text. This is done by appending an open angle bracket ("<"), the octet position of the first desired octet, a period, the maximum number of octets desired, and a close angle bracket (">") to the part specifier. If the starting octet is beyond the end of the text, an empty string is returned.¶

Any partial fetch that attempts to read beyond the end of the text is truncated as appropriate. A partial fetch that starts at octet 0 is returned as a partial fetch, even if this truncation happened.¶

Note: This means that BODY[]<0.2048> of a 1500-octet message will return BODY[]<0> with a literal of size 1500, not BODY[].¶

Note: A substring fetch of a HEADER.FIELDS or HEADER.FIELDS.NOT part specifier is calculated after subsetting the header.¶

The \Seen flag is implicitly set; if this causes the flags to change, they SHOULD be included as part of the FETCH responses.¶

BODY.PEEK[<section>]<<partial>>

An alternate form of BODY[<section>] that does not implicitly set the \Seen flag.¶

BODYSTRUCTURE

The [MIME-IMB] body structure of the message. This is computed by the server by parsing the [MIME-IMB] header fields in the [RFC5322] header and [MIME-IMB] headers. See Section 7.5.2 for more details.¶

ENVELOPE

The envelope structure of the message. This is computed by the server by parsing the [RFC5322] header into the component parts, defaulting various fields as necessary. See Section 7.5.2 for more details.¶

FLAGS

The flags that are set for this message.¶

INTERNALDATE

The internal date of the message.¶

RFC822.SIZE

The size of the message, as defined in Section 2.3.4.¶

UID

The unique identifier for the message.¶

Example:¶

  C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
  S: * 2 FETCH ....
  S: * 3 FETCH ....
  S: * 4 FETCH ....
  S: A654 OK FETCH completed

  HEADER     ([RFC5322] header of the message)
  TEXT       ([RFC5322] text body of the message) MULTIPART/MIXED
  1          TEXT/PLAIN
  2          APPLICATION/OCTET-STREAM
  3          MESSAGE/RFC822
  3.HEADER   ([RFC5322] header of the message)
  3.TEXT     ([RFC5322] text body of the message) MULTIPART/MIXED
  3.1        TEXT/PLAIN
  3.2        APPLICATION/OCTET-STREAM
  4          MULTIPART/MIXED
  4.1        IMAGE/GIF
  4.1.MIME   ([MIME-IMB] header for the IMAGE/GIF)
  4.2        MESSAGE/RFC822
  4.2.HEADER ([RFC5322] header of the message)
  4.2.TEXT   ([RFC5322] text body of the message) MULTIPART/MIXED
  4.2.1      TEXT/PLAIN
  4.2.2      MULTIPART/ALTERNATIVE
  4.2.2.1    TEXT/PLAIN
  4.2.2.2    TEXT/RICHTEXT

6.4.7. COPY Command

Arguments:

sequence set¶

mailbox name¶

Responses:

no specific responses for this command¶

Result:

OK -

copy completed¶

NO -

copy error: can't copy those messages or to that name¶

BAD -

command unknown or arguments invalid¶

The COPY command copies the specified message(s) to the end of the specified destination mailbox. The flags and internal date of the message(s) SHOULD be preserved in the copy.¶

If the destination mailbox does not exist, a server MUST return an error. It MUST NOT automatically create the mailbox. Unless it is certain that the destination mailbox can not be created, the server MUST send the response code "[TRYCREATE]" as the prefix of the text of the tagged NO response. This gives a hint to the client that it can attempt a CREATE command and retry the COPY if the CREATE is successful.¶

If the COPY command is unsuccessful for any reason, server implementations MUST restore the destination mailbox to its state before the COPY attempt (other than possibly incrementing UIDNEXT), i.e., partial copy MUST NOT be done.¶

On successful completion of a COPY, the server returns a COPYUID response code (see Section 7.1). Two exceptions to this requirement are listed below.¶

In the case of a mailbox that has permissions set so that the client can COPY to the mailbox, but not SELECT or EXAMINE it, the server MUST NOT send a COPYUID response code as it would disclose information about the mailbox.¶

In the case of a mailbox that has UIDNOTSTICKY status (see Section 7.1), the server MAY omit the COPYUID response code as it is not meaningful.¶

Example:¶

  C: A003 COPY 2:4 MEETING
  S: A003 OK [COPYUID 38505 304,319:320 3956:3958] COPY completed

6.4.9. UID Command

Arguments:

command name¶

command arguments¶

Responses:

untagged responses:

FETCH, ESEARCH, EXPUNGE¶

Result:

OK -

UID command completed¶

NO -

UID command error¶

BAD -

command unknown or arguments invalid¶

The UID command has three forms. In the first form, it takes as its arguments a COPY, MOVE, FETCH, or STORE command with arguments appropriate for the associated command. However, the numbers in the sequence-set argument are unique identifiers instead of message sequence numbers. Sequence-set ranges are permitted, but there is no guarantee that unique identifiers will be contiguous.¶

A non-existent unique identifier is ignored without any error message generated. Thus, it is possible for a UID FETCH command to return an OK without any data or a UID COPY, UID MOVE, or UID STORE to return an OK without performing any operations.¶

In the second form, the UID command takes an EXPUNGE command with an extra parameter that specifies a sequence set of UIDs to operate on. The UID EXPUNGE command permanently removes all messages that have both the \Deleted flag set and a UID that is included in the specified sequence set from the currently selected mailbox. If a message either does not have the \Deleted flag set or has a UID that is not included in the specified sequence set, it is not affected.¶

UID EXPUNGE is particularly useful for disconnected use clients. By using UID EXPUNGE instead of EXPUNGE when resynchronizing with the server, the client can ensure that it does not inadvertently remove any messages that have been marked as \Deleted by other clients between the time that the client was last connected and the time the client resynchronizes.¶

Example:¶

  C: A003 UID EXPUNGE 3000:3002
  S: * 3 EXPUNGE
  S: * 3 EXPUNGE
  S: * 3 EXPUNGE
  S: A003 OK UID EXPUNGE completed

In the third form, the UID command takes a SEARCH command with SEARCH command arguments. The interpretation of the arguments is the same as with SEARCH; however, the numbers returned in an ESEARCH response for a UID SEARCH command are unique identifiers instead of message sequence numbers. Also, the corresponding ESEARCH response MUST include the UID indicator. For example, the command UID SEARCH 1:100 UID 443:557 returns the unique identifiers corresponding to the intersection of two sequence sets, the message sequence number range 1:100, and the UID range 443:557.¶

Note: in the above example, the UID range 443:557 appears. The same comment about a non-existent unique identifier being ignored without any error message also applies here. Hence, even if neither UID 443 or 557 exist, this range is valid and would include an existing UID 495.¶

Also note that a UID range of 559:* always includes the UID of the last message in the mailbox, even if 559 is higher than any assigned UID value. This is because the contents of a range are independent of the order of the range endpoints. Thus, any UID range with * as one of the endpoints indicates at least one message (the message with the highest numbered UID), unless the mailbox is empty.¶

The number after the "*" in an untagged FETCH or EXPUNGE response is always a message sequence number, not a unique identifier, even for a UID command response. However, server implementations MUST implicitly include the UID message data item as part of any FETCH response caused by a UID command, regardless of whether a UID was specified as a message data item to the FETCH.¶

Note: The rule about including the UID message data item as part of a FETCH response primarily applies to the UID FETCH and UID STORE commands, including a UID FETCH command that does not include UID as a message data item. Although it is unlikely that the other UID commands will cause an untagged FETCH, this rule applies to these commands as well.¶

Example:¶

  C: A999 UID FETCH 4827313:4828442 FLAGS
  S: * 23 FETCH (FLAGS (\Seen) UID 4827313)
  S: * 24 FETCH (FLAGS (\Seen) UID 4827943)
  S: * 25 FETCH (FLAGS (\Seen) UID 4828442)
  S: A999 OK UID FETCH completed

7.3.1. LIST Response

Contents:

• name attributes¶
• hierarchy delimiter¶
• name¶
• OPTIONAL extension data¶

The LIST response occurs as a result of a LIST command. It returns a single name that matches the LIST specification. There can be multiple LIST responses for a single LIST command.¶

The following base mailbox name attributes are defined:¶

\NonExistent

The "\NonExistent" attribute indicates that a mailbox name does not refer to an existing mailbox. Note that this attribute is not meaningful by itself, as mailbox names that match the canonical LIST pattern but don't exist must not be returned unless one of the two conditions listed below is also satisfied:¶

1. The mailbox name also satisfies the selection criteria (for example, it is subscribed and the "SUBSCRIBED" selection option has been specified).¶
2. "RECURSIVEMATCH" has been specified, and the mailbox name has at least one descendant mailbox name that does not match the LIST pattern and does match the selection criteria.¶

In practice, this means that the "\NonExistent" attribute is usually returned with one or more of "\Subscribed", "\Remote", "\HasChildren", or the CHILDINFO extended data item.¶

The "\NonExistent" attribute implies "\NoSelect".¶

\Noinferiors

It is not possible for any child levels of hierarchy to exist under this name; no child levels exist now and none can be created in the future.¶

\Noselect

It is not possible to use this name as a selectable mailbox.¶

\HasChildren

The presence of this attribute indicates that the mailbox has child mailboxes. A server SHOULD NOT set this attribute if there are child mailboxes and the user does not have permission to access any of them. In this case, \HasNoChildren SHOULD be used. In many cases, however, a server may not be able to efficiently compute whether a user has access to any child mailboxes. Note that even though the \HasChildren attribute for a mailbox must be correct at the time of processing the mailbox, a client must be prepared to deal with a situation when a mailbox is marked with the \HasChildren attribute, but no child mailbox appears in the response to the LIST command. This might happen, for example, due to child mailboxes being deleted or made inaccessible to the user (using access control) by another client before the server is able to list them.¶

\HasNoChildren

The presence of this attribute indicates that the mailbox has NO child mailboxes that are accessible to the currently authenticated user.¶

\Marked

The mailbox has been marked "interesting" by the server; the mailbox probably contains messages that have been added since the last time the mailbox was selected.¶

\Unmarked

The mailbox does not contain any additional messages since the last time the mailbox was selected.¶

\Subscribed

The mailbox name was subscribed to using the SUBSCRIBE command.¶

\Remote

The mailbox is a remote mailbox.¶

It is an error for the server to return both a \HasChildren and a \HasNoChildren attribute in the same LIST response. A client that encounters a LIST response with both \HasChildren and \HasNoChildren attributes present should act as if both are absent in the LIST response.¶

Note: the \HasNoChildren attribute should not be confused with the \NoInferiors attribute, which indicates that no child mailboxes exist now and none can be created in the future.¶

If it is not feasible for the server to determine whether or not the mailbox is "interesting", the server SHOULD NOT send either \Marked or \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked, and \Noselect for a single mailbox, and it MAY send none of these.¶

In addition to the base mailbox name attributes defined above, an IMAP server MAY also include any or all of the following attributes that denote "role" (or "special-use") of a mailbox. These attributes are included along with base attributes defined above. A given mailbox may have none, one, or more than one of these attributes. In some cases, a special use is advice to a client about what to put in that mailbox. In other cases, it's advice to a client about what to expect to find there.¶

\All

This mailbox presents all messages in the user's message store. Implementations MAY omit some messages, such as, perhaps, those in \Trash and \Junk. When this special use is supported, it is almost certain to represent a virtual mailbox.¶

\Archive

This mailbox is used to archive messages. The meaning of an "archival" mailbox is server dependent; typically, it will be used to get messages out of the inbox, or otherwise keep them out of the user's way, while still making them accessible.¶

\Drafts

This mailbox is used to hold draft messages -- typically, messages that are being composed but have not yet been sent. In some server implementations, this might be a virtual mailbox, containing messages from other mailboxes that are marked with the "\Draft" message flag. Alternatively, this might just be advice that a client put drafts here.¶

\Flagged

This mailbox presents all messages marked in some way as "important". When this special use is supported, it is likely to represent a virtual mailbox collecting messages (from other mailboxes) that are marked with the "\Flagged" message flag.¶

\Junk

This mailbox is where messages deemed to be junk mail are held. Some server implementations might put messages here automatically. Alternatively, this might just be advice to a client-side spam filter.¶

\Sent

This mailbox is used to hold copies of messages that have been sent. Some server implementations might put messages here automatically. Alternatively, this might just be advice that a client save sent messages here.¶

\Trash

This mailbox is used to hold messages that have been deleted or marked for deletion. In some server implementations, this might be a virtual mailbox, containing messages from other mailboxes that are marked with the "\Deleted" message flag. Alternatively, this might just be advice that a client that chooses not to use the IMAP "\Deleted" model should use as its trash location. In server implementations that strictly expect the IMAP "\Deleted" model, this special use is likely not to be supported.¶

All special-use attributes are OPTIONAL, and any given server or message store may support any combination of the attributes, or none at all. In most cases, there will likely be at most one mailbox with a given attribute for a given user, but in some server or message store implementations, it might be possible for multiple mailboxes to have the same special-use attribute.¶

Special-use attributes are likely to be user specific. User Adam might share his \Sent mailbox with user Barb, but that mailbox is unlikely to also serve as Barb's \Sent mailbox.¶

Other mailbox name attributes can be found in the "IMAP Mailbox Name Attributes" registry [IMAP-MAILBOX-NAME-ATTRS-REG].¶

The hierarchy delimiter is a character used to delimit levels of hierarchy in a mailbox name. A client can use it to create child mailboxes and to search higher or lower levels of naming hierarchy. All children of a top-level hierarchy node MUST use the same separator character. A NIL hierarchy delimiter means that no hierarchy exists; the name is a "flat" name.¶

The name represents an unambiguous left-to-right hierarchy and MUST be valid for use as a reference in LIST command. Unless \Noselect or \NonExistent is indicated, the name MUST also be valid as an argument for commands, such as SELECT, that accept mailbox names.¶

The name might be followed by an OPTIONAL series of extended fields, a parenthesized list of tagged data (also referred to as an "extended data item"). The first element of an extended field is a string, which identifies the type of data. [RFC5258] specifies requirements on string registration (which are called "tags"; such tags are not to be confused with IMAP command tags); in particular, it states that "Tags MUST be registered with IANA". This document doesn't change that. See Section 9.5 of [RFC5258] for the registration template. The server MAY return data in the extended fields that was not directly solicited by the client in the corresponding LIST command. For example, the client can enable extra extended fields by using another IMAP extension that makes use of the extended LIST responses. The client MUST ignore all extended fields it doesn't recognize.¶

Example:¶

  S: * LIST (\Noselect) "/" ~/Mail/foo

Example:¶

  S: * LIST (\Marked) ":" Tables (tablecloth (("edge" "lacy")
      ("color" "red")) Sample "text")
  S: * LIST () ":" Tables:new (tablecloth ("edge" "lacy")
      Sample ("text" "more text"))

7.3.5. FLAGS Response

Contents:

flag parenthesized list¶

The FLAGS response occurs as a result of a SELECT or EXAMINE command. The flag parenthesized list identifies the flags (at a minimum, the system-defined flags) that are applicable for this mailbox. Flags other than the system flags can also exist, depending on server implementation.¶

The update from the FLAGS response MUST be remembered by the client.¶

Example:¶

  S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)

7.4.1. EXISTS Response

Contents:

none¶

The EXISTS response reports the number of messages in the mailbox. This response occurs as a result of a SELECT or EXAMINE command and if the size of the mailbox changes (e.g., new messages).¶

The update from the EXISTS response MUST be remembered by the client.¶

Example:¶

  S: * 23 EXISTS

7.5.1. EXPUNGE Response

Contents:

none¶

The EXPUNGE response reports that the specified message sequence number has been permanently removed from the mailbox. The message sequence number for each successive message in the mailbox is immediately decremented by 1, and this decrement is reflected in message sequence numbers in subsequent responses (including other untagged EXPUNGE responses).¶

The EXPUNGE response also decrements the number of messages in the mailbox; it is not necessary to send an EXISTS response with the new value.¶

As a result of the immediate decrement rule, message sequence numbers that appear in a set of successive EXPUNGE responses depend upon whether the messages are removed starting from lower numbers to higher numbers, or from higher numbers to lower numbers. For example, if the last 5 messages in a 9-message mailbox are expunged, a "lower to higher" server will send five untagged EXPUNGE responses for message sequence number 5, whereas a "higher to lower" server will send successive untagged EXPUNGE responses for message sequence numbers 9, 8, 7, 6, and 5.¶

An EXPUNGE response MUST NOT be sent when no command is in progress, nor while responding to a FETCH, STORE, or SEARCH command. This rule is necessary to prevent a loss of synchronization of message sequence numbers between client and server. A command is not "in progress" until the complete command has been received; in particular, a command is not "in progress" during the negotiation of command continuation.¶

Note: UID FETCH, UID STORE, and UID SEARCH are different commands from FETCH, STORE, and SEARCH. An EXPUNGE response MAY be sent during a UID command.¶

The update from the EXPUNGE response MUST be remembered by the client.¶

Example:¶

  S: * 44 EXPUNGE

7.5.2. FETCH Response

Contents:

message data¶

The FETCH response returns data about a message to the client. The data are pairs of data item names, and their values are in parentheses. This response occurs as the result of a FETCH or STORE command, as well as by a unilateral server decision (e.g., flag updates).¶

The current data items are:¶

BINARY[<section-binary>]<<number>>

An <nstring> or <literal8> expressing the content of the specified section after removing any encoding specified in the corresponding Content-Transfer-Encoding header field. If <number> is present, it refers to the offset within the DECODED section data.¶

If the domain of the decoded data is "8bit" and the data does not contain the NUL octet, the server SHOULD return the data in a <string> instead of a <literal8>; this allows the client to determine if the "8bit" data contains the NUL octet without having to explicitly scan the data stream for NULs.¶

Messaging clients and servers have been notoriously lax in their adherence to the Internet CRLF convention for terminating lines of textual data (text/* media types) in Internet protocols. When sending data in a BINARY[...] FETCH data item, servers MUST ensure that textual line-oriented sections are always transmitted using the IMAP CRLF line termination syntax, regardless of the underlying storage representation of the data on the server.¶

If the server does not know how to decode the section's Content-Transfer-Encoding, it MUST fail the request and issue a "NO" response that contains the "UNKNOWN-CTE" response code.¶

BINARY.SIZE[<section-binary>]

The size of the section after removing any encoding specified in the corresponding Content-Transfer-Encoding header field. The value returned MUST match the size of the <nstring> or <literal8> that will be returned by the corresponding FETCH BINARY request.¶

If the server does not know how to decode the section's Content-Transfer-Encoding, it MUST fail the request and issue a "NO" response that contains the "UNKNOWN-CTE" response code.¶

BODY

A form of BODYSTRUCTURE without extension data.¶

BODY[<section>]<<origin octet>>

A string expressing the body contents of the specified section. The string SHOULD be interpreted by the client according to the content transfer encoding, body type, and subtype.¶

If the origin octet is specified, this string is a substring of the entire body contents, starting at that origin octet. This means that BODY[]<0> MAY be truncated, but BODY[] is NEVER truncated.¶

Note: The origin octet facility MUST NOT be used by a server in a FETCH response unless the client specifically requested it by means of a FETCH of a BODY[<section>]<<partial>> data item.¶

8-bit textual data is permitted if a [CHARSET] identifier is part of the body parameter parenthesized list for this section. Note that headers (part specifiers HEADER or MIME, or the header portion of a MESSAGE/RFC822 or MESSAGE/GLOBAL part) MAY be in UTF-8. Note also that the [RFC5322] delimiting blank line between the header and the body is not affected by header-line subsetting; the blank line is always included as part of the header data, except in the case of a message that has no body and no blank line.¶

Non-textual data such as binary data MUST be transfer encoded into a textual form, such as base64, prior to being sent to the client. To derive the original binary data, the client MUST decode the transfer-encoded string.¶

BODYSTRUCTURE

A parenthesized list that describes the [MIME-IMB] body structure of a message. This is computed by the server by parsing the [MIME-IMB] header fields, defaulting various fields as necessary.¶

For example, a simple text message of 48 lines and 2279 octets can have a body structure of:¶

   ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 2279 48)

¶

Multiple parts are indicated by parenthesis nesting. Instead of a body type as the first element of the parenthesized list, there is a sequence of one or more nested body structures. The second element of the parenthesized list is the multipart subtype (mixed, digest, parallel, alternative, etc.).¶

For example, a two-part message consisting of a text and a base64-encoded text attachment can have a body structure of:¶

   (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)
    ("TEXT" "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff")
    "<960723163407.20117h@cac.washington.edu>" "Compiler diff"
    "BASE64" 4554 73) "MIXED")

¶

Extension data follows the multipart subtype. Extension data is never returned with the BODY fetch but can be returned with a BODYSTRUCTURE fetch. Extension data, if present, MUST be in the defined order. The extension data of a multipart body part are in the following order:¶

body parameter parenthesized list

A parenthesized list of attribute/value pairs (e.g., ("foo" "bar" "baz" "rag") where "bar" is the value of "foo", and "rag" is the value of "baz") as defined in [MIME-IMB]. Servers SHOULD decode parameter-value continuations and parameter-value character sets as described in [RFC2231], for example, if the message contains parameters "baz*0", "baz*1", and "baz*2", the server should decode them per [RFC2231], concatenate, and return the resulting value as a parameter "baz". Similarly, if the message contains parameters "foo*0*" and "foo*1*", the server should decode them per [RFC2231], convert to UTF-8, concatenate, and return the resulting value as a parameter "foo*".¶

body disposition

A parenthesized list, consisting of a disposition type string, followed by a parenthesized list of disposition attribute/value pairs as defined in [DISPOSITION]. Servers SHOULD decode parameter-value continuations as described in [RFC2231].¶

body language

A string or parenthesized list giving the body language value as defined in [LANGUAGE-TAGS].¶

body location

A string giving the body content URI as defined in [LOCATION].¶

Any following extension data are not yet defined in this version of the protocol. Such extension data can consist of zero or more NILs, strings, numbers, or potentially nested parenthesized lists of such data. Client implementations that do a BODYSTRUCTURE fetch MUST be prepared to accept such extension data. Server implementations MUST NOT send such extension data until it has been defined by a revision of this protocol.¶

The basic fields of a non-multipart body part are in the following order:¶

body type

A string giving the content media-type name as defined in [MIME-IMB].¶

body subtype

A string giving the content subtype name as defined in [MIME-IMB].¶

body parameter parenthesized list

A parenthesized list of attribute/value pairs (e.g., ("foo" "bar" "baz" "rag") where "bar" is the value of "foo", and "rag" is the value of "baz") as defined in [MIME-IMB].¶

body id

A string giving the Content-ID header field value as defined in Section 7 of [MIME-IMB].¶

body description

A string giving the Content-Description header field value as defined in Section 8 of [MIME-IMB].¶

body encoding

A string giving the content transfer encoding as defined in Section 6 of [MIME-IMB].¶

body size

A number giving the size of the body in octets. Note that this size is the size in its transfer encoding and not the resulting size after any decoding.¶

A body type of type MESSAGE and subtype RFC822 contains, immediately after the basic fields, the envelope structure, body structure, and size in text lines of the encapsulated message.¶

A body type of type TEXT contains, immediately after the basic fields, the size of the body in text lines. Note that this size is the size in its content transfer encoding and not the resulting size after any decoding.¶

Extension data follows the basic fields and the type-specific fields listed above. Extension data is never returned with the BODY fetch but can be returned with a BODYSTRUCTURE fetch. Extension data, if present, MUST be in the defined order.¶

The extension data of a non-multipart body part are in the following order:¶

body MD5

A string giving the body MD5 value as defined in [MD5].¶

body disposition

A parenthesized list with the same content and function as the body disposition for a multipart body part.¶

body language

A string or parenthesized list giving the body language value as defined in [LANGUAGE-TAGS].¶

body location

A string giving the body content URI as defined in [LOCATION].¶

Any following extension data are not yet defined in this version of the protocol and would be as described above under multipart extension data.¶

ENVELOPE

A parenthesized list that describes the envelope structure of a message. This is computed by the server by parsing the [RFC5322] header into the component parts, defaulting various fields as necessary.¶

The fields of the envelope structure are in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id. The date, subject, in-reply-to, and message-id fields are strings. The from, sender, reply-to, to, cc, and bcc fields are parenthesized lists of address structures.¶

An address structure is a parenthesized list that describes an electronic mail address. The fields of an address structure are in the following order: display name, [SMTP] at-domain-list (source route and obs-route ABNF production from [RFC5322]), mailbox name (local-part ABNF production from [RFC5322]), and hostname.¶

[RFC5322] group syntax is indicated by a special form of address structure in which the hostname field is NIL. If the mailbox name field is also NIL, this is an end-of-group marker (semicolon in RFC 822 syntax). If the mailbox name field is non-NIL, this is the start of a group marker, and the mailbox name field holds the group name phrase.¶

If the Date, Subject, In-Reply-To, and Message-ID header fields are absent in the [RFC5322] header, the corresponding member of the envelope is NIL; if these header fields are present but empty, the corresponding member of the envelope is the empty string.¶

Note: some servers may return a NIL envelope member in the "present but empty" case. Clients SHOULD treat NIL and the empty string as identical.¶

Note: [RFC5322] requires that all messages have a valid Date header field. Therefore, for a well-formed message, the date member in the envelope cannot be NIL or the empty string. However, it can be NIL for a malformed or draft message.¶

Note: [RFC5322] requires that the In-Reply-To and Message-ID header fields, if present, have non-empty content. Therefore, for a well-formed message, the in-reply-to and message-id members in the envelope cannot be the empty string. However, they can still be the empty string for a malformed message.¶

If the From, To, Cc, and Bcc header fields are absent in the [RFC5322] header, or are present but empty, the corresponding member of the envelope is NIL.¶

If the Sender or Reply-To header fields are absent in the [RFC5322] header, or are present but empty, the server sets the corresponding member of the envelope to be the same value as the from member (the client is not expected to know how to do this).¶

Note: [RFC5322] requires that all messages have a valid From header field. Therefore, for a well-formed message, the from, sender, and reply-to members in the envelope cannot be NIL. However, they can be NIL for a malformed or draft message.¶

FLAGS

A parenthesized list of flags that are set for this message.¶

INTERNALDATE

A string representing the internal date of the message.¶

RFC822.SIZE

A number expressing the size of a message, as described in Section 2.3.4.¶

UID

A number expressing the unique identifier of the message.¶

If the server chooses to send unsolicited FETCH responses, they MUST include UID FETCH item. Note that this is a new requirement when compared to [RFC3501].¶

Example:¶

  S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827 UID 447)