IMAP

From Postmaster Administration Wiki
Jump to: navigation, search
Mail-agents.png

Internet Message Access Protocol

IMAP is a complex mail retrieval protocol. Unlike POP, it allows concurrent access to the same user account and mail boxes by multiple clients. IMAP provides for selective reading of mail message parts, such as headers, message body, and attachments, without having to read the whole message; server side searches; shared mail/news folders; and even the sending of mail by uploading to a drop box for those IMAP servers that support it. There are several RFC documents for IMAP revisions and extensions.

Protocol Summary

IMAP is a service available on port 143 and/or the SSL port 993. It is an asynchronous request-reply human readable protocol. Each command in IMAP begins with a tag string, which the corresponding reply uses when the command is completed; successful commands reply with "tag OK text" and failed commands with "tag BAD text". An asterisk (*) tag indicates server notification messages and/or supplemental information. The command tagging is used to distinguish which commands have completed. Because of IMAP's asynchronous nature, multiple commands can be sent before reading any replies, and the replies might not return in the same order in which the commands were given. Also, the server can push untagged notification messages, like indicating the arrival of new mail, interspersed with tagged replies. All the examples below are shown in synchronous order.

Using a telnet client one can connect to port 143 of a mail store and get a "* OK text" welcome banner, after which the following commands can be used starting with LOGIN. There are other IMAP commands in the protocol, but those below tend to be sufficient for manual testing.

The C: And S: denote which lines are sent from the client and server respectively. They are not part of input or output.

tag LOGIN "username" "password"

Clear text authentication. Some IMAP servers require that the session enable encryption with STARTTLS, before accepting clear text authentication. IMAP also supports an AUTHENTICATE command, which is better suited for use by IMAP client software than it is for manual testing.

S: * OK [CAPABILITY IMAP4REV1 STARTTLS] marvin.example.com IMAP4rev1 2007e.404 at Wed, 10 Apr 2013 08:50:24 -0500 (EST)
C: A001 LOGIN "Slartibartfast" "HHgTTg"
S: A001 OK [CAPABILITY IMAP4REV1 IDLE UIDPLUS NAMESPACE CHILDREN] User Slartibartfast authenticated


tag LOGOUT

Close an IMAP session and connection.

C: A000 LOGOUT
S: * BYE marvin.example.com IMAP4rev1 server terminating connection
S: A000 OK LOGOUT completed


tag STARTTLS

An IMAP connection on port 143 starts unencrypted. This command requests that the server start TLS, communication channel encryption. Some IMAP servers require TLS before accepting clear-text user authentication. It is not possible to test STARTTLS using telnet, see Manually Test STARTTLS.

tag CAPABILITY

Request the list of IMAP server capabilities. This can be used without having authenticated.

C: A002 CAPABILITY
S: * CAPABILITY IMAP4REV1 I18NLEVEL=1 LITERAL+ IDLE UIDPLUS NAMESPACE CHILDREN MAILBOX-REFERRALS
     BINARY UNSELECT ESEARCH WITHIN SCAN SORT THREAD=REFERENCES THREAD=ORDEREDSUBJECT MULTIAPPEND
     SASL-IR LOGIN-REFERRALS STARTTLS
S: A002 OK CAPABILITY completed


tag NOOP

Do nothing. Sometimes used to poll for server messages and/or keep a LOGIN session from timing out.


tag SELECT "mailbox"

Select a mailbox to work on. The special name INBOX can be used. The mailbox might be personal mail folders, shared mail folders, read-only news, or another name space. Please refer to the RFC concerning mailbox names and names-spaces. The SELECT command will generate several supplemental lines describing the current state of the selected mailbox. One can use SELECT to switch between multiple mailboxes without having to UNSELECT or CLOSE first.

C: A003 SELECT INBOX
S: * 1 EXISTS
S: * 0 RECENT
S: * OK [UIDVALIDITY 1306242239] UID validity status
S: * OK [UIDNEXT 32] Predicted next UID
S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen)
S: * OK [PERMANENTFLAGS (\* \Answered \Flagged \Deleted \Draft \Seen)] Permanent flags
S: * OK [UNSEEN 1] first unseen message in /var/mail/Slartibartfast
S: A003 OK [READ-WRITE] SELECT completed


