Rfc 1730

7/29/2019 Rfc 1730

1/78

Network Working Group M. CrispinRequest for Comments: 1730 University of WashingtonCategory: Standards Track December 1994

INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4

Status of this Memo

This document specifies an Internet standards track protocol for theInternet community, and requests discussion and suggestions forimprovements. Please refer to the current edition of the "InternetOfficial Protocol Standards" (STD 1) for the standardization stateand status of this protocol. Distribution of this memo is unlimited.

Abstract

The Internet Message Access Protocol, Version 4 (IMAP4) allows aclient to access and manipulate electronic mail messages on a server.IMAP4 permits manipulation of remote message folders, called"mailboxes", in a way that is functionally equivalent to localmailboxes. IMAP4 also provides the capability for an offline clientto resynchronize with the server (see also [IMAP-DISC]).

IMAP4 includes operations for creating, deleting, and renamingmailboxes; checking for new messages; permanently removing messages;setting and clearing flags; RFC 822 and MIME parsing; searching; andselective fetching of message attributes, texts, and portions

thereof. Messages in IMAP4 are accessed by the use of numbers.These numbers are either message sequence numbers (relative positionfrom 1 to the number of messages in the mailbox) or uniqueidentifiers (immutable, strictly ascending values assigned to eachmessage, but which are not necessarily contiguous).

IMAP4 supports a single server. A mechanism for supporting multipleIMAP4 servers is discussed in [IMSP].

IMAP4 does not specify a means of posting mail; this function ishandled by a mail transfer protocol such as [SMTP].

IMAP4 is designed to be upwards compatible from the [IMAP2] protocol.

Compatibility issues are discussed in [IMAP-COMPAT].

Crispin [Page i]

7/29/2019 Rfc 1730

2/78

RFC 1730 IMAP4 December 1994

Table of Contents

IMAP4 Protocol Specification ...................................... 11. Organization of this Document ............................. 11.1. How to Read This Document ................................. 11.2. Conventions Used in this Document ......................... 12. Protocol Overview ......................................... 12.1. Link Level ................................................ 12.2. Commands and Responses .................................... 12.2.1. Client Protocol Sender and Server Protocol Receiver ....... 22.2.2. Server Protocol Sender and Client Protocol Receiver ....... 23. State and Flow Diagram .................................... 43.1. Non-Authenticated State ................................... 43.2. Authenticated State ....................................... 43.3. Selected State ............................................ 4

3.4. Logout State .............................................. 44. Data Formats .............................................. 64.1. Atom ...................................................... 64.2. Number .................................................... 64.3. String .................................................... 64.3.1. 8-bit and Binary Strings .................................. 74.4. Parenthesized List ........................................ 74.5. NIL ....................................................... 75. Operational Considerations ................................ 85.1. Mailbox Naming ............................................ 85.2. Mailbox Size and Message Status Updates ................... 85.3. Response when no Command in Progress ...................... 85.4. Autologout Timer .......................................... 9

5.5. Multiple Commands in Progress ............................. 96. Client Commands ........................................... 106.1. Client Commands - Any State ............................... 106.1.1. CAPABILITY Command ........................................ 106.1.2. NOOP Command .............................................. 116.1.3. LOGOUT Command ............................................ 116.2. Client Commands - Non-Authenticated State ................. 126.2.1. AUTHENTICATE Command ...................................... 126.2.2. LOGIN Command ............................................. 146.3. Client Commands - Authenticated State ..................... 146.3.1. SELECT Command ............................................ 156.3.2. EXAMINE Command ........................................... 166.3.3. CREATE Command ............................................ 17

6.3.4. DELETE Command ............................................ 186.3.5. RENAME Command ............................................ 18

Crispin [Page ii]

7/29/2019 Rfc 1730

3/78


6.3.6. SUBSCRIBE Command ......................................... 196.3.7. UNSUBSCRIBE Command ....................................... 196.3.8. LIST Command .............................................. 206.3.9. LSUB Command .............................................. 226.3.10. APPEND Command ............................................ 226.4. Client Commands - Selected State .......................... 236.4.1. CHECK Command ............................................. 236.4.2. CLOSE Command ............................................. 246.4.3. EXPUNGE Command ........................................... 256.4.4. SEARCH Command ............................................ 256.4.5. FETCH Command ............................................. 296.4.6. PARTIAL Command ........................................... 326.4.7. STORE Command ............................................. 336.4.8. COPY Command .............................................. 346.4.9. UID Command ............................................... 356.5. Client Commands - Experimental/Expansion .................. 376.5.1. X Command ........................................... 377. Server Responses .......................................... 387.1. Server Responses - Status Responses ....................... 397.1.1. OK Response ............................................... 40

7.1.2. NO Response ............................................... 407.1.3. BAD Response .............................................. 417.1.4. PREAUTH Response .......................................... 417.1.5. BYE Response .............................................. 417.2. Server Responses - Server and Mailbox Status .............. 427.2.1. CAPABILITY Response ....................................... 427.2.2. LIST Response ............................................. 437.2.3. LSUB Response ............................................. 447.2.4. SEARCH Response ........................................... 447.2.5. FLAGS Response ............................................ 447.3. Server Responses - Message Status ......................... 457.3.1. EXISTS Response ........................................... 457.3.2. RECENT Response ........................................... 45

7.3.3. EXPUNGE Response .......................................... 457.3.4. FETCH Response ............................................ 467.3.5. Obsolete Responses ........................................ 517.4. Server Responses - Command Continuation Request ........... 518. Sample IMAP4 session ...................................... 529. Formal Syntax ............................................. 5310. Author's Note ............................................. 6411. Security Considerations ................................... 6412. Author's Address .......................................... 64Appendices ........................................................ 65A. Obsolete Commands ......................................... 65A.6.3.OBS.1. FIND ALL.MAILBOXES Command ........................ 65A.6.3.OBS.2. FIND MAILBOXES Command ............................ 65

A.6.3.OBS.3. SUBSCRIBE MAILBOX Command ......................... 66A.6.3.OBS.4. UNSUBSCRIBE MAILBOX Command ....................... 66

Crispin [Page iii]

7/29/2019 Rfc 1730

4/78


B. Obsolete Responses ........................................ 68B.7.2.OBS.1. MAILBOX Response .................................. 68B.7.3.OBS.1. COPY Response ..................................... 68B.7.3.OBS.2. STORE Response .................................... 69C. References ................................................ 70E. IMAP4 Keyword Index ....................................... 71

Crispin [Page iv]

7/29/2019 Rfc 1730

5/78


IMAP4 Protocol Specification

1. Organization of this Document

1.1. How to Read This Document

This document is written from the point of view of the implementor ofan IMAP4 client or server. Beyond the protocol overview in section2, it is not optimized for someone trying to understand the operationof the protocol. The material in sections 3 through 5 provides thegeneral context and definitions with which IMAP4 operates.

Sections 6, 7, and 9 describe the IMAP commands, responses, andsyntax, respectively. The relationships among these are such that itis almost impossible to understand any of them separately. Inparticular, one should not attempt to deduce command syntax from thecommand section alone; one should instead refer to the formal syntaxsection.

1.2. Conventions Used in this Document

In examples, "C:" and "S:" indicate lines sent by the client andserver respectively.

2. Protocol Overview

2.1. Link Level

The IMAP4 protocol assumes a reliable data stream such as provided byTCP. When TCP is used, an IMAP4 server listens on port 143.

2.2. Commands and Responses

An IMAP4 session consists of the establishment of a client/serverconnection, an initial greeting from the server, and client/serverinteractions. These client/server interactions consist of a clientcommand, server data, and a server completion result response.

All interactions transmitted by client and server are in the form oflines; that is, strings that end with a CRLF. The protocol receiverof an IMAP4 client or server is either reading a line, or is readinga sequence of octets with a known count followed by a line.

Crispin [Page 1]

7/29/2019 Rfc 1730

6/78


2.2.1. Client Protocol Sender and Server Protocol Receiver

The client command begins an operation. Each client command isprefixed with a identifier (typically a short alphanumeric string,e.g. A0001, A0002, etc.) called a "tag". A different tag isgenerated by the client for each command.

There are two cases in which a line from the client does notrepresent a complete command. In one case, a command argument isquoted with an octet count (see the description of literal in Stringunder Data Formats); in the other case, the command arguments requireserver feedback (see the AUTHENTICATE command). In either case, theserver sends a command continuation request response if it is readyfor 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 thecommand, it sends a BAD completion response with tagmatching the command (as described below) to reject thecommand and prevent the client from sending any more of the

command.

It is also possible for the server to send a completionresponse for some other command (if multiple commands arein progress), or untagged data. In either case, thecommand continuation request is still pending; the clienttakes the appropriate action for the response, and readsanother response from the server.

The protocol receiver of an IMAP4 server reads a command line fromthe client, parses the command and its arguments, and transmitsserver 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 responsesthat 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 besent unilaterally by the server. There is no syntactic differencebetween server data that resulted from a specific command and serverdata 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 theclient command which began the operation. Thus, if more than one

Crispin [Page 2]

7/29/2019 Rfc 1730

7/78


command is in progress, the tag in a server completion responseidentifies the command to which the response applies. There arethree possible server completion responses: OK (indicating success),NO (indicating failure), or BAD (indicating protocol error such asunrecognized command or command syntax error).

The protocol receiver of an IMAP4 client reads a response line fromthe server. It then takes action on the response based upon thefirst token of the response, which may be a tag, a "*", or a "+". Asdescribed above.

A client MUST be prepared to accept any server response at all times.This includes server data that it may not have requested. Serverdata SHOULD be recorded, so that the client can reference itsrecorded copy rather than sending a command to the server to requestthe data. In the case of certain server data, recording the data ismandatory.

This topic is discussed in greater detail in the Server Responsessection.

Crispin [Page 3]

7/29/2019 Rfc 1730

8/78


3. State and Flow Diagram

An IMAP4 server is in one of four states. Most commands are valid inonly certain states. It is a protocol error for the client toattempt a command while the command is in an inappropriate state. Inthis case, a server will respond with a BAD or NO (depending uponserver implementation) command completion result.

3.1. Non-Authenticated State

In non-authenticated state, the user must supply authenticationcredentials before most commands will be permitted. This state isentered when a connection starts unless the connection has beenpre-authenticated.

3.2. Authenticated State

In authenticated state, the user is authenticated and must select a

mailbox to access before commands that affect messages will bepermitted. This state is entered when a pre-authenticated connectionstarts, when acceptable authentication credentials have beenprovided, or after an error in selecting a mailbox.

3.3. Selected State

In selected state, a mailbox has been selected to access. This stateis entered when a mailbox has been successfully selected.

3.4. Logout State

In logout state, the session is being terminated, and the server willclose the connection. This state can be entered as a result of aclient request or by unilateral server decision.

Crispin [Page 4]

7/29/2019 Rfc 1730

9/78


+--------------------------------------+|initial connection and server greeting|+--------------------------------------+

|| (1) || (2) || (3)VV || ||

+-----------------+ || |||non-authenticated| || ||+-----------------+ || |||| (7) || (4) || |||| VV VV |||| +----------------+ |||| | authenticated |

7/29/2019 Rfc 1730

10/78


4. Data Formats

IMAP4 uses textual commands and responses. Data in IMAP4 can be inone of several forms: atom, number, string, parenthesized list, orNIL.

4.1. Atom

An atom consists of one or more non-special characters.

4.2. Number

A number consists of one or more digit characters, and represents anumeric value.

4.3. String

A string is in one of two forms: literal and quoted string. Theliteral form is the general form of string. The quoted string formis an alternative that avoids the overhead of processing a literal atthe cost of restrictions of what may be in a quoted string.

A literal is a sequence of zero or more octets (including CR and LF),prefix-quoted with an octet count in the form of an open brace ("{"),the number of octets, close brace ("}"), and CRLF. In the case ofliterals transmitted from server to client, the CRLF is immediatelyfollowed by the octet data. In the case of literals transmitted fromclient to server, the client must wait to receive a commandcontinuation request (described later in this document) beforesending the octet data (and the remainder of the command).

A quoted string is a sequence of zero or more 7-bit characters,excluding CR and LF, with double quote (

7/29/2019 Rfc 1730

11/78


4.3.1. 8-bit and Binary Strings

8-bit textual and binary mail is supported through the use of[MIME-1] encoding. IMAP4 implementations MAY transmit 8-bit ormulti-octet characters in literals, but should do so only when thecharacter set is identified.

Although a BINARY body encoding is defined, unencoded binary stringsare not permitted. A "binary string" is any string with NULcharacters. Implementations MUST encode binary data into a textualform such as BASE64 before transmitting the data. A string with anexcessive amount of CTL characters may also be considered to bebinary, although this is not required.

4.4. Parenthesized List

Data structures are represented as a "parenthesized list"; a sequenceof data items, delimited by space, and bounded at each end byparentheses. A parenthesized list may itself contain other

parenthesized lists, using multiple levels of parentheses to indicatenesting.

The empty list is represented as () -- a parenthesized list with nomembers.

4.5. NIL

The special atom "NIL" represents the non-existence of a particulardata item that is represented as a string or parenthesized list, asdistinct from the empty string "" or the empty parenthesized list ().

Crispin [Page 7]

7/29/2019 Rfc 1730

12/78


5. Operational Considerations

5.1. Mailbox Naming

The interpretation of mailbox names is implementation-dependent.However, the mailbox name INBOX is a special name reserved to mean"the primary mailbox for this user on this server". If it is desiredto export hierarchical mailbox names, mailbox names must beleft-to-right hierarchical using a single character to separatelevels of hierarchy. The same hierarchy separator character is usedfor all levels of hierarchy within a single name.

5.2. Mailbox Size and Message Status Updates

At any time, a server can send data that the client did not request.Sometimes, such behavior is required. For example, agents other thanthe server may add messages to the mailbox (e.g. new mail delivery),change the flags of message in the mailbox (e.g. simultaneous accessto the same mailbox by multiple agents), or even remove messages fromthe mailbox. A server MUST send mailbox size updates automatically

if a mailbox size change is observed during the processing of acommand. A server SHOULD send message flag updates automatically,without requiring the client to request such updates explicitly.Special rules exist for server notification of a client about theremoval of messages to prevent synchronization errors; see thedescription of the EXPUNGE response for more details.

Regardless of what implementation decisions a client may take onremembering data from the server, a client implementation MUST recordmailbox size updates. It MUST NOT assume that any command afterinitial mailbox selection will return the size of the mailbox.

5.3. Response when no Command in Progress

Server implementations are permitted to send an untagged response(except for EXPUNGE) while there is no command in progress. Serverimplementations that send such responses MUST deal with flow controlconsiderations. Specifically, they must either (1) verify that thesize of the data does not exceed the underlying transport's availablewindow size, or (2) use non-blocking writes.

Crispin [Page 8]

7/29/2019 Rfc 1730

13/78


5.4. Autologout Timer

If a server has an inactivity autologout timer, that timer MUST be ofat least 30 minutes' duration. The receipt of ANY command from theclient during that interval should suffice to reset the autologouttimer.

5.5. Multiple Commands in Progress

The client is not required to wait for the completion result responseof a command before sending another command, subject to flow controlconstraints on the underlying data stream. Similarly, a server isnot required to process a command to completion before beginningprocessing of the next command, unless an ambiguity would resultbecause of a command that would affect the results of other commands.If there is such an ambiguity, the server executes commands tocompletion in the order given by the client.

Crispin [Page 9]

7/29/2019 Rfc 1730

14/78


6. Client Commands

IMAP4 commands are described in this section. Commands are organizedby the state in which the command is permitted. Commands which arepermitted in multiple states are listed in the minimum permittedstate (for example, commands valid in authenticated and selectedstate are listed in the authenticated state commands).

Command arguments, identified by "Arguments:" in the commanddescriptions below, are described by function, not by syntax. Theprecise syntax of command arguments is described in the Formal Syntaxsection.

Some commands cause specific server data to be returned; these areidentified by "Data:" in the command descriptions below. See theresponse descriptions in the Responses section for information onthese responses, and the Formal Syntax section for the precise syntaxof these responses. It is possible for server data to be transmittedas a result of any command; thus, commands that do not specificallyrequire server data specify "no specific data for this command"

instead of "none".

The "Result:" in the command description refers to the possibletagged status responses to a command, and any special interpretationof these status responses.

6.1. Client Commands - Any State

The following commands are valid in any state: CAPABILITY, NOOP, andLOGOUT.

6.1.1. CAPABILITY Command

Arguments: none

Data: mandatory untagged response: CAPABILITY

Result: OK - capability completedBAD - command unknown or arguments invalid

The CAPABILITY command requests a listing of capabilities that theserver supports. The server MUST send a single untaggedCAPABILITY response with "IMAP4" as the first listed capabilitybefore the (tagged) OK response. This listing of capabilities isnot dependent upon connection state or user. It is therefore not

necessary to issue a CAPABILITY command more than once in asession.

Crispin [Page 10]

7/29/2019 Rfc 1730

15/78


Capability names other than "IMAP4" refer to extensions,revisions, or amendments to this specification. See thedocumentation of the CAPABILITY response for additionalinformation. No capabilities are enabled without explicit clientaction to invoke the capability. See the section entitled "ClientCommands - Experimental/Expansion" for information about the formof site or implementation-specific capabilities.

Example: C: abcd CAPABILITYS: * CAPABILITY IMAP4S: abcd OK CAPABILITY completed

6.1.2. NOOP Command

Arguments: none

Data: no specific data for this command (but see below)

Result: OK - noop completed

BAD - command unknown or arguments invalid

The NOOP command always succeeds. It does nothing.

Since any command can return a status update as untagged data, theNOOP command can be used as a periodic poll for new messages ormessage status updates during a period of inactivity. The NOOPcommand can also be used to reset any inactivity autologout timeron the server.

Example: C: a002 NOOPS: a002 OK NOOP completed

. . .

C: a047 NOOPS: * 22 EXPUNGES: * 23 EXISTSS: * 3 RECENTS: * 14 FETCH (FLAGS (\Seen \Deleted))S: a047 OK NOOP completed

Crispin [Page 11]

7/29/2019 Rfc 1730

16/78


6.1.3. LOGOUT Command

Arguments: none

Data: mandatory untagged response: BYE

Result: OK - logout completedBAD - command unknown or arguments invalid

The LOGOUT command informs the server that the client is done withthe session. The server must send a BYE untagged response beforethe (tagged) OK response, and then close the network connection.

Example: C: A023 LOGOUTS: * BYE IMAP4 Server logging outS: A023 OK LOGOUT completed(Server and client then close the connection)

6.2. Client Commands - Non-Authenticated State

In non-authenticated state, the AUTHENTICATE or LOGIN commandestablishes authentication and enter authenticated state. TheAUTHENTICATE command provides a general mechanism for a variety ofauthentication techniques, whereas the LOGIN command uses thetraditional user name and plaintext password pair.

Server implementations may allow non-authenticated access to certainmailboxes. The convention is to use a LOGIN command with the userid"anonymous". A password is required. It is implementation-dependentwhat requirements, if any, are placed on the password and what accessrestrictions are placed on anonymous users.

Once authenticated (including as anonymous), it is not possible tore-enter non-authenticated state.

In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),the following commands are valid in non-authenticated state:AUTHENTICATE and LOGIN.

Crispin [Page 12]

7/29/2019 Rfc 1730

17/78


6.2.1. AUTHENTICATE Command

Arguments: authentication mechanism name

Data: continuation data may be requested

Result: OK - authenticate completed, now in authenticated stateNO - authenticate failure: unsupported authentication

mechanism, credentials rejectedBAD - command unknown or arguments invalid,

authentication exchange cancelled

The AUTHENTICATE command indicates an authentication mechanism,such as described in [IMAP-AUTH], to the server. If the serversupports the requested authentication mechanism, it performs anauthentication protocol exchange to authenticate and identify theuser. Optionally, it also negotiates a protection mechanism forsubsequent protocol interactions. If the requested authenticationmechanism is not supported, the server should reject theAUTHENTICATE command by sending a tagged NO response.

The authentication protocol exchange consists of a series ofserver challenges and client answers that are specific to theauthentication mechanism. A server challenge consists of acommand continuation request response with the "+" token followedby a BASE64 encoded string. The client answer consists of a lineconsisting of a BASE64 encoded string. If the client wishes tocancel an authentication exchange, it should issue a line with asingle "*". If the server receives such an answer, it must rejectthe AUTHENTICATE command by sending a tagged BAD response.

A protection mechanism provides integrity and privacy protectionto the protocol session. If a protection mechanism is negotiated,

it is applied to all subsequent data sent over the connection.The protection mechanism takes effect immediately following theCRLF that concludes the authentication exchange for the client,and the CRLF of the tagged OK response for the server. Once theprotection mechanism is in effect, the stream of command andresponse octets is processed into buffers of ciphertext. Eachbuffer is transferred over the connection as a stream of octetsprepended with a four octet field in network byte order thatrepresents the length of the following data. The maximumciphertext buffer length is defined by the protection mechanism.

The server is not required to support any particularauthentication mechanism, nor are authentication mechanisms

required to support any protection mechanisms. If an AUTHENTICATEcommand fails with a NO response, the client may try another

Crispin [Page 13]

7/29/2019 Rfc 1730

18/78


authentication mechanism by issuing another AUTHENTICATE command,or may attempt to authenticate by using the LOGIN command. Inother words, the client may request authentication types indecreasing order of preference, with the LOGIN command as a lastresort.

Example: S: * OK KerberosV4 IMAP4 ServerC: A001 AUTHENTICATE KERBEROS_V4S: + AmFYig==C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT

+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFdWwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh

S: + or//EoAADZI=C: DiAF5A4gA+oOIALuBkAAmw==S: A001 OK Kerberos V4 authentication successful

Note: the line breaks in the first client answer are foreditorial clarity and are not in real authenticators.

6.2.2. LOGIN Command

Arguments: user namepassword

Data: no specific data for this command

Result: OK - login completed, now in authenticated stateNO - login failure: user name or password rejectedBAD - command unknown or arguments invalid

The LOGIN command identifies the user to the server and carriesthe plaintext password authenticating this user.

Example: C: a001 LOGIN SMITH SESAMES: a001 OK LOGIN completed

6.3. Client Commands - Authenticated State

In authenticated state, commands that manipulate mailboxes as atomicentities are permitted. Of these commands, the SELECT and EXAMINEcommands will select a mailbox for access and enter selected state.

Crispin [Page 14]

7/29/2019 Rfc 1730

19/78


In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),the following commands are valid in authenticated state: SELECT,EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB,and APPEND.

6.3.1. SELECT Command

Arguments: mailbox name

Data: mandatory untagged responses: FLAGS, EXISTS, RECENToptional OK untagged responses: UNSEEN, PERMANENTFLAGS

Result: OK - select completed, now in selected stateNO - select failure, now in authenticated state: no

such mailbox, can't access mailboxBAD - command unknown or arguments invalid

The SELECT command selects a mailbox so that messages in themailbox can be accessed. Before returning an OK to the client,the server MUST send the following untagged data to the client:

FLAGS Defined flags in the mailbox

EXISTS The number of messages in the mailbox

RECENT The number of messages added to the mailbox sincethe previous time this mailbox was read

OK [UIDVALIDITY ]The unique identifier validity value. See thedescription of the UID command for more detail.

to define the initial state of the mailbox at the client. If it

is not possible to determine the messages that were added sincethe previous time a mailbox was read, then all messages SHOULD beconsidered recent.

The server SHOULD also send an UNSEEN response code in an OKuntagged response, indicating the message sequence number of thefirst unseen message in the mailbox.

If the client can not change the permanent state of one or more ofthe flags listed in the FLAGS untagged response, the server SHOULDsend a PERMANENTFLAGS response code in an OK untagged response,listing the flags that the client may change permanently.

Only one mailbox may be selected at a time in a session;simultaneous access to multiple mailboxes requires multiple

Crispin [Page 15]

7/29/2019 Rfc 1730

20/78


sessions. The SELECT command automatically deselects anycurrently selected mailbox before attempting the new selection.Consequently, if a mailbox is selected and a SELECT command thatfails is attempted, no mailbox is selected.

If the user is permitted to modify the mailbox, the server SHOULDprefix the text of the tagged OK response with the "[READ-WRITE]"response code.

If the user is not permitted to modify the mailbox but ispermitted read access, the mailbox is selected as read-only, andthe server MUST prefix the text of the tagged OK response toSELECT with the "[READ-ONLY]" response code. Read-only accessthrough SELECT differs from the EXAMINE command in that certainread-only mailboxes may permit the change of permanent state on aper-user (as opposed to global) basis. Netnews messages marked ina user's .newsrc file are an example of such per-user permanentstate that can be modified with read-only mailboxes.

Example: C: A142 SELECT INBOX

S: * 172 EXISTSS: * 1 RECENTS: * OK [UNSEEN 12] Message 12 is first unseenS: * OK [UIDVALIDITY 3857529045] UIDs validS: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] LimitedS: A142 OK [READ-WRITE] SELECT completed

6.3.2. EXAMINE Command


Data: mandatory untagged responses: FLAGS, EXISTS, RECENToptional OK untagged responses: UNSEEN, PERMANENTFLAGS

Result: OK - examine completed, now in selected stateNO - examine failure, now in authenticated state: no

such mailbox, can't access mailboxBAD - command unknown or arguments invalid

The EXAMINE command is identical to SELECT and returns the sameoutput; however, the selected mailbox is identified as read-only.No changes to the permanent state of the mailbox, includingper-user state, are permitted.

Crispin [Page 16]

7/29/2019 Rfc 1730

21/78


The text of the tagged OK response to the EXAMINE command MUSTbegin with the "[READ-ONLY]" response code.

Example: C: A932 EXAMINE blurdybloopS: * 17 EXISTSS: * 2 RECENTS: * OK [UNSEEN 8] Message 8 is first unseenS: * OK [UIDVALIDITY 3857529045] UIDs validS: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)S: * OK [PERMANENTFLAGS ()] No permanent flags permittedS: A932 OK [READ-ONLY] EXAMINE completed

6.3.3. CREATE Command



Result: OK - create completed

NO - create failure: can't create mailbox with that nameBAD - command unknown or arguments invalid

The CREATE command creates a mailbox with the given name. An OKresponse is returned only if a new mailbox with that name has beencreated. It is an error to attempt to create INBOX or a mailboxwith a name that refers to an extant mailbox. Any error increation will return a tagged NO response.

If the mailbox name is suffixed with the server's hierarchyseparator character (as returned from the server by a LISTcommand), this is a declaration that the client may, in thefuture, create mailbox names under this name in the hierarchy.

Server implementations that do not require this declaration MUSTignore it.

If a new mailbox is created with the same name as a mailbox whichwas deleted, its unique identifiers MUST be greater than anyunique identifiers used in the previous incarnation of the mailboxUNLESS the new incarnation has a different unique identifiervalidity value. See the description of the UID command for moredetail.

Example: C: A003 CREATE owatagusiam/S: A003 OK CREATE completedC: A004 CREATE owatagusiam/blurdybloop

S: A004 OK CREATE completed

Crispin [Page 17]

7/29/2019 Rfc 1730

22/78


Note: the interpretation of this example depends on whether"/" was returned as the hierarchy separator from LIST. If"/" is the hierarchy separator, a new level of hierarchynamed "owatagusiam" with a member called "blurdybloop" iscreated. Otherwise, two mailboxes at the same hierarchylevel are created.

6.3.4. DELETE Command



Result: OK - delete completedNO - delete failure: can't delete mailbox with that nameBAD - command unknown or arguments invalid

The DELETE command permanently removes the mailbox with the givenname. A tagged OK response is returned only if the mailbox has

been deleted. It is an error to attempt to delete INBOX or amailbox name that does not exist. Any error in deletion willreturn a tagged NO response.

The value of the highest-used unique indentifier of the deletedmailbox MUST be preserved so that a new mailbox created with thesame name will not reuse the identifiers of the formerincarnation, UNLESS the new incarnation has a different uniqueidentifier validity value. See the description of the UID commandfor more detail.

Example: C: A683 DELETE blurdybloopS: A683 OK DELETE completed

6.3.5. RENAME Command

Arguments: existing mailbox namenew mailbox name


Result: OK - rename completedNO - rename failure: can't rename mailbox with that name,

can't rename to mailbox with that nameBAD - command unknown or arguments invalid

Crispin [Page 18]

7/29/2019 Rfc 1730

23/78


The RENAME command changes the name of a mailbox. A tagged OKresponse is returned only if the mailbox has been renamed. It isan error to attempt to rename from a mailbox name that does notexist or to a mailbox name that already exists. Any error inrenaming will return a tagged NO response.

Renaming INBOX is permitted; a new, empty INBOX is created in itsplace.

Example: C: Z4S9 RENAME blurdybloop owatagusiamS: Z4S9 OK RENAME completed

6.3.6. SUBSCRIBE Command

Arguments: mailbox


Result: OK - subscribe completed

NO - subscribe failure: can't subscribe to that nameBAD - command unknown or arguments invalid

The SUBSCRIBE command adds the specified mailbox name to theserver's set of "active" or "subscribed" mailboxes as returned bythe LSUB command. This command returns a tagged OK response onlyif the subscription is successful.

Example: C: A002 SUBSCRIBE #news.comp.mail.mimeS: A002 OK SUBSCRIBE completed

6.3.7. UNSUBSCRIBE Command



Result: OK - unsubscribe completedNO - unsubscribe failure: can't unsubscribe that nameBAD - command unknown or arguments invalid

The UNSUBSCRIBE command removes the specified mailbox name fromthe server's set of "active" or "subscribed" mailboxes as returnedby the LSUB command. This command returns a tagged OK responseonly if the unsubscription is successful.

Crispin [Page 19]

7/29/2019 Rfc 1730

24/78


Example: C: A002 UNSUBSCRIBE #news.comp.mail.mimeS: A002 OK UNSUBSCRIBE completed

6.3.8. LIST Command

Arguments: reference namemailbox name with possible wildcards

Data: untagged responses: LIST

Result: OK - list completedNO - list failure: can't list that reference or nameBAD - command unknown or arguments invalid

The LIST command returns a subset of names from the complete setof all names available to the user. Zero or more untagged LISTreplies are returned, containing the name attributes, hierarchydelimiter, and name; see the description of the LIST reply formore detail.

An empty ("" string) reference name argument indicates that themailbox name is interpreted as by SELECT. The returned mailboxnames MUST match the supplied mailbox name pattern. A non-emptyreference name argument is the name of a mailbox or a level ofmailbox hierarchy, and indicates a context in which the mailboxname is interpreted in an implementation-defined manner.

The reference and mailbox name arguments are interpreted, in animplementation-dependent fashion, into a canonical form thatrepresents an unambiguous left-to-right hierarchy. The returnedmailbox names will be in the interpreted form.

Any part of the reference argument that is included in theinterpreted form SHOULD prefix the interpreted form. It shouldalso be in the same form as the reference name argument. Thisrule permits the client to determine if the returned mailbox nameis in the context of the reference argument, or if something aboutthe mailbox argument overrode the reference argument. Withoutthis rule, the client would have to have knowledge of the server'snaming semantics including what characters are "breakouts" thatoverride a naming context.

Crispin [Page 20]

7/29/2019 Rfc 1730

25/78


For example, here are some examples of how referencesand mailbox names might be interpreted on a UNIX-basedserver:

Reference Mailbox Name Interpretation------------ ------------ --------------~smith/Mail/ foo.* ~smith/Mail/foo.*archive/ % archive/%#news. comp.mail.* #news.comp.mail.*~smith/Mail/ /usr/doc/foo /usr/doc/fooarchive/ ~fred/Mail/* ~fred/Mail/*

The first three examples demonstrate interpretations inthe context of the reference argument. Note that"~smith/Mail" should not be transformed into somethinglike "/u2/users/smith/Mail", or it would be impossiblefor the client to determine that the interpretation wasin 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 "%" wildcardis the last character of a mailbox name argument, matching levelsof hierarchy are also returned. If these levels of hierarchy arenot also selectable mailboxes, they are returned with the\Noselect mailbox name attribute (see the description of the LISTresponse for more detail).

Server implementations are permitted to "hide" otherwiseaccessible mailboxes from the wildcard characters, by preventingcertain characters or names from matching a wildcard in certainsituations. For example, a UNIX-based server might restrict theinterpretation of "*" so that an initial "/" character does not

match.

The special name INBOX is included in the output from LIST if itmatches the input arguments and INBOX is supported by this serverfor this user. The criteria for omitting INBOX is whether SELECTINBOX will return failure; it is not relevant whether the user'sreal INBOX resides on this or some other server.

Example: C: A002 LIST "~/Mail/" "%"S: * LIST (\Noselect) "/" ~/Mail/fooS: * LIST () "/" ~/Mail/meetingsS: A002 OK LIST completed

Crispin [Page 21]

7/29/2019 Rfc 1730

26/78


6.3.9. LSUB Command

Arguments: reference namemailbox name with possible wildcards

Data: untagged responses: LSUB

Result: OK - lsub completedNO - lsub failure: can't list that reference or nameBAD - command unknown or arguments invalid

The LSUB command returns a subset of names from the set of namesthat the user has declared as being "active" or "subscribed".Zero or more untagged LSUB replies are returned. The arguments toLSUB are in the same form as those for LIST.

Example: C: A002 LSUB "#news." "comp.mail.*"S: * LSUB () "." #news.comp.mail.mimeS: * LSUB () "." #news.comp.mail.miscS: A002 OK LSUB completed

6.3.10. APPEND Command

Arguments: mailbox nameoptional flag parenthesized listoptional date/time stringmessage literal


Result: OK - append completedNO - append error: can't append to that mailbox, error

in flags or date/time or message textBAD - command unknown or arguments invalid

The APPEND command appends the literal argument as a new messagein the specified destination mailbox. This argument is in theformat of an [RFC-822] message. 8-bit characters are permitted inthe message. A server implementation that is unable to preserve8-bit data properly MUST be able to reversibly convert 8-bitAPPEND data to 7-bit using [MIME-1] encoding.

If a flag parenthesized list or date_time are specified, that dataSHOULD be set in the resulting message; otherwise, the defaults ofempty flags and the current date/time are used.

Crispin [Page 22]

7/29/2019 Rfc 1730

27/78


If the append is unsuccessful for any reason, the mailbox MUST berestored to its state before the APPEND attempt; no partialappending is permitted. If the mailbox is currently selected, thenormal new mail actions should occur.

If the destination mailbox does not exist, a server MUST return anerror, and MUST NOT automatically create the mailbox. Unless itis certain that the destination mailbox can not be created, theserver MUST send the response code "[TRYCREATE]" as the prefix ofthe text of the tagged NO response. This gives a hint to theclient that it can attempt a CREATE command and retry the APPENDif the CREATE is successful.

Example: C: A003 APPEND saved-messages (\Seen) {310}C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)C: From: Fred Foobar C: Subject: afternoon meetingC: To: [email protected]: Message-Id: C: MIME-Version: 1.0

C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCIIC:C: Hello Joe, do you think we can meet at 3:30 tomorrow?C:S: A003 OK APPEND completed

Note: the APPEND command is not used for message delivery,because it does not provide a mechanism to transfer [SMTP]envelope information.

6.4. Client Commands - Selected State

In selected state, commands that manipulate messages in a mailbox arepermitted.

In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),and the authenticated state commands (SELECT, EXAMINE, CREATE,DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, FINDALL.MAILBOXES, FIND MAILBOXES, and APPEND), the following commandsare valid in the selected state: CHECK, CLOSE, EXPUNGE, SEARCH,FETCH, PARTIAL, STORE, COPY, and UID.

Crispin [Page 23]

7/29/2019 Rfc 1730

28/78


6.4.1. CHECK Command

Arguments: none


Result: OK - check completedBAD - command unknown or arguments invalid

The CHECK command requests a checkpoint of the currently selectedmailbox. A checkpoint refers to any implementation-dependenthousekeeping associated with the mailbox (e.g. resolving theserver's in-memory state of the mailbox with the state on itsdisk) that is not normally executed as part of each command. Acheckpoint may take a non-instantaneous amount of real time tocomplete. If a server implementation has no such housekeepingconsiderations, CHECK is equivalent to NOOP.

There is no guarantee that an EXISTS untagged response will happenas a result of CHECK. NOOP, not CHECK, should be used for new

mail polling.

Example: C: FXXZ CHECKS: FXXZ OK CHECK Completed

6.4.2. CLOSE Command

Arguments: none


Result: OK - close completed, now in authenticated state

NO - close failure: no mailbox selectedBAD - command unknown or arguments invalid

The CLOSE command permanently removes from the currently selectedmailbox all messages that have the \Deleted flag set, and returnsto authenticated state from selected state. No untagged EXPUNGEresponses are sent.

No messages are removed, and no error is given, if the mailbox isselected by an EXAMINE command or is otherwise selected read-only.

Even when a mailbox is selected, it is not required to send aCLOSE command before a SELECT, EXAMINE, or LOGOUT command. The

SELECT, EXAMINE, and LOGOUT commands implicitly close thecurrently selected mailbox without doing an expunge. However,

Crispin [Page 24]

7/29/2019 Rfc 1730

29/78


when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECTsequence is considerably faster than an EXPUNGE-LOGOUT orEXPUNGE-SELECT because no untagged EXPUNGE responses (which theclient would probably ignore) are sent.

Example: C: A341 CLOSES: A341 OK CLOSE completed

6.4.3. EXPUNGE Command

Arguments: none

Data: untagged responses: EXPUNGE

Result: OK - expunge completedNO - expunge failure: can't expunge (e.g. permission

denied)BAD - command unknown or arguments invalid

The EXPUNGE command permanently removes from the currentlyselected mailbox all messages that have the \Deleted flag set.Before returning an OK to the client, an untagged EXPUNGE responseis sent for each message that is removed.

Example: C: A202 EXPUNGES: * 3 EXPUNGES: * 3 EXPUNGES: * 5 EXPUNGES: * 8 EXPUNGES: A202 OK EXPUNGE completed

Note: in this example, messages 3, 4, 7, and 11 had the

\Deleted flag set. See the description of the EXPUNGEresponse for further explanation.

Crispin [Page 25]

7/29/2019 Rfc 1730

30/78


6.4.4. SEARCH Command

Arguments: optional character set specificationsearching criteria (one or more)

Data: mandatory untagged response: SEARCH

Result: OK - search completedNO - search error: can't search that character set or

criteriaBAD - command unknown or arguments invalid

The SEARCH command searches the mailbox for messages that matchthe given searching criteria. Searching criteria consist of oneor more search keys. The untagged SEARCH response from the servercontains a listing of message sequence numbers corresponding tothose messages that match the searching criteria.

When multiple keys are specified, the result is the intersection(AND function) of all the messages that match those keys. For

example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refersto all deleted messages from Smith that were placed in the mailboxsince February 1, 1994. A search key may also be a parenthesizedlist of one or more search keys (e.g. for use with the OR and NOTkeys).

Server implementations MAY exclude [MIME-1] body parts withterminal content types other than TEXT and MESSAGE fromconsideration in SEARCH matching.

The optional character set specification consists of the word"CHARSET" followed by a registered MIME character set. Itindicates the character set of the strings that appear in the

search criteria. [MIME-2] strings that appear in RFC 822/MIMEmessage headers, and [MIME-1] content transfer encodings, MUST bedecoded before matching. Except for US-ASCII, it is not requiredthat any particular character set be supported. If the serverdoes not support the specified character set, it MUST return atagged NO response (not a BAD).

In all search keys that use strings, a message matches the key ifthe string is a substring of the field. The matching iscase-insensitive.

Crispin [Page 26]

7/29/2019 Rfc 1730

31/78


The defined search keys are as follows. Refer to the FormalSyntax section for the precise syntactic definitions of thearguments.

Messages with message sequence numberscorresponding to the specified message sequencenumber set

ALL All messages in the mailbox; the default initialkey for ANDing.

ANSWERED Messages with the \Answered flag set.

BCC Messages that contain the specified string in theenvelope structure's BCC field.

BEFORE Messages whose internal date is earlier than thespecified date.

BODY Messages that contain the specified string in the

body of the message.

CC Messages that contain the specified string in theenvelope structure's CC field.

DELETED Messages with the \Deleted flag set.

DRAFT Messages with the \Draft flag set.

FLAGGED Messages with the \Flagged flag set.

FROM Messages that contain the specified string in theenvelope structure's FROM field.

HEADER Messages that have a header with the specifiedfield-name (as defined in [RFC-822]) and thatcontains the specified string in the [RFC-822]field-body.

KEYWORD Messages with the specified keyword set.

LARGER Messages with an RFC822.SIZE larger than thespecified number of octets.

NEW Messages that have the \Recent flag set but not the

\Seen flag. This is functionally equivalent to"(RECENT UNSEEN)".

Crispin [Page 27]

7/29/2019 Rfc 1730

32/78


NOT Messages that do not match the specified searchkey.

OLD Messages that do not have the \Recent flag set.This is functionally equivalent to "NOT RECENT" (asopposed to "NOT NEW").

ON Messages whose internal date is within thespecified date.

OR Messages that match either search key.

RECENT Messages that have the \Recent flag set.

SEEN Messages that have the \Seen flag set.

SENTBEFORE Messages whose [RFC-822] Date: header is earlier

than the specified date.

SENTON Messages whose [RFC-822] Date: header is within thespecified date.

SENTSINCE Messages whose [RFC-822] Date: header is within orlater than the specified date.

SINCE Messages whose internal date is within or laterthan the specified date.

SMALLER Messages with an RFC822.SIZE smaller than the

specified number of octets.

SUBJECT Messages that contain the specified string in theenvelope structure's SUBJECT field.

TEXT Messages that contain the specified string in theheader or body of the message.

TO Messages that contain the specified string in theenvelope structure's TO field.

UID

Messages with unique identifiers corresponding tothe specified unique identifier set.

Crispin [Page 28]

7/29/2019 Rfc 1730

33/78


UNANSWERED Messages that do not have the \Answered flag set.

UNDELETED Messages that do not have the \Deleted flag set.

UNDRAFT Messages that do not have the \Draft flag set.

UNFLAGGED Messages that do not have the \Flagged flag set.

UNKEYWORD Messages that do not have the specified keywordset.

UNSEEN Messages that do not have the \Seen flag set.

Example: C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"S: * SEARCH 2 84 882S: A282 OK SEARCH completed

6.4.5. FETCH Command

Arguments: message setmessage data item names

Data: untagged responses: FETCH

Result: OK - fetch completedNO - fetch error: can't fetch that dataBAD - command unknown or arguments invalid

The FETCH command retrieves data associated with a message in themailbox. The data items to be fetched may be either a single atom

or a parenthesized list. The currently defined data items thatcan be fetched are:

ALL Macro equivalent to: (FLAGS INTERNALDATERFC822.SIZE ENVELOPE)

BODY Non-extensible form of BODYSTRUCTURE.

BODY[]The text of a particular body section. The sectionspecification is a set of one or more part numbersdelimited by periods.

Single-part messages only have a part 1.

Crispin [Page 29]

7/29/2019 Rfc 1730

34/78


Multipart messages are assigned consecutive partnumbers, as they occur in the message. If aparticular part is of type message or multipart,its parts must be indicated by a period followed bythe part number within that nested multipart part.It is not permitted to fetch a multipart partitself, only its individual members.

A part of type MESSAGE and subtype RFC822 also hasnested parts. These are the parts of the MESSAGEpart's body. Nested part 0 of a part of typeMESSAGE and subtype RFC822 is the [RFC-822] headerof the message.

Every message has at least one part.

Here is an example of a complex messagewith its associated sectionspecifications:

0 ([RFC-822] header of the message)MULTIPART/MIXED1 TEXT/PLAIN2 APPLICATION/OCTET-STREAM3 MESSAGE/RFC8223.0 ([RFC-822] header of the message)3.1 TEXT/PLAIN3.2 APPLICATION/OCTET-STREAM

MULTIPART/MIXED4.1 IMAGE/GIF4.2 MESSAGE/RFC8224.2.0 ([RFC-822] header of the message)4.2.1 TEXT/PLAIN

MULTIPART/ALTERNATIVE4.2.2.1 TEXT/PLAIN4.2.2.2 TEXT/RICHTEXT

Note that there is no sectionspecification for the Multi-part parts(no section 4 or 4.2.2).

The \Seen flag is implicitly set; if this causesthe flags to change they should be included as partof the fetch responses.

BODY.PEEK[]

An alternate form of BODY[section] that does notimplicitly set the \Seen flag.

Crispin [Page 30]

7/29/2019 Rfc 1730

35/78


BODYSTRUCTURE The [MIME-1] body structure of the message. Thisis computed by the server by parsing the [MIME-1]header lines.

ENVELOPE The envelope structure of the message. This iscomputed by the server by parsing the [RFC-822]header into the component parts, defaulting variousfields as necessary.

FAST Macro equivalent to: (FLAGS INTERNALDATERFC822.SIZE)

FLAGS The flags that are set for this message.

FULL Macro equivalent to: (FLAGS INTERNALDATERFC822.SIZE ENVELOPE BODY)

INTERNALDATE The date and time of final delivery of the messageas defined by RFC 821.

RFC822 The message in [RFC-822] format. The \Seen flag isimplicitly set; if this causes the flags to changethey should be included as part of the fetchresponses. This is the concatenation ofRFC822.HEADER and RFC822.TEXT.

RFC822.PEEK An alternate form of RFC822 that does notimplicitly set the \Seen flag.

RFC822.HEADER The [RFC-822] format header of the message asstored on the server including the delimiting blankline between the header and the body.

RFC822.HEADER.LINES All header lines (including continuation lines) ofthe [RFC-822] format header of the message with afield-name (as defined in [RFC-822]) that matchesany of the strings in header_list. The matching iscase-insensitive but otherwise exact. Thedelimiting blank line between the header and thebody is always included.

Crispin [Page 31]

7/29/2019 Rfc 1730

36/78


RFC822.HEADER.LINES.NOT All header lines (including continuation lines) ofthe [RFC-822] format header of the message with afield-name (as defined in [RFC-822]) that does notmatch any of the strings in header_list. Thematching is case-insensitive but otherwise exact.The delimiting blank line between the header andthe body is always included.

RFC822.SIZE The number of octets in the message, as expressedin [RFC-822] format.

RFC822.TEXT The text body of the message, omitting the[RFC-822] header. The \Seen flag is implicitlyset; if this causes the flags to change they shouldbe included as part of the fetch responses.

RFC822.TEXT.PEEKAn alternate form of RFC822.TEXT that does notimplicitly set the \Seen flag.

UID The unique identifier for the message.

Example: C: A654 FETCH 2:4 (FLAGS RFC822.HEADER.LINES (DATE FROM))S: * 2 FETCH ....S: * 3 FETCH ....S: * 4 FETCH ....S: A003 OK FETCH completed

6.4.6. PARTIAL Command

Arguments: message sequence numbermessage data item nameposition of first octetnumber of octets


Result: OK - partial completedNO - partial error: can't fetch that dataBAD - command unknown or arguments invalid

The PARTIAL command is equivalent to the associated FETCH command,with the added functionality that only the specified number of

octets, beginning at the specified starting octet, are returned.Only a single message can be fetched at a time. The first octet

Crispin [Page 32]

7/29/2019 Rfc 1730

37/78


of a message, and hence the minimum for the starting octet, isoctet 1.

The following FETCH items are valid data for PARTIAL: RFC822,RFC822.HEADER, RFC822.TEXT, BODY[section], as well as any .PEEKforms of these.

Any partial fetch that attempts to read beyond the end of the textis truncated as appropriate. If the starting octet is beyond theend of the text, an empty string is returned.

The data are returned with the FETCH response. There is noindication of the range of the partial data in this response. Itis not possible to stream multiple PARTIAL commands of the samedata item without processing and synchronizing at each step, sincestreamed commands may be executed out of order.

There is no requirement that partial fetches follow any sequence.For example, if a partial fetch of octets 1 through 10000 breaksin an awkward place for BASE64 decoding, it is permitted to

continue with a partial fetch of 9987 through 19987, etc.

The handling of the \Seen flag is the same as in the associatedFETCH command.

Example: C: A005 PARTIAL 4 RFC822 1 1024S: * 1 FETCH (RFC822 {1024}S: Return-Path: S: ...S: ......... FLAGS (\Seen))S: A005 OK PARTIAL completed

6.4.7. STORE Command

Arguments: message setmessage data item namevalue for message data item


Result: OK - store completedNO - store error: can't store that dataBAD - command unknown or arguments invalid

The STORE command alters data associated with a message in the

mailbox. Normally, STORE will return the updated value of thedata with an untagged FETCH response. A suffix of ".SILENT" in

Crispin [Page 33]

7/29/2019 Rfc 1730

38/78


the data item name prevents the untagged FETCH, and the servershould assume that the client has determined the updated valueitself or does not care about the updated value.

The currently defined data items that can be stored are:

FLAGS Replace the flags for the message with theargument. The new value of the flags are returnedas if a FETCH of those flags was done.

FLAGS.SILENT Equivalent to FLAGS, but without returning a newvalue.

+FLAGS Add the argument to the flags for the message. Thenew value of the flags are returned as if a FETCHof those flags was done.

+FLAGS.SILENT Equivalent to +FLAGS, but without returning a newvalue.

-FLAGS Remove the argument from the flags for the message.The new value of the flags are returned as if aFETCH of those flags was done.

-FLAGS.SILENT Equivalent to -FLAGS, but without returning a newvalue.

Example: C: A003 STORE 2:4 +FLAGS (\Deleted)S: * 2 FETCH FLAGS (\Deleted \Seen)S: * 3 FETCH FLAGS (\Deleted)S: * 4 FETCH FLAGS (\Deleted \Flagged \Seen)S: A003 OK STORE completed

Crispin [Page 34]

7/29/2019 Rfc 1730

39/78


6.4.8. COPY Command

Arguments: message setmailbox name


Result: OK - copy completedNO - copy error: can't copy those messages or to that

nameBAD - command unknown or arguments invalid

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

If the destination mailbox does not exist, a server SHOULD returnan error. It SHOULD NOT automatically create the mailbox. Unlessit is certain that the destination mailbox can not be created, theserver MUST send the response code "[TRYCREATE]" as the prefix of

the text of the tagged NO response. This gives a hint to theclient that it can attempt a CREATE command and retry the COPY ifthe CREATE is successful.

If the COPY command is unsuccessful for any reason, serverimplementations MUST restore the destination mailbox to its statebefore the COPY attempt.

Example: C: A003 COPY 2:4 MEETINGS: A003 OK COPY completed

6.4.9. UID Command

Arguments: command namecommand arguments

Data: untagged responses: FETCH, SEARCH

Result: OK - UID command completedNO - UID command errorBAD - command unknown or arguments invalid

The UID command has two forms. In the first form, it takes as itsarguments a COPY, FETCH, or STORE command with argumentsappropriate for the associated command. However, the numbers in

the message set argument are unique identifiers instead of messagesequence numbers.

Crispin [Page 35]

7/29/2019 Rfc 1730

40/78


In the second form, the UID command takes a SEARCH command withSEARCH command arguments. The interpretation of the arguments isthe same as with SEARCH; however, the numbers returned in a SEARCHresponse for a UID SEARCH command are unique identifiers insteadof message sequence numbers. For example, the command UID SEARCH1:100 UID 443:557 returns the unique identifiers corresponding tothe intersection of the message sequence number set 1:100 and theUID set 443:557.

A unique identifier of a message is a number, and is guaranteednot to refer to any other message in the mailbox. Uniqueidentifiers are assigned in a strictly ascending fashion for eachmessage added to the mailbox. Unlike message sequence numbers,unique identifiers persist across sessions. This permits a clientto resynchronize its state from a previous session with the server(e.g. disconnected or offline access clients); this is discussedfurther in [IMAP-DISC].

Associated with every mailbox is a unique identifier validityvalue, which is sent in an UIDVALIDITY response code in an OK

untagged response at message selection time. If uniqueidentifiers from an earlier session fail to persist to thissession, the unique identifier validity value MUST be greater thanin the earlier session.

Note: An example of a good value to use for the uniqueidentifier validity value would be a 32-bitrepresentation of the creation date/time of the mailbox.It is alright to use a constant such as 1, but only ifit guaranteed that unique identifers will never bereused, even in the case of a mailbox being deleted anda new mailbox by the same name created at some futuretime.

Message set ranges are permitted; however, there is no guaranteethat unique identifiers be contiguous. A non-existent uniqueidentifier within a message set range is ignored without any errormessage generated.

The number after the "*" in an untagged FETCH response is always amessage sequence number, not a unique identifier, even for a UIDcommand response. However, server implementations MUST implicitlyinclude the UID message data item as part of any FETCH responsecaused by a UID command, regardless of whether UID was specifiedas a message data item to the FETCH.

Crispin [Page 36]

7/29/2019 Rfc 1730

41/78


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

6.5. Client Commands - Experimental/Expansion

6.5.1. X Command

Arguments: implementation defined

Data: implementation defined

Result: OK - command completedNO - failureBAD - command unknown or arguments invalid

Any command prefixed with an X is an experimental command.Commands which are not part of this specification, or a standardor standards-track revision of this specification, MUST use the Xprefix.

Any added untagged responses issued by an experimental commandMUST also be prefixed with an X. Server implementations MUST NOTsend any such untagged responses, unless the client requested itby issuing the associated experimental command.

Example: C: a441 CAPABILITYS: * CAPABILITY IMAP4 XPIG-LATIN

S: a441 OK CAPABILITY completedC: A442 XPIG-LATINS: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-layS: A442 OK XPIG-LATIN ompleted-cay

Crispin [Page 37]

7/29/2019 Rfc 1730

42/78


7. Server Responses

Server responses are in three forms: status responses, server data,and command continuation request.

Server response data, identified by "Data:" in the responsedescriptions below, are described by function, not by syntax. Theprecise syntax of server response data is described in the FormalSyntax section.

The client MUST be prepared to accept any response at all times.

Status responses that are tagged indicate the completion result of aclient command, and have a tag matching the command.

Some status responses, and all server data, are untagged. Anuntagged response is indicated by the token "*" instead of a tag.Untagged status responses indicate server greeting, or server statusthat does not indicate the completion of a command. For historicalreasons, untagged server data responses are also called "unsolicited

data", although strictly speaking only unilateral server data istruly "unsolicited".

Certain server data MUST be recorded by the client when it isreceived; this is noted in the description of that data. Such dataconveys critical information which affects the interpretation of allsubsequent commands and responses (e.g. updates reflecting thecreation or destruction of messags).

Other server data SHOULD be recorded for later reference; if theclient does not need to record the data, or if recording the data hasno obvious purpose (e.g. a SEARCH response when no SEARCH command isin progress), the data SHOULD be ignored.

An example of unilateral untagged responses occurs when the IMAPconnection is in selected state. In selected state, the serverchecks the mailbox for new messages as part of the execution of eachcommand. If new messages are found, the server sends untagged EXISTSand RECENT responses reflecting the new size of the mailbox. Serverimplementations that offer multiple simultaneous access to the samemailbox should also send appropriate unilateral untagged FETCH andEXPUNGE responses if another agent changes the state of any messageflags or expunges any messages.

Command continuation request responses use the token "+" instead of atag. These responses are sent by the server to indicate acceptance

of an incomplete client command and readiness for the remainder ofthe command.

Crispin [Page 38]

7/29/2019 Rfc 1730

43/78


7.1. Server Responses - Status Responses

Status responses may include an optional response code. A responsecode consists of data inside square brackets in the form of an atom,possibly followed by a space and arguments. The response codecontains additional information or status codes for client softwarebeyond the OK/NO/BAD condition, and are defined when there is aspecific action that a client can take based upon the additionalinformation.

The currently defined response codes are:

ALERT The human-readable text contains a special alertthat MUST be presented to the user in a fashionthat calls the user's attention to the message.

PARSE The human-readable text represents an error inparsing the [RFC-822] or [MIME-1] headers of amessage in the mailbox.

PERMANENTFLAGS Followed by a parenthesized list of flags,indicates which of the known flags that the clientmay change permanently. Any flags that are in theFLAGS untagged response, but not the PERMANENTFLAGSlist, can not be set permanently. If the clientattempts to STORE a flag that is not in thePERMANENTFLAGS list, the server will either rejectit with a NO reply or store the state for theremainder of the current session only. ThePERMANENTFLAGS list may also include the specialflag \*, which indicates that it is possible tocreate new keywords by attempting to store thoseflags in the mailbox.

READ-ONLY The mailbox is selected read-only, or its accesswhile selected has changed from read-write toread-only.

READ-WRITE The mailbox is selected read-write, or its accesswhile selected has changed from read-only toread-write.

TRYCREATE An APPEND or COPY attempt is failing because thetarget mailbox does not exist (as opposed to someother reason). This is a hint to the client thatthe operation may succeed if the mailbox is first

created by the CREATE command.

Crispin [Page 39]

7/29/2019 Rfc 1730

44/78


UIDVALIDITY Followed by a decimal number, indicates the uniqueidentifier validity value. See the description ofthe UID command for more detail.

UNSEEN Followed by a decimal number, indicates the numberof the first message without the \Seen flag set.

Additional response codes defined by particular client or serverimplementations should be prefixed with an "X" until they areadded to a revision of this protocol. Client implementationsshould ignore response codes that they do not recognize.

7.1.1. OK Response

Data: optional response codehuman-readable text

The OK response indicates an information message from the server.When tagged, it indicates successful completion of the associated

command. The human-readable text may be presented to the user asan information message. The untagged form indicates aninformation-only message; the nature of the information may beindicated by a response code.

The untagged form is also used as one of three possible greetingsat session startup. It indicates that the session is not yetauthenticated and that a LOGIN command is needed.

Example: S: * OK IMAP4 server readyC: A001 LOGIN fred blurdybloopS: * OK [ALERT] System shutdown in 10 minutesS: A001 OK LOGIN Completed

7.1.2. NO Response


The NO response indicates an operational error message from theserver. When tagged, it indicates unsuccessful completion of theassociated command. The untagged form indicates a warning; thecommand may still complete successfully. The human-readable textdescribes the condition.

Crispin [Page 40]

7/29/2019 Rfc 1730

45/78


Example: C: A222 COPY 1:2 owatagusiamS: * NO Disk is 98% full, please delete unnecessary dataS: A222 OK COPY completedC: A222 COPY 3:200 blurdybloopS: * NO Disk is 98% full, please delete unnecessary dataS: * NO Disk is 99% full, please delete unnecessary dataS: A222 NO COPY failed: disk is full

7.1.3. BAD Response


The BAD response indicates an error message from the server. Whentagged, it reports a protocol-level error in the client's command;the tag indicates the command that caused the error. The untaggedform indicates a protocol-level error for which the associatedcommand can not be determined; it may also indicate an internalserver failure. The human-readable text describes the condition.

Example: C: ...very long command line...S: * BAD Command line too longC: ...empty line...S: * BAD Empty command lineC: A443 EXPUNGES: * BAD Disk crash, attempting salvage to a new disk!S: * OK Salvage successful, no data lostS: A443 OK Expunge completed

7.1.4. PREAUTH Response


The PREAUTH response is always untagged, and is one of threepossible greetings at session startup. It indicates that thesession has already been authenticated by external means and thusno LOGIN command is needed.

Example: S: * PREAUTH IMAP4 server ready and logged in as Smith

Crispin [Page 41]

7/29/2019 Rfc 1730

46/78


7.1.5. BYE Response


The BYE response is always untagged, and indicates that the serveris about to close the connection. The human-readable text may bedisplayed to the user in a status report by the client. The BYEresponse may be sent as part of a normal logout sequence, or as apanic shutdown announcement by the server. It is also used bysome server implementations as an announcement of an inactivityautologout.

This response is also used as one of three possible greetings atsession startup. It indicates that the server is not willing toaccept a session from this client.

Example: S: * BYE Autologout; idle for too long

7.2. Server Responses - Server and Mailbox Status

These responses are always untagged. This is how server data aretransmitted from the server to the client, often as a result of acommand with the same name.

7.2.1. CAPABILITY Response

Data: capability listing

The CAPABILITY response occurs as a result of a CAPABILITYcommand. The capability listing contains a space-separated

listing of capability names that the server supports. The firstname in the capability listing MUST be the atom "IMAP4".

A capability name other than IMAP4 indicates that the serversupports an extension, revision, or amendment to the IMAP4protocol. Server responses MUST conform to this document untilthe client issues a command that uses the associated capability.

Capability names MUST either begin with "X" or be standard orstandards-track IMAP4 extensions, revisions, or amendmentsregistered with IANA. A server MUST NOT offer unregistered ornon-standard capability names, unless such names are prefixed withan "X".

Crispin [Page 42]

7/29/2019 Rfc 1730

47/78


Client implementations SHOULD NOT require any capability nameother than "IMAP4", and MUST ignore any unknown capability names.

Example: S: * CAPABILITY IMAP4 XPIG-LATIN

7.2.2. LIST Response

Data: name attributeshierarchy delimitername

The LIST response occurs as a result of a LIST command. Itreturns a single name that matches the LIST specification. Theremay be multiple LIST responses for a single LIST command.

Four name attributes are defined:

\Noinferiors It is not possible for any child levels ofhierarchy 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 selectablemailbox.

\Marked The mailbox has been marked "interesting" by theserver; the mailbox probably contains messages thathave been added since the last time the mailbox wasselected.

\Unmarked The mailbox does not contain any additionalmessages since the last time the mailbox wasselected.

If it is not feasible for the server to determine whether themailbox is "interesting" or not, or if the name is a \Noselectname, the server should not send either \Marked or \Unmarked.

The hierarchy delimiter is a character used to delimit levels ofhierarchy in a mailbox name. A client may use it to create childmailboxes, and to search higher or lower levels of naminghierarchy. All children of a top-level hierarchy node must usethe same separator character. A NIL hierarchy delimiter meansthat no hierarchy exists; the name is a "flat" name.

Crispin [Page 43]

7/29/2019 Rfc 1730

48/78


The name represents an unambiguous left-to-right hierarchy, andMUST be valid for use as a reference in LIST and LSUB commands.Unless \Noselect is indicated, the name must also be valid as anargument for commands, such as SELECT, that accept mailbox names.

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

7.2.3. LSUB Response

Data: name attributeshierarchy delimitername

The LSUB response occurs as a result of an LSUB command. Itreturns a single name that matches the LSUB specification. Theremay be multiple LSUB responses for a single LSUB command. Thedata is identical in format to the LIST response.

Example: S: * LSUB () "." #news.comp.mail.misc

7.2.4. SEARCH Response

Data: zero or more numbers

The SEARCH response occurs as a result of a SEARCH or UID SEARCHcommand. The number(s) refer to those messages that match thesearch criteria. For SEARCH, these are message sequence numbers;for UID SEARCH, these are unique identifiers. Each number isdelimited by a space.

Example: S: * SEARCH 2 3 6

7.2.5. FLAGS Response

Data: flag parenthesized list

The FLAGS response occurs as a result of a SELECT or EXAMINEcommand. The flag parenthesized list identifies the flags (at aminimum, the system-defined flags) that are applicable for thismailbox. Flags other than the system flags may also exist,depending on server implementation.

The update from the FLAGS response MUST be recorded by the client.

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

Crispin [Page 44]

7/29/2019 Rfc 1730

49/78


7.3. Server Responses - Message Status

These responses are always untagged. This is how message data aretransmitted from the server to the client, often as a result of acommand with the same name. Immediately following the "*" token is anumber that represents either a message sequence number or a messagecount.

7.3.1. EXISTS Response

Data: 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 mail).

The update from the EXISTS response MUST be recorded by theclient.

Example: S: * 23 EXISTS

7.3.2. RECENT Response

Data: none

The RECENT response reports the number of messages that havearrived since the previous time a SELECT command was done on thismailbox. This response occurs as a result of a SELECT or EXAMINEcommand, and if the size of the mailbox changes (e.g. new mail).

The update from the RECENT response MUST be recorded by theclient.

Example: S: * 5 RECENT

7.3.3. EXPUNGE Response

Data: none

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

untagged EXPUNGE responses).

Crispin [Page 45]

7/29/2019 Rfc 1730

50/78


As a result of the immediate decrement rule, message sequencenumbers that appear in a set of successive EXPUNGE responsesdepend upon whether the messages are removed starting from lowernumbers to higher numbers, or from higher numbers to lowernumbers. For example, if the last 5 messages in a 9-messagemailbox are expunged; a "lower to higher" server will send fiveuntagged EXPUNGE responses for message sequence number 5, whereasa "higher to lower server" will send successive untagged EXPUNGEresponses for message sequence numbers 9, 8, 7, 6, and 5.

An EXPUNGE response MUST NOT be sent when no command is inprogress; nor while responding to a FETCH, STORE, or SEARCHcommand. This rule is necessary to prevent a loss ofsynchronization of message sequence numbers between client andserver.

The update from the EXPUNGE response MUST be recorded by theclient.

Example: S: * 44 EXPUNGE

7.3.4. FETCH Response

Data: message data

The FETCH response returns data about a message to the client.The data are pairs of data item names and their values inparentheses. This response occurs as the result of a FETCH orSTORE command, as well as by unilateral server decision (e.g. flagupdates).

The current data items are:

BODY A form of BODYSTRUCTURE without extension data.

BODY[section] A string expressing the body contents of thespecified section. The string should beinterpreted by the client according to the contenttransfer encoding, body type, and subtype.

8-bit textual data is permitted if a character setidentifier is part of the body parameterparenthesized list for this section.

Non-textual data such as binary data must be

transfer encoded into a textual form such as BASE64prior to being sent to the client. To derive the

Crispin [Page 46]

7/29/2019 Rfc 1730

51/78


original binary data, the client must decode thetransfer encoded string.

BODYSTRUCTURE A parenthesized list that describes the bodystructure of a message. This is computed by theserver by parsing the [RFC-822] header and bodyinto the component parts, defaulting various fieldsas necessary.

Multiple parts are indicated by parenthesisnesting. Instead of a body type as the firstelement of the parenthesized list there is a nestedbody. The second element of the parenthesized listis the multipart subtype (mixed, digest, parallel,alternative, etc.).

Extension data follows the multipart subtype.Extension data is never returned with the BODYfetch, but may be returned with a BODYSTRUCTUREfetch. Extension data, if present, must be in the

defined order.

The extension data of a multipart body part are inthe following order:

body parameter parenthesized listA parenthesized list of attribute/value pairs[e.g. (foo bar baz rag) where "bar" is the valueof "foo" and "rag" is the value of "baz"] asdefined in [MIME-1].

Any following extension data are not yet defined inthis version of the protocol. Such extension data

may consist of zero or more NILs, strings, numbers,or potentially nested parenthesized lists of suchdata. Client implementations that do aBODYSTRUCTURE fetch MUST be prepared to accept suchextension data. Server implementations MUST NOTsend such extension data until it has been definedby a revision of this protocol.

The basic fields of a non-multipart body part arein the following order:

body typeA string giving the content type name as defined

in [MIME-1].

Crispin [Page 47]

7/29/2019 Rfc 1730

52/78


body subtypeA string giving the content subtype name asdefined in [MIME-1].

body parameter parenthesized listA parenthesized list of attribute/value pairs[e.g. (foo bar baz rag) where "bar" is the valueof "foo" and "rag" is the value of "baz"] asdefined in [MIME-1].

body idA string giving the content id as defined in[MIME-1].

body descriptionA string giving the content description asdefined in [MIME-1].

body encodingA string giving the content transfer encoding as

defined in [MIME-1].

body sizeA number giving the size of the body in octets.Note that this size is the size in its transferencoding and not the resulting size after anydecoding.

A body type of type MESSAGE and subtype RFC822contains, immediately after the basic fields, theenvelope structure, body structure, and size intext lines of the encapsulated message.

A body type of type TEXT contains, immediatelyafter the basic fields, the size of the body intext lines. Note that this size is the size in itstransfer encoding and not the resulting size afterany decoding.

Extension data follows the basic fields and thetype-specific fields listed above. Extension datais never returned with the BODY fetch, but may bereturned with a BODYSTRUCTURE fetch. Extensiondata, if present, must be in the defined order.

The extension data of a non-multipart body part are

in the following order:

Crispin [Page 48]

7/29/2019 Rfc 1730

53/78


body MD5A string giving the content MD5 value as definedin [MIME-1].

Any following extension data are not yet defined inthis version of the protocol, and would be asdescribed above under multipart extension data.

ENVELOPE A parenthesized list that describes the envelopestructure of a message. This is computed by theserver by parsing the [RFC-822] header into thecomponent parts, defaulting various fields asnecessary.

The fields of the envelope structure are in thefollowing order: date, subject, from, sender,reply-to, to, cc, bcc, in-reply-to, and message-id.The date, subject, in-reply-to, and message-idfields 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 thatdescribes an electronic mail address. The fieldsof an address structure are in the following order:personal name, [SMTP] at-domain-list (sourceroute), mailbox name, and host name.

[RFC-822] group syntax is indicated by a specialform of address structure in which the host namefield is NIL. If the mailbox name field is alsoNIL, this is an end of group marker (semi-colon inRFC 822 syntax). If the mailbox name field is

non-NIL, this is a start of group marker, and themailbox name field holds the group name phrase.

Any field of an envelope or address structure thatis not applicable is presented as NIL. Note thatthe server must default the reply-to and senderfields from the from field; a clien

Rfc 1730

Documents

Transcript of Rfc 1730