Microsoft KB Archive/189325

= XADM: IMAP4 Client/Server Commands =

Article ID: 189325

Article Last Modified on 10/28/2006

-

APPLIES TO


 * Microsoft Exchange Server 5.5 Standard Edition

-



This article was previously published under Q189325



SUMMARY
This article explains the Internet Message Access Protocol, Version 4 rev. 1 (IMAP4rev1) features and commands.



MORE INFORMATION
FEATURES:

1. IMAP4rev1 client allows the user to access and manipulate electronic messages on a server. 2. IMAP4rev1 permits manipulation of remote message folders, called mailboxes, in a way that is functionally equivalent to local mailboxes. 3. IMAP4rev1 also provides the capability for an offline client to re- synchronize with the server (see also [IMAP-DISC]). 4. IMAP4rev1 includes operations for creating, deleting, and renaming mailboxes. 5. IMAP4rev1 checks for new messages, permanently removes messages, and sets and clears flags [RFC-822]. 6. IMAP4rev1 does [MIME-IMB] parsing, searching, and selective fetching of  message attributes, texts, and portions thereof. 7. Messages in IMAP4rev1 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers.

COMMANDS and RESPONSES:

An IMAP4rev1 connection consists of the establishment of a  client/server network connection, an initial greeting from the server, and client/server interactions. These client/server interactions consist of a client command, server data, and a server completion result response.

Non-Authenticated State In a non-authenticated state, the client MUST supply authentication credentials before most commands are permitted. This state is  entered when a connection starts, unless the connection has been pre- authenticated.

Authenticated State In an authenticated state, the client is authenticated and MUST select a  mailbox to access before commands that affect messages are permitted. This state is entered when a pre-authenticated connection starts, when acceptable authentication credentials have been provided, or after an  error in selecting a mailbox.

CLIENT COMMANDS - ANY STATE:

CAPABILITY Command

Arguments: none Responses: REQUIRED untagged response: CAPABILITY Result:    OK - capability completed BAD - command unknown or arguments invalid

The CAPABILITY command requests a listing of capabilities that the server supports.

Example: C: abcd CAPABILITY S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4 S: abcd OK CAPABILITY completed

NOOP Command

Arguments: none Responses: no specific responses for this command (but see below) Result:    OK - noop completed BAD - command unknown or arguments invalid

The NOOP command always succeeds. It does nothing.

Example: C: a002 NOOP S: a002 OK NOOP completed. . .              C: a047 NOOP S: * 22 EXPUNGE S: * 23 EXISTS S: * 3 RECENT S: * 14 FETCH (FLAGS (\Seen \Deleted)) S: a047 OK NOOP completed

LOGOUT Command

Arguments: none Responses: REQUIRED untagged response: BYE Result:    OK - logout completed BAD - command unknown or arguments invalid

The LOGOUT command informs the server that the client is done with the connection. Example: C: A023 LOGOUT S: * BYE IMAP4rev1 Server logging out S: A023 OK LOGOUT completed (Server and client then close                 the connection)

CLIENT COMMANDS - NON-AUTHENTICATED STATE:

AUTHENTICATE Command

Arguments: authentication mechanism name 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 cancelled

The AUTHENTICATE command indicates an authentication mechanism to the server. Example: S: * OK KerberosV4 IMAP4rev1 Server C: A001 AUTHENTICATE KERBEROS_V4 S: + AmFYig== C:              S: + or//EoAADZI= C: DiAF5A4gA+oOIALuBkAAmw== S: A001 OK Kerberos V4 authentication successful

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 plain text password authenticating this user.

Example: C: a001 LOGIN  S: a001 OK LOGIN completed

CLIENT COMMANDS - AUTHENTICATED STATE:

SELECT Command

Arguments: mailbox name Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT OPTIONAL OK untagged responses: UNSEEN, PERMANENTFLAGS Result:    OK - select completed, now in selected state NO - select failure, now in authenticated state: no                   such mailbox, cannot access mailbox BAD - command unknown or arguments invalid

The SELECT command selects a mailbox so that messages in the mailbox can be accessed.

Example: C: A142 SELECT INBOX S: * 172 EXISTS S: * 1 RECENT S: * OK [UNSEEN 12] Message 12 is first unseen S: * OK [UIDVALIDITY 3857529045] UIDs valid S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited S: A142 OK [READ-WRITE] SELECT completed

EXAMINE Command

Arguments: mailbox name Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT OPTIONAL OK untagged responses: UNSEEN, PERMANENTFLAGS Result:    OK - examine completed, now in selected state NO - examine failure, now in authenticated state: no                   such mailbox, cannot access mailbox BAD - command unknown or arguments invalid

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

Example: C: A932 EXAMINE S: * 17 EXISTS S: * 2 RECENT S: * OK [UNSEEN 8] Message 8 is first unseen S: * OK [UIDVALIDITY 3857529045] UIDs valid S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) S: * OK [PERMANENTFLAGS ] No permanent flags permitted S: A932 OK [READ-ONLY] EXAMINE completed

CREATE Command

Arguments: mailbox name Responses: no specific responses for this command Result:    OK - create completed NO - create failure: cannot create mailbox with that name BAD - command unknown or arguments invalid

The CREATE command creates a mailbox with the given name. An OK response is returned only if a new mailbox with that name has been created.

Example: C: A003 CREATE S: A003 OK CREATE completed C: A004 CREATE  S: A004 OK CREATE completed

DELETE Command

Arguments: mailbox name Responses: no specific responses for this command Result:    OK - delete completed NO - delete failure: cannot delete mailbox with that name BAD - command unknown or arguments invalid

The DELETE command permanently removes the mailbox with the given name. A tagged OK response is returned only if the mailbox has been deleted.

Examples: C: A682 LIST "" *                     S: A687 OK DELETE Completed S: * LIST "/"        C: A82 LIST "" * S: * LIST (\Noselect) "/"    S: * LIST  "." S: * LIST "/"  C: A683 DELETE      S: A82 OK LIST completed S: A683 OK DELETE completed             C: A83 DELETE C: A684 DELETE      S: A83 OK DELETE completed S: A684 NO Name     C: A84 DELETE C: A685 DELETE  S: A84 OK DELETE Completed S: A685 OK DELETE Completed          C: A85 LIST "" * C: A686 LIST "" *                    S: * LIST  "." > S: * LIST (\Noselect) "/"    S: A85 OK LIST completed S: A686 OK LIST completed               C: A86 LIST "" % C: A687 DELETE      S: * LIST (\Noselect) "." S: A86 OK LIST completed

RENAME Command

Arguments: existing mailbox name new mailbox name Responses: no specific responses for this command Result:    OK - rename completed NO - rename failure: cannot rename mailbox with that name, cannot rename to mailbox with that name BAD - command unknown or arguments invalid

The RENAME command changes the name of a mailbox. A tagged OK response is returned only if the mailbox has been renamed.

Examples: C: A682 LIST "" *                  S: * LIST (\Noselect) "/" S: * LIST "/"      S: * LIST  "/"    S: * LIST  "." S: A682 OK LIST completed          S: * LIST  "."  C: A683 RENAME S: Z432 OK LIST completed S: A683 OK RENAME completed        C: Z433 RENAME  C: A684 RENAME S: Z433 OK RENAME completed S: A684 OK RENAME Completed        C: Z434 LIST "" * C: A685 LIST "" *                  S: * LIST  "." S: * LIST                        S: * LIST  "."  S: * LIST "/"      S: * LIST  "." old-mail S: Z434 OK LIST completed

SUBSCRIBE Command

Arguments: mailbox Responses: no specific responses for this command Result:    OK - subscribe completed NO - subscribe failure: cannot subscribe to that name BAD - command unknown or arguments invalid

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

Example: C: A002 SUBSCRIBE # S: A002 OK SUBSCRIBE completed

UNSUBSCRIBE Command

Arguments: mailbox name Responses: no specific responses for this command Result:    OK - unsubscribe completed NO - unsubscribe failure: cannot unsubscribe that name BAD - command unknown or arguments invalid

The UNSUBSCRIBE command removes the specified mailbox name from the server's set of "active" or "subscribed" mailboxes as returned by the LSUB command. This command returns a tagged OK response only if the unsubscription is successful.

Example: C: A002 UNSUBSCRIBE # S: A002 OK UNSUBSCRIBE completed

LIST Command

Arguments: reference name mailbox name with possible wildcards Responses: untagged responses: LIST Result:    OK - list completed NO - list failure: cannot list that reference or name BAD - command unknown or arguments invalid

The LIST command returns a subset of names from the complete set of all names available to the client.

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

LSUB Command

Arguments: reference name mailbox name with possible wildcards Responses: untagged responses: LSUB Result:    OK - lsub completed NO - lsub failure: cannot list that reference or name BAD - command unknown or arguments invalid

The LSUB command returns a subset of names from the set of names that the user has declared as being "active" or "subscribed".

Example: C: A002 LSUB "#newsgroup." "newsgroup.*" S: * LSUB "." #news.comp.mail.mime S: * LSUB "." #news.comp.mail.misc S: A002 OK LSUB completed

STATUS Command

Arguments: mailbox name status data item names Responses: 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 (in particular, STATUS MUST NOT cause messages to lose the \Recent flag).

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

APPEND Command

Arguments: mailbox name OPTIONAL flag parenthesized list OPTIONAL date/time string message literal Responses: no specific responses for this command Result:    OK - append completed NO - append error: cannot append to that mailbox, error in flags or date/time or message text BAD - command unknown or arguments invalid

The APPEND command appends the literal argument as a new message to the end of the specified destination mailbox. This argument SHOULD be in the format of an [RFC-822] message.

Example: C: A003 APPEND saved-messages (\Seen) {310} C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) C: From: User Name  C: To: username@domainname.com C: Message-Id:  C: MIME-Version: 1.0 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII C: Subject: afternoon meeting C: C: Hello, do you think we can meet at 3:30 tomorrow? S: A003 OK APPEND completed

CLIENT COMMANDS - SELECTED STATE:

CHECK Command

Arguments: none Responses: no specific responses for this command Result:    OK - check completed BAD - command unknown or arguments invalid

The CHECK command requests a checkpoint of the currently selected mailbox. A checkpoint refers to any implementation-dependent housekeeping associated with the mailbox (for example, resolving the server's in-memory state of the mailbox with the state on its disk) that is not normally executed as part of each command.

Example: C: FXXZ CHECK S: FXXZ OK CHECK Completed

CLOSE Command

Arguments: none Responses: no specific responses for this command Result:    OK - close completed, now in authenticated state NO - close failure: no mailbox selected BAD - command unknown or arguments invalid

The CLOSE command permanently removes from the currently selected mailbox all messages that have the \Deleted flag set, and returns to authenticated state from selected state.

Example: C: A341 CLOSE S: A341 OK CLOSE completed

EXPUNGE Command

Arguments: none Responses: untagged responses: EXPUNGE Result:    OK - expunge completed NO - expunge failure: cannot expunge (for example,                   Permission denied) BAD - command unknown or arguments invalid

The EXPUNGE command permanently removes from the currently selected mailbox all messages that have the \Deleted flag set.

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

SEARCH Command

Arguments: OPTIONAL [CHARSET] specification searching criteria (one or more) Responses: REQUIRED untagged response: SEARCH Result:    OK - search completed NO - search error: cannot search that [CHARSET] or                   criteria BAD - command unknown or arguments invalid

The SEARCH command searches the mailbox for messages that match the given searching criteria. Searching criteria consist of one or more search keys:

Messages with message sequence numbers corresponding to the specified message sequence number set.

ALL           All messages in the mailbox.

ANSWERED      Messages with the \Answered flag set.

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

BEFORE Messages whose internal date is earlier than the specified date.

BODY Messages that contain the specified string in the body of the message.

CC   Messages that contain the specified string in the envelope 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 the envelope structure's FROM field.

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

KEYWORD Messages with the specified keyword set.

LARGER <n>    Messages with an [RFC-822] size larger than the specified number of octets.

NEW           Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to                    "(RECENT UNSEEN)".

NOT <search-key> Messages that do not match the specified search key.

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

ON     Messages whose internal date is within the specified date.

OR <search-key1> <search-key2> 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 the specified date.

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

SINCE  Messages whose internal date is within or later than the specified date.

SMALLER <n>   Messages with an [RFC-822] size smaller than the specified number of octets.

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

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

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

UID Messages with unique identifiers corresponding to                    the specified unique identifier set.

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 keyword set.

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

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

FETCH Command

Arguments: message set message data item names Responses: untagged responses: FETCH Result:    OK - fetch completed NO - fetch error: cannot fetch that data BAD - command unknown or arguments invalid

The FETCH command retrieves data associated with a message in the mailbox. The currently defined data items that can be fetched are:

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

BODY          Non-extensible form of BODYSTRUCTURE.

BODY[ ]< > The text of a particular body section. The section specification is a set of zero or more part specifiers delimited by periods. A part specifier is either a part number or one of the following: HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, MIME, and TEXT. An empty section specification refers to the entire message, including the header.

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

STORE Command

Arguments: message set message data item name value for message data item Responses: untagged responses: FETCH Result:    OK - store completed NO - store error: cannnot store that data BAD - command unknown or arguments invalid

The STORE command alters data associated with a message in the mailbox.

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

COPY Command

Arguments: message set mailbox name Responses: no specific responses for this command Result:    OK - copy completed NO - copy error: cannot 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.

Example: C: A003 COPY 2:4 MEETING S: A003 OK COPY completed

UID Command

Arguments: command name command arguments Responses: untagged responses: FETCH, SEARCH Result:    OK - UID command completed NO - UID command error BAD - command unknown or arguments invalid

The UID command has two forms. In the first form, it takes as its arguments a COPY, FETCH, or STORE command with arguments appropriate for the associated command. In the second form, the UID command takes a SEARCH command with SEARCH command arguments.

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 UID FETCH completed

Keywords: kbinfo KB189325

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.