tag EXAMINE "mailbox"

Same as SELECT, except that the mailbox is selected read-only.


tag STATUS "mailbox" (items)

Report mail box information without changing the current selected mailbox. All this information is supplied by SELECT or EXAMINE too. The item list can contain one or more of the following: MESSAGES RECENT UIDNEXT UIDVALIDITY UNSEEN.


tag SUBSCRIBE "mailbox"

Add a mailbox to the user's subscription list.


tag UNSUBSCRIBE "mailbox"

Remove a mailbox from the user's subscription list.


tag LIST "reference" "pattern"

List is similar to Unix ls(1) or MSDOS dir commands in that it can list a name space's hierarchy. If reference is the empty string, then the current SELECT mailbox is used. If pattern is the empty string, then this is a special request to return the mailbox's hierarchy delimiter and the root of the reference name. The hierarchy delimiter can be NIL for a flat name space. The root can be non-rooted, as indicated by the empty string.

C: A004 LIST "" ""
S: * LIST (\NoSelect) "/" ""
S: A004 OK LIST completed#

The pattern can contain the asterisk (*) wildcard, which matches zero or more characters. The percent (%) wildcard matches zero or more characters, excluding the hierarchy delimiter. Note that the interpretation of the reference is implementation defined; most cases should end with the hierarchy delimiter as it is implementation defined as to how the reference and pattern are concatenated. See RFC 3501 section 6.3.8.


tag LSUB "reference" "pattern"

Return a subset of names from the user's subscription list. It uses the same arguments as LIST.


tag CLOSE

Delete all messages marked with the \Deleted flag in the currently selected mailbox and deselect the mailbox. This is similar to EXPUNGE, without all the extra untagged response lines.


tag UNSELECT

Deselect the current mailbox, without deleting messages. It's also possible to simply SELECT a new mailbox without a previous UNSELECT of the current one.


tag FETCH sequence_set item_list

Retrieve message details, such as structure, size, flags, header, envelope, and even actual message content, whole or in part.

A sequence_set is a comma-separated list of message index numbers and/or ranges from within the currently selected mailbox; a range is given by a start-number colon (:) end-number. Message index numbers count upwards from one (1). For example:

C: A005 FETCH 2:4,11 FLAGS
S: * 2 FETCH (FLAGS (\Seen \Answered))
S: * 3 FETCH (FLAGS (\Seen \Answered))
S: * 4 FETCH (FLAGS (\Seen \Answered))
S: * 11 FETCH (FLAGS (\Recent))
S: A005 OK FETCH completed

The item_list is a single item or parenthesised list of items, as given in RFC 3501 section 6.4.5. The example below has a simple item_list that requests the FLAGS and complete message content.

C: A006 FETCH 1 (FLAGS BODY[])
S: * 1 FETCH (FLAGS (\Recent) BODY[] {480}
S: Return-Path: <Slartibartfast@example.com>
S: Received: from galatic.example.net (galatic.example.net [192.0.2.1])
S:         by marvin.example.com (8.14.4/8.14.4) with ESMTP id r3AI0ZgK008922
S:         for <Slartibartfast@example.com>; Wed, 10 Apr 2013 13:00:43 -0500 (EST)
S: Date: Wed, 10 Apr 2013 13:00:35 -0500 (EST)
S: From: Joey Bloggs <joey@example.net>
S: Message-Id: <201304101800.r3AI0ZYZ014672@example.net>
S: To: Slartibartfast@example.com
S: Subject: FETCH example
S:
S: Hello world!
S: )
S: * 1 FETCH (FLAGS (\Recent \Seen))
S: A006 OK FETCH completed

tag STORE sequence_set item (flag_list)

Used to add (+FLAGS, +FLAGS.SILENT), remove (-FLAGS, -FLAGS.SILENT), or replace (FLAGS, FLAGS.SILENT) the flags for one or more messages.

C: A123 STORE 2:3 +FLAGS.SILENT (\Deleted)
S: A123 OK STORE completed


References

  • RFC 3501 Internet Message Access Protocol - Version 4Rev1
  • RFC 3691 Internet Message Access Protocol (IMAP) UNSELECT command
  • Wikipedia IMAP overview