TOC 
Internet Engineering Task ForceI. Radu, Ed.
Internet-DraftMay 14, 2010
Intended status: Informational 
Expires: November 15, 2010 


Advanced Groupware Access Protocol
draft-iulian-advanced-groupware-access-protocol-01

Abstract

The Advanced Groupware Access Protocol, (AGAP) allows a client to access and store electronic mail messages, contacts, events, files, and configurations on a server. The electronic mail messages can be grouped in folders. AGAP also provides the capability for an offline client to resynchronize with the server.

AGAP does not specify a means of posting electronic mail messages; this function is handled by a mail transfer protocol such as SMTP (Klensin, J., “Simple Mail Transfer Protocol,” April 2001.) [RFC2821]. It also does not specify a means for exchanging messages with contacts that are reported as being online; this function is handled by an instant messaging protocol such as XMPP (Saint-Andre, P., Ed., “Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence,” October 2004.) [RFC3921].

AGAP includes the following operations for electronic mail messages: creating, deleting, renaming, moving and coping mail folders; checking for new messages; permanently removing messages; moving and coping messages between folders; fetching information about a message; setting and clearing tags for messages; searching in messages; retrieving only a part of a message; marking messages as spam; deleting attachments from a message.

AGAP includes the following operations to manipulate the contacts: creating, deleting, moving, coping, tagging, and searching contacts; checking if a contact is online; fetching information about a contact.

AGAP includes the following operations related to the use of the events: creating, deleting, moving, coping and tagging events in calendar; fetching events details; searching for events.

All entries are read and written in format XML encoded UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] and each entry is identified by a unique alphanumeric identifier.

AGAP is designed to support access only to a single server per connection. It is also designed to balance the volume of text exchanged between the server and clients and its readability by humans for debugging.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on November 15, 2010.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.



Table of Contents

1.  How to Read This Document
1.1.  Organization of This Document
1.2.  Conventions Used in This Document
2.  Protocol Overview
2.1.  Charset Used for Commands and Responses
2.2.  Maximal Length of a Command or Response Line
2.3.  Numbers in Commands and Responses
2.4.  Regular Expressions in Commands
2.5.  Unique Identification Numbers
2.6.  Folders
2.6.1.  Naming
2.6.2.  Hierarchy
2.6.3.  Folder Types
2.6.4.  Reserved Folders
2.7.  Tags
2.7.1.  Syntax
2.7.2.  Reserved Tag Names
2.8.  The Responses for Each Type of Folder
2.8.1.  Format and Conventions
2.8.2.  Response for Configuration Folders
2.8.3.  Response for Contact Folders
2.8.4.  Response for Event (Calendar, Journal, Task) Folders
2.8.5.  Response for File Folders
2.8.6.  Response for Filter Folders
2.8.7.  Response for Message Folders
2.8.8.  Response for Note Folders
3.  States
3.1.  Not-authenticated State
3.2.  Pre-authentication State
3.3.  Authenticated (and Selected) State
3.4.  (Authenticated but) Not-selected State
4.  Commands
4.1.  Semantic and Syntax
4.2.  Syntax of a Tag List
4.3.  Syntax of a Filter
4.3.1.  Syntax of a Filter for a Command
4.3.2.  Syntax of a Filter for a FILT Folder
4.4.  The Welcome Message - not-authenticated state
4.5.  Command QUIT - all states
4.6.  Command AUTH mechanism - not-authenticated state
4.7.  Command CAPA - not-authenticated state
4.8.  Command SGZP - not-authenticated state
4.9.  Command STLS - not-authenticated state
4.10.  Command PASS password - pre-authenticated state (PLAIN)
4.11.  Command USER account - pre-authenticated state (PLAIN)
4.12.  Command COPY - authenticated state
4.13.  Command CPYF - authenticated state
4.14.  Command DATT - authenticated state (MESG folder type)
4.15.  Command DELE - authenticated state
4.16.  Command DELF - authenticated state
4.17.  Command EXIT - authenticated state
4.18.  Command FCPY - authenticated state
4.19.  Command FDEL - authenticated state
4.20.  Command FIND - authenticated state
4.21.  Command FMOV - authenticated state
4.22.  Command FTAG - authenticated state
4.23.  Command GTAG - authenticated state
4.24.  Command LIST - authenticated and not-selected state
4.25.  Command MAKE - authenticated state
4.26.  Command MOVE - authenticated state
4.27.  Command MOVF - authenticated state
4.28.  Command NAME - authenticated state
4.29.  Command NOOP - authenticated state
4.30.  Command RETR - authenticated state
4.31.  Command SLCT - authenticated and not-selected state
4.32.  Command SPAM - authenticated state (MESG folder type)
4.33.  Command STAG - authenticated state
4.34.  Command STAT - authenticated state
4.35.  Command STOR - authenticated state
5.  Responses
5.1.  Semantic and Syntax
5.2.  1xx Informational
5.2.1.  100 Reserved
5.2.2.  110 Continue
5.3.  2xx Success
5.3.1.  200 OK
5.4.  4xx Temporary Server Error
5.4.1.  400 Reserved
5.4.2.  401 Internal Error
5.4.3.  410 Retry later
5.5.  5xx Permanent Server Error
5.5.1.  500 Reserved
5.5.2.  510 Unknown Command
5.5.3.  511 Invalid Parameter
5.5.4.  512 Out of order
5.5.5.  521 Not found
5.5.6.  531 Banned
6.  All Possible Response Codes for All Commands
6.1.  Not-authenticated State
6.2.  Pre-authenticating State (PLAIN method)
6.3.  Authenticated State
6.4.  Not-selected State
7.  Example of Conversations
7.1.  Successful connection and authentication
7.2.  Successful connection but unsuccessful authentication
7.3.  Connection refused
7.4.  Find what folders are available with messages
7.5.  Retrieve a message
7.6.  Retrieve a contact
7.7.  Retrieve an event
7.8.  Store a message
7.9.  Store a contact
7.10.  Store an event
7.11.  Mark messages as SPAM an move them in a new folder
7.12.  Create a filter folder, find the matching entries of the filter and read its filter definition
7.13.  Create a folder and rename it
7.14.  Find the status for a folder
7.15.  Set and check the tags of a message
7.16.  Find messages that can be SPAM and delete them
8.  References
8.1.  Normative References
8.2.  Informative References
§  Author's Address




 TOC 

1.  How to Read This Document



 TOC 

1.1.  Organization of This Document

This document is written from the point of view of someone implementing an AGAP client or server, and also from the point of view of a server administrator. The protocol overview (chapter 2) presents all aspects related to a correct implementation (like the maximum length of a command or response line, charset used). The material in chapter 3 through 5 provides the states in which can be a connection at a moment, respectively what commands are valid in each state and their valid responses. Chapter 6 makes a summary of the return codes for each command. The implementers find in chapter 7 samples of conversations so that they can test the compliance of their applications with this standard.



 TOC 

1.2.  Conventions Used in This Document

Document conventions are noted in this chapter. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT","MAY", and "OPTIONAL" in this document are to be interpreted as described in 'Key words for use in RFCs to Indicate Requirement Levels' (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119]. The word "CAN" (not "MAY") is used to refer to a possible circumstance or situation, as opposed to an optional facility of the protocol.

"User" is used to refer to a human user. "Client" refers to the software being run by the user. "Server" refers to the software responding to the client requests. In examples, "C:" and "S:" indicate lines sent by the client and server respectively. "Connection" refers to the entire sequence of client/server interaction from the initial establishment of the network connection until its termination. "Conversation" is an exchange of commands and responses between the client and the server. "Account" defines all folders and their content that can be accessed from Authenticated State. All references to characters order is according to the UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] specification.



 TOC 

2.  Protocol Overview



 TOC 

2.1.  Charset Used for Commands and Responses

All data exchanged between the server and the client is done using strings encoded UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629]. If the server or client send a string incorrect encoded then the other side can close immediately the connection.



 TOC 

2.2.  Maximal Length of a Command or Response Line

A command or response consists of a line of text that has a maximal length of 1024 characters (including line end). A line of text is ended with the character LF (0x0A). There can be optionally a CR character (0x0D) before the LF character. If the server or client sends a line with a length greater of 1024 then the other side can close immediately the connection.



 TOC 

2.3.  Numbers in Commands and Responses

The numbers that are used in commands are signed integers on 32 bits. The valid values are between -2,147,483,648 and 2,147,483,647.



 TOC 

2.4.  Regular Expressions in Commands

Following is a resume of all regular expression rules that CAN be used by the commands defined in this standard:


    Logical operators:
XY       X followed by Y
X|Y      Either X or Y

    Predefined character class:
.        Any character (does not match line terminators)

    Characters:
x        The character x
\\       The backslash character
\xhh     The character with hexadecimal value 0xhh
\uhhhh   The character with hexadecimal value 0xhhhh
\t       The tab character ('\x09')
\n       The newline (line feed) character ('\x0A')
\r       The carriage-return character ('\x0D')

    Character classes:
[abc]     a, b, or c (simple class)
[^abc]    Any character except a, b, or c (negation)
[a-zA-Z]  a through z or A through Z, inclusive (range)

    Boundary matchers:
^        The beginning of a line
$        The end of a line
\b       A word boundary
\B       A non-word boundary

    Greedy quantifiers:
X?       X, once or not at all
X*       X, zero or more times
X+       X, one or more times
X{n}     X, exactly n times
X{n,}    X, at least n times
X{n,m}   X, at least n but not more than m times

    Reluctant quantifiers:
X??      X, once or not at all
X*?      X, zero or more times
X+?      X, one or more times
X{n}?    X, exactly n times
X{n,}?   X, at least n times
X{n,m}?  X, at least n but not more than m times

 Figure 1 



 TOC 

2.5.  Unique Identification Numbers

The length of an UID is between 1 and 32 characters.

The UIDs MUST to be unique only between entries from the same folder.

The characters accepted for building an UID are only all 26 Latin letters (A-Z) in lowercase and uppercase and all 10 Latin digits (0-9). An UID is case sensitive and it is valid only for the current connection (the same message/contact/event CAN have different UIDs for different client connections).

Any new message/contact/event MUST to have a bigger UID as all other existing entries in the selected folder. The sorting is made according UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] (digits before letters and uppercase letters before the lowercase letters - 0..9A..Za..z). A short UID is before a longer one (9234 before 02345) and any zero (0) before a number is take into account by the server when two UIDs are compared.

We get an approximately maximum number of 3.15e+85 unique combinations for 64 characters long UIDs. We get a maximum number of 136325893334400 unique combinations for 8 characters long UIDs .



 TOC 

2.6.  Folders



 TOC 

2.6.1.  Naming

All folder names are case sensitive and they are encoded according to UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629].

A backslash (\) does not escape the character after it (it has no special meaning).

For building a folder name, the user CAN use all UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] characters with a value bigger then 0x1f (white space is the first allowed character), but with the exception of the slash (/ 9x2F) and back slash (\ 0x5C).

The following folder names are not accepted: '.', and '..'.



 TOC 

2.6.2.  Hierarchy

None of the reserved folders can have subfolders, exception makes the TRASH that must to store also deleted folders and FILESHARE that holds ordinary files.

The character used for delimiting path levels is the slash (/). A path that starts with '/' represents an absolute path. All other are relative to the currently selected folder (with SLCT).

If there is no folder currently selected then the client MUST use only absolute paths. It is recommended for a client to use always absolute paths.



 TOC 

2.6.3.  Folder Types

The following folder types are defined by this standard:



 TOC 

2.6.4.  Reserved Folders

All the following reserved folders are located in the root of the user's account:

A client can use different names for these folders when display them so that the client application can use localization and standard or customized names for them. If this is the case, then the user cannot create a folder, in the root of his account, with the same name as the real (reserved) name of the folder.



 TOC 

2.7.  Tags



 TOC 

2.7.1.  Syntax

The client can set tags only for folder entries, but the server can set tags also for folders. The tags of a folder are reported by the STAT command.

The format of a tag is a name optionally followed by the equal sign (=) and a value. Each time is set a tag, the new value replace the old one. All tags that have no value assigned are returned as name only. Assigning an empty value to a tag makes it to return a name followed by the equal sign and no value. (This means that once a value is assigned to a tag, it will always be returned together with an equal sign.) Hint: Deleting and setting again (without a value) a tag that previously had a value will make it being returned without an equal sign.



 TOC 

2.7.2.  Reserved Tag Names

The following tag names have a meaning set by this standard:



 TOC 

2.8.  The Responses for Each Type of Folder



 TOC 

2.8.1.  Format and Conventions

All responses are in XML format. The tags and their attributes names are written only in lowercase.

The content is encoded in UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] format.

Each type of folder returns its entries in a different format.

Each tag written in uppercase must to be send as it is, each tag written in lowercase will be replaced with the right value at the time of generation.

Each tag that have a star will be present only if it is the case and without the star.

If a command is correct but the server cannot execute it because of an internal error, then the server returns the code 401.



 TOC 

2.8.2.  Response for Configuration Folders

A response holding the configuration has the following structure:


<CONFIGURATION>
    <name>value</name>
</CONFIGURATION>

 Figure 2 

Example:


<configuration>
    <quota>1024</quota>
</configuration>

 Figure 3 



 TOC 

2.8.3.  Response for Contact Folders

The format is the same as the one defined by the vCard XML Representation (Perreault, S., “vCard XML Representation,” May 2010.) [I‑D.ietf‑vcarddav‑vcardxml] standard (work in progress).

Example:


<vcards xmlns="urn:ietf:params:xml:ns:vcard-4.0">
     <vcard>
       <fn><text>Iulian Radu</text></fn>
       <n>
         <surname><text>Radu</text></surname>
         <given><text>Iulian</text></given>
         <suffix>
           <text>Dipl.-Ing.</text>
         </suffix>
       </n>
       <sex>1</sex>
       <lang>
         <parameters><pref>1</pref></parameters>
         <language-tag>de</language-tag>
       </lang>
       <org>
         <parameters><type>work</type></parameters>
         <text>Example Com</text>
       </org>
       <email>
         <parameters><type>work</type></parameters>
         <text>iulian.radu@gmx.at</text>
       </email>
       <class>PUBLIC</class>
    </vcard>
</vcards>

 Figure 4 



 TOC 

2.8.4.  Response for Event (Calendar, Journal, Task) Folders

The format is the same as the one defined by the xCal (Daboo, C., Douglass, M., and S. Lees, “xCal: The XML format for iCalendar,” March 2010.) [I‑D.daboo‑et‑al‑icalendar‑in‑xml] standard (work in progress).

The following example corresponds to this event definition:


BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//amap/calender//NONSGML v1.0//EN
BEGIN:VEVENT
UID:uidx1234@example.com
DTSTAMP:20100701T110000Z
ORGANIZER;CN=RFC Amap:MAILTO:rfc@example.com
DTSTART:20101102T000000Z
DTEND:20101102T235959Z
SUMMARY:AGAP RFC Party
END:VEVENT
END:VCALENDAR

 Figure 5 

Example:


<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
    <vcalendar>
        <properties>
            <prodid>
                <text>-//amap/calender//NONSGML v1.0//EN</text>
            </prodid>
            <version><text>2.0</text></version>
        </properties>
        <components>
            <vevent>
                <properties>
                    <dtstamp>
                        <date-time utc='yes'>
                            <year>2010</year>
                            <month>7</month>
                            <day>1</day>
                            <hour>11</hour>
                            <minute>0</minute>
                            <second>0</second>
                        </date-time>
                    </dtstamp>
                    <dtstart>
                        <date>
                            <year>2010</year>
                            <month>11</month>
                            <day>2</day>
                        </date>
                    </dtstart>
                    <dtend>
                        <date>
                            <year>2010</year>
                            <month>11</month>
                            <day>2</day>
                        </date>
                    </dtend>
                    <summary>
                        <text>AGAP RFC Party</text>
                    </summary>
                    <uid>
                        <text>uidx1234@example.com</text>
                    </uid>
                </properties>
            </vevent>
        </components>
    </vcalendar>
</icalendar>

 Figure 6 



 TOC 

2.8.5.  Response for File Folders

A response holding the content of a file has the following structure:


<FILE>
    <CONTENT ENCODED="...">content</CONTENT>
</FILE>

 Figure 7 

The valid encodings type are: utf-8, quoted-printable, and base64. It CAN be case-insensitive written.

Example:


<file>
    <content encoded="base64">c3VyZS4=</content>
</file>

 Figure 8 



 TOC 

2.8.6.  Response for Filter Folders

An entryTag can be: and, or, not, uid, tag, is, regex. The value associated to entryTag is specified as a XML text node. The is and regex tags have two attributes: path and op. Their values are set as for a filter command (see chapter "Syntax of a Filter" for more information). The first entryTag MUST to be an AND or OR tag.

A response holding the content of a file has the following structure:


<FILTER>
    <entryTag>...</entryTag>
</FILTER>

 Figure 9 

Example:


<filter>
    <or>
        <is path="header/subject" op="=">Viagra</is>
        <and>
            <uid>UIDx1234:UIDx4321</>
            <tag>SPAM</>
        </and>
    </or>
</filter>

 Figure 10 



 TOC 

2.8.7.  Response for Message Folders

A response holding the content of a message has the following structure:


<MESSAGE>
    <HEADER>
        <header-entry-once>value</header-entry-once>...
        <header-entry-multi>
            <ITEM INDEX="i">value n</ITEM>...
        </header-entry-multi>...
    </HEADER>
    <BODY TYPE="..." ENCODED="utf-8">
        <TEXT*>main text</TEXT>
        <HTML*>main html</HTML>
        <ATTACHMENT* ID="1.." PARENT="0..">
            <HEADER>
                ...
            </HEADER>
            <BODY TYPE="..." ENCODED="...">
                ...
            </BODY>
        </ATTACHMENT>...
    </BODY>
</MESSAGE>

 Figure 11 

A parent="0" for an attachment tag means that is it part of the main message or the parent is unknown. The value for parent is a number used as id for another attachment entry. An attachment having a wrong parent id will be considered to have no parent (parent="0"). It is incorrect for a tag to use the same number both for its id and its parent.

The first index and the first attachment id has the value 1.

The index of on item tag shows the order of the entries in the original message.

The default content type for an attachment is "text/plain", the default content encoding is utf-8, and the default parent id is 0.

The entries in the header of the main message and attachments are the same with the one from the e-mail message.

Example:


<message>
    <header>
        <from>example@no-spam.com</from>
        <to>example@example.com</to>
        <received>
            <item index="2">
from mail.yahoo.com by example.com; Tue, 16 Mar 2010 12:14:24 +0100
            </item>
            <item index="1">
from no-spam.com by mail.yahoo.com; Mon, 15 Mar 2010 11:13:23 +0100
            </item>
        </received>
        <content-type>multipart/mixed; boundary="XYZ"</content-type>
        <subject>A basic example</subject>
    </header>
    <body type="multipart/mixed" encoded="utf-8">
    <text>Please see the attachments.</text>
    <html>
&lt;b&gt;Please&lt;/b&gt; see the &lt;u&gt;attachments&lt;/u&gt;.
    </html>
    <attachment ID="1"/>
      <header>
        <content-type>multipart/related</content-type>
      </header>
    </attachment>
    <attachment ID="2" parent="1">
      <header>
        <content-type>text/plain</content-type>
      </header>
      <body type="text/plain" encoded="utf-8">See the picture.</body>
    </attachment>
    <attachment ID="3" parent="1">
      <header>
        <content-type>image/jpeg</content-type>
        <content-transfer-encoding>base64</content-transfer-encoding>
      </header>
      <body type="image/jpeg" encoded="base64">c3VyZS4=</body>
    </attachment>
    </body>
</message>

 Figure 12 

The previous example corresponds to a message with the following structure:



 TOC 

2.8.8.  Response for Note Folders

A response holding the content of the note has the following structure:


<NOTE>
    <TEXT>content</TEXT>
</NOTE>

 Figure 13 

Example:


<note>
    <text>To review the code.</text>
</note>

 Figure 14 



 TOC 

3.  States



 TOC 

3.1.  Not-authenticated State

This is the default state when a new connection is made to the server. The client becomes a welcome message.

From this state the client can use the command 'AUTH mechanism' to move in the 'Pre-authentication State'. This is the only other state in which the server can go.

The client can use the command 'STLS' for commuting in the encrypted mode of the channel. After STLS the server remains in the 'Not-authenticated State'. There is no command for switching back to clear-text communication.

The client can use the command 'SGZP' for commuting in the compressed mode of the channel. After SGZP the server remains in the 'Not-authenticated State'. There is no command for switching back to not-compressed communication.

A client can use at the same time the both modes (encrypted and compressed).

The client can use the command 'QUIT' for terminating the connection.

For finding what extensions are installed in server, the client can use the 'CAPA' command.



 TOC 

3.2.  Pre-authentication State

This is the state where a client authenticate itself and move to the 'Authenticated State' or returns to the 'Not-authenticated State'.

This standard defines only one method for AUTH: PLAIN. Following is a description of the commands flow used by this authentication mechanism.

The client must send a 'USER account' followed by a 'PASS password' (if the server confirms the acceptance of the account name). If the pair account and password is accepted then the server move to the state 'Authenticated State' and the folder INBOX is selected by server. If this folder does not exist then the server moves in the 'Not-Selected State' and the client must to select an existing folder for operating with this account. If this pair is rejected then the server returns to the 'Not-authenticated State'. That means that the client must to send a new 'AUTH mechanism' for trying a new authentication.

The client can use the command 'QUIT' for terminating the connection.

A client can enter into this state only after a successful 'AUTH' command in 'Not-authenticated State'.



 TOC 

3.3.  Authenticated (and Selected) State

This is the state from which a client operates with the content of an account.

From this state the client can use the command 'EXIT' to move in the 'Not-authenticated State'. After an unsuccessful SLCT, the server goes in 'Not-selected State'.

The client can use the command 'QUIT' for terminating the connection.

Check the following chapter for finding which commands can be performed from this state.

A client can enter into this state only after a successful authentication in the 'Pre-authenticated State' or after a successful 'SLCT' command in the 'Authenticated State' or 'Not-selected State'.



 TOC 

3.4.  (Authenticated but) Not-selected State

This is the state from which a client must to select a folder for performing further operations.

From this state the client must use the command 'SLCT' to select a folder and to move in the 'Authenticated State'. This is the only other state in which the server can go.

The client CAN use the command 'LIST' for finding valid folder names that eventually CAN be selected with 'SLCT' command.

The client CAN use the command 'QUIT' for terminating the connection.

A client CAN enter into this state only after an unsuccessful 'SLCT' command or if the INBOX folder does not exists and it cannot be selected automatically after a successful authentication.



 TOC 

4.  Commands



 TOC 

4.1.  Semantic and Syntax

Each command has its name from 4 letters and it is matched case-insensitive.

Each command is separated by its arguments by a 0x20 character. Also, each argument is separated from its adjacent arguments by a 0x20 character.

The minimal response has only the return code without any text.

A list of elements is enclosed between parentheses (round brackets).



 TOC 

4.2.  Syntax of a Tag List

A tag list is used by the following commands: FTAG, GTAG and STAG.

A tag list defines what action to be done with its tags.

Syntax: ACTION TAG TAG ...

ACTION:

Example:


C: STAG UIDx1234 = SEEN SPAM
C: STAG UIDx1234 + SEEN SPAM
C: STAG UIDx1234 - SEEN SPAM

 Figure 15 



 TOC 

4.3.  Syntax of a Filter



 TOC 

4.3.1.  Syntax of a Filter for a Command

A filter of this type is used by the following commands: FCPY, FDEL, FTAG, FIND and FMOV.

A filter defines rules for matching the different messages. It is defined as lines with rules and it is ended by an empty line.

The keywords of the filter are case insensitive matched (ex.: UID and Uid are the same).

Accepted rules:

The filed_path is a XPATH in the response as it is returned by RETR.

Searching for a TAG without associating and a value to it will match all entries that have this tag even if it have values set for it.

Example 1: These filters find all messages with the UID between UIDx0001:UIDx1000 and that were seen and marked as being spam or having a virus (the AND is redundant in the second case). Both filter definitions are equivalent.


C: UID UIDx0001:UIDx1000 OR ( TAG SPAM TAG HAS=VIRUS ) TAG SEEN
C: UID UIDx0001:UIDx1000 AND( OR ( TAG SPAM TAG HAS=VIRUS ) TAG SEEN)

 Figure 16 

Example 2:


C: IS header/subject = "From University"
C: REGEX header/from != "[^0-9]+@example\.com$"
C: IS vcard/fn/text = "Anonymous"
C: REGEX vcard/org/text = "^[A-Za-z]+[0-9]$"

 Figure 17 



 TOC 

4.3.2.  Syntax of a Filter for a FILT Folder

A filter of this type is used by the following command: STOR.

A filter defines rules for matching the different messages from different folders. It is defined as a XML with target folders and rules.

The keywords of the filter are case sensitive matched (ex.: UID and Uid are not the same). They are always lowercase.

Accepted rules:

The filed_path is a XPATH in the response as is it returned by RETR.

Searching for a TAG without associating and a value to it will match all entries that have this tag even if it have values set for it (the empty string is also considered matched).

The following two examples corresponds to the two examples from the previous chapter:


<filter>
    <folders>
        <folder>/INBOX</folder>
    </folders>
    <rules>
        <and>
            <uid>UIDx0001:UIDx0010</uid>
            <or>
                <tag>SPAM</tag>
                <tag>HAS=VIRUS</tag>
            </or>
            <tag>SEEN</tag>
        </and>
    </rules>
</filter>

 Figure 18 

Example 2:


<filter>
  <folders>
    <folder>/INBOX</folder>
  </folders>
  <rules>
    <or>
      <is path="header/subject" op="=">From University</is>
      <regex path="header/from" op="!=">[^0-9]+@example\.com$</regex>
      <is path="vcard/fn/text" op="=">Anonymous</is>
      <regex path="vcard/org/text" op="=">^[A-Za-z]+[0-9]$</regex>
    </or>
  </rules>
</filter>

 Figure 19 



 TOC 

4.4.  The Welcome Message - not-authenticated state

Results: 200 401 410 531

Result 200 - the client is accepted for sending commands;

Result 401 - there was an internal error;

Result 410 - too many connections;

Result 531 - the client is rejected permanently.

Description: When a client connects to the server it receives a welcome message. This message begins with a response code that shows if the client is accepted for sending commands.

Examples:


S: 200 Welcome localhost [127.0.0.1]

 Figure 20 



S: 401 Internal error, please contact our administrator

 Figure 21 



S: 410 Sorry, too many connections, please retry later

 Figure 22 



S: 531 Your hostname/IP (localhost:127.0.0.1) is blacklisted

 Figure 23 



 TOC 

4.5.  Command QUIT - all states

Name: quit

Arguments: none

Result: 200

Description: The QUIT command close the connection between the client and server.

Example:


C: QUIT
S: 200 OK Bye

 Figure 24 



 TOC 

4.6.  Command AUTH mechanism - not-authenticated state

Name: authenticate

Argument: mechanism

Results: 200 510 511

Result 200 - the mechanism is known and accepted.

Result 510 - unknown command.

Result 511 - the mechanism is unknown/unsupported.

Description: Choose an authentication method (exists at least the mechanism PLAIN).

Examples:


C: AUTH PLAIN
S: 200 OK Send USER

 Figure 25 



C: AUTH
S: 510 UNKNOWN command

 Figure 26 



C: AUTH unknown
S: 511 UNKNWON method

 Figure 27 



 TOC 

4.7.  Command CAPA - not-authenticated state

Name: capabilities

Arguments: none

Result: 200

Description: Ask for the extensions known by the server.

Note: If the server accepts compression then it must advertise the GZIP capability. If the server can encrypt the communication channel then it must advertise the TLS capability. (The following example shows both capabilities advertised.)

Example:


C: CAPA
S: .GZIP
S: .TLS
S: .Extension1
S: .Extension.2 argument1
S: .Extension-3 argument1 argument2
S: 200 OK CAPA completed

 Figure 28 



 TOC 

4.8.  Command SGZP - not-authenticated state

Name: start using GZip

Arguments: none

Results: 200 510

Result 200 - the communication is now compressed.

Result 510 - unknown/unsupported command.

Description: Change the communication in compressed mode using GZIP (Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and G. Randers-Pehrson, “GZIP file format specification version 4.3,” May 1996.) [RFC1952] as compression method. If this command is executed from the compression mode then it simply returns a 200 response code. The response to this command is using still the not-compressed mode of the channel. The compression becomes effective only after a 200 response line was send by the server.

Note: With GZIP the data is compressed using the LZ77 algorithm and Huffman coding. Starting using this mode is like starting to write clear texts into a GZIP format archive and reading texts from a GZIP format archive. The compression is used both by the client and the server and they start to use it with the next line they send after the 200 response line received from the server.

Examples:


C: SGZP
S: 200 OK Using GZIP

 Figure 29 



C: SGZP
S: 510 UNKNOWN command

 Figure 30 



 TOC 

4.9.  Command STLS - not-authenticated state

Name: start using TLS

Arguments: none

Results: 200 510

Result 200 - the communication is now encrypted.

Result 510 - unknown/unsupported command.

Description: Change the communication in mode TLS. If this command is executed from the encrypted mode then it simply returns a 200 response code. The response to this command is using still the not-encrypted mode of the channel. The encryption becomes effective only after a 200 response line was send by the server.

Examples:


C: STLS
S: 200 OK Using TLS

 Figure 31 



C: STLS
S: 510 UNKNOWN command

 Figure 32 



 TOC 

4.10.  Command PASS password - pre-authenticated state (PLAIN)

Name: password

Argument: password

Result: 200 510 511 512

Result 200 - the pair user/password was successfully authenticated.

Result 510 - unknown/unsupported command.

Result 511 - invalid password.

Result 512 - first send USER and then PASS.

Description: Send the password associated to the previous USER.

Examples:


C: USER account
S: 200 OK Send PASS
C: PASS password
S: 200 OK Authenticated

 Figure 33 



C: USER account
S: 200 OK Send PASS
C: PASS
S: 510 UNKNOWN command

 Figure 34 



C: USER account
S: 200 OK Send PASS
C: PASS password
S: 511 WRONG user/password pair

 Figure 35 



C: AUTH PLAIN
S: 200 OK AUTH completed
C: PASS password
S: 512 EXPECTED USER

 Figure 36 



 TOC 

4.11.  Command USER account - pre-authenticated state (PLAIN)

Name: user

Argument: account

Result: 200

Result: 200 510 511

Result 200 - the user is accepted and expecting the password.

Result 510 - unknown/unsupported command.

Result 511 - invalid account.

Description: Send an account name for authentication and authorization.

Examples:


C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 200 OK Send PASS

 Figure 37 



C: AUTH PLAIN
S: 200 OK Send USER
C: USER
S: 510 UNKNOWN command

 Figure 38 



C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 511 INVALID username

 Figure 39 



 TOC 

4.12.  Command COPY - authenticated state

Name: copy entry

Arguments: UID_source path_destination_folder

Result: 200 510 511

Result 200 - the copy was successful.

Result 510 - unknown/unsupported command.

Result 511 - unknown uid or invalid destination folder.

Description: Copy a message/contact/event from the currently selected folder into another folder (by UID).

Note: For copying a folder the client must use CPYF.

Examples:


C: COPY UIDx1234 ARCHIVE_FOLDER/TODAY
S: 200 OK COPY completed

 Figure 40 



C: COPY
S: 510 UNKNOWN command

 Figure 41 



C: COPY UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: COPY MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination

 Figure 42 



 TOC 

4.13.  Command CPYF - authenticated state

Name: copy folder

Arguments: path_source_folder path_destination_folder

Result: 200 510 511

Result 200 - the copy was successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid source or destination folder.

Description: Copy the content of a folder into another folder.

Note: In the destination folder are created copies of all entries found in the source. If the user needs to copy the content of the source folder in another folder then he must to create first a new folder with the MAKE command and then use it as argument for CPYF.

Examples (in TODAY are copied only the messages from INBOX):


C: CPYF INBOX ARCHIVE_FOLDER/TODAY
S: 200 OK CPYF completed

 Figure 43 



C: CPYF
S: 510 UNKNOWN command

 Figure 44 



C: CPYF MISSING ARCHIVE_FOLDER/TODAY
S: 511 INVALID Source
C: CPYF INBOX MISSING
S: 511 INVALID Destination

 Figure 45 



 TOC 

4.14.  Command DATT - authenticated state (MESG folder type)

Name: delete attachment

Arguments: UID AttNum

Result: 200 510 511 521

Result 200 - the attachment was successfully deleted.

Result 510 - unknown/unsupported command.

Result 511 - unknown uid or uid is not for a message.

Result 521 - wrong attachment number.

Description: Delete from a message an attachment. The first attachment has number 1. All its children are also deleted.

Note: It cannot be undone.

Examples:


C: DATT UIDx1234 1
S: 200 OK Attachment deleted

 Figure 46 



C: DATT
S: 510 UNKNOWN command

 Figure 47 



C: DATT UIDx1234 1
S: 511 INVALID UID
C: DATT UIDx1234 -1
S: 511 INVALID Attachment number

 Figure 48 



C: DATT UIDx1234 10
S: 521 There are not so many attachments

 Figure 49 



 TOC 

4.15.  Command DELE - authenticated state

Name: delete entry

Argument: UID

Result: 200 510 511

Result 200 - the entry was successfully deleted.

Result 510 - unknown/unsupported command.

Result 511 - unknown uid.

Description: Delete a message/contact/event by uid.

Note: It cannot be undone.

Examples:


C: DELE UIDx1234
S: 200 OK Message deleted

 Figure 50 



C: DELE
S: 510 UNKNOWN command

 Figure 51 



C: DELE 1234
S: 511 INVALID UID

 Figure 52 



 TOC 

4.16.  Command DELF - authenticated state

Name: delete folder

Argument: path_folder

Result: 200 510 511

Result 200 - the folder was successfully deleted.

Result 510 - unknown/unsupported command.

Result 511 - unknown path or the path points to a reserved folder.

Description: Delete a folder and all its content and subfolders. A reserved folder cannot be deleted.

Note: It cannot be undone.

Examples:


C: DELF ARCHIVE/TODAY
S: 200 OK Folder deleted

 Figure 53 



C: DELF
S: 510 UNKNOWN command

 Figure 54 



C: DELF MISSING
S: 511 INVALID Folder
C: DELF INBOX
S: 511 INBOX cannot be deleted

 Figure 55 



 TOC 

4.17.  Command EXIT - authenticated state

Name: exit

Arguments: none

Result: 200

Description: Return the server to the Not-authenticated State.

Example:


C: EXIT
S: 200 OK EXIT completed

 Figure 56 



 TOC 

4.18.  Command FCPY - authenticated state

Name: find and copy entries

Arguments: path_destination_folder filter*

Result: 200 510 511

Result 200 - the find and copy was successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid destination folder or wrong filter.

Description: Search for messages/contacts/events only from the currently selected folder (no subfolders) that correspond to a filter and copy them to a new folder. The tags are also copied.

Note: The filter is delivered after the acceptance of the command (response code 100).

Examples:


C: FCPY ARCHIVE/SPAM
S: 100 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 200 OK FCPY completed (10 matches)

 Figure 57 



C: FCPY
S: 510 UNKNOWN command

 Figure 58 



C: FCPY MISSING
S: 511 INVALID folder
C: FCPY SEND
S: 100 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition

 Figure 59 



 TOC 

4.19.  Command FDEL - authenticated state

Name: find and delete entries

Argument: filter*

Result: 200 511

Result 200 - the find and delete was successful.

Result 511 - wrong filter (inclusive empty filter).

Description: Search for messages/contacts/events only from the currently selected folder (no subfolders) that correspond to a filter and delete them (no copy in TRASH).

Note: The filter is delivered after the acceptance of the command (response code 100).

Examples:


C: FDEL
S: 100 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 200 OK FDEL completed (10 matches)

 Figure 60 



C: FDEL
S: 100 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition

 Figure 61 



 TOC 

4.20.  Command FIND - authenticated state

Name: find entry

Argument: filter*

Result: 200 511

Result 200 - the find was successful.

Result 511 - wrong filter.

Description: Search for messages/contacts/events only from the currently selected folder (no subfolders) that correspond to a filter and return their UIDs. If the search is done for a filter folder then the server does not expect any filter and apply the current filter (if any). If there is no filter in the filter folder then it is returned only the return code. The answer consists of the UIDs and, for a filter folder, they are followed by a 0x20 character and the absolute path for which are the corresponding UID.

Note: For not FILT folders, the filter is delivered after the acceptance of the command. An empty filter matches all messages/contacts/events from that folder.

Examples:


C: SLCT /MESG-Folder
C: FIND
S: 100 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: .UIDx1234
S: .UIDx1235
S: .UIDx2340
S: 200 OK FIND completed (3 matches)
C: SLCT /FILT-Folder
C: FIND
S: .UIDx1234 /INBOX
S: .UIDx1234 /Trash
S: .UIDx1235 /Trash
S: 200 OK FIND completed (3 matches)

 Figure 62 



C: FIND
S: 100 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition

 Figure 63 



 TOC 

4.21.  Command FMOV - authenticated state

Name: find and move

Arguments: path_destination_folder filter*

Result: 200 510 511

Result 200 - the find and move was successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid destination folder or wrong filter.

Description: Search for messages/contacts/events only from the currently selected folder (no subfolders) that correspond to a filter and move them to a new folder. The tags are also moved.

Note: The filter is delivered after the acceptance of the command (response code 100).

Examples:


C: FMOV ARCHIVE/SPAM
S: 100 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 200 OK FMOV completed (10 matches)

 Figure 64 



C: FMOV
S: 510 UNKNOWN command

 Figure 65 



C: FMOV MISSING
S: 511 INVALID folder
C: FMOV SEND
S: 100 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition

 Figure 66 



 TOC 

4.22.  Command FTAG - authenticated state

Name: find and tag entries

Arguments: tag_list filter*

Result: 200 510 511

Result 200 - the find and set of tag(s) were successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid tag list or wrong filter.

Description: Search for messages/contacts/events only from the currently selected folder (no subfolders) that correspond to a filter and change their tags.

Note: The filter is delivered after the acceptance of the command (response code 100).

Examples:


C: FTAG + SEEN
S: 100 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG NEW
C:
S: 200 OK FTAG completed (10 matches)

 Figure 67 



C: FTAG
S: 510 UNKNOWN command

 Figure 68 



C: FTAG SEEN
S: 511 INVALID tag list
C: FTAG + SEEN
S: 100 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition

 Figure 69 



 TOC 

4.23.  Command GTAG - authenticated state

Name: get tag

Arguments: UID_range

Result: 200 510 511

Result 200 - the tag(s) of UIDs was/were successful displayed.

Result 510 - unknown/unsupported command.

Result 511 - invalid UID or UID range.

Description: Return the tags associated to one or more messages/contacts/events (by UID).

Examples:


C: GTAG UIDx1000
S: .UIDx1000 SEEN SPAM
S: 200 OK GTAG completed
C: GTAG UIDx1000:UIDx1234
S: .UIDx1000 SEEN SPAM
S: .UIDx1100
S: .UIDx1200 NEW
S: 200 OK GTAG completed

 Figure 70 



C: GTAG
S: 510 UNKNOWN command

 Figure 71 



C: GTAG -1
S: 511 INVALID UID
C: GTAG UIDx1234:UIDx1000
S: 511 INVALID UID range

 Figure 72 



 TOC 

4.24.  Command LIST - authenticated and not-selected state

Name: list

Arguments: path/filter?

Results: 200 511 513

Result 200 - the list was successful delivered (even if it is empty).

Result 511 - filter is invalid.

Result 521 - the specified path (that has no wildcard) does not exist or the filter returns no results.

Description: List all folders that correspond to the filter (if it is provided), otherwise all direct children of this folder together with their types. All returned folder names are prefixed with the type of the corresponding folder (as it is used by the MAKE command) followed by a white space and the path to the folder (absolute or relative).

Filter: It is a relative (does not begins with /) or an absolute (begins with /) path. The slash sign (/) is used to delimit folders in the hierarchy. There can be only a star (*) and must to be located in the name of the last folder. The '\' does not have any meaning and it is interpreted as a normal character. The server can return 511 if it founds '.' or '..' as folder names in the filter definition, and it must not escape (or give a special meaning) to the character found after a backslash. In addition, the server cannot return relative paths using at beginning of a path the string './'.

Examples:


C: LIST
S: .MESG YESTERDAY
S: .MESG YEAR-2000
S: 200 OK LIST completed (2 matches)
C: LIST /*
S: .MESG /INBOX
S: .MESG /TRASH
S: .CALE /CALENDAR
S: 200 OK LIST completed (3 matches)
C: LIST YEAR-2010/J*
S: .MESG /WORK/YEAR-2010/JUN
S: .MESG /WORK/YEAR-2010/JUL
S: 200 OK LIST completed (2 matches)

 Figure 73 



C: LIST */*
S: 511 ERROR path filter can contain only one * in last folder name

 Figure 74 



C: LIST /ARCHIVE/2000
S: 521 ERROR The specified folder does not exist
C: LIST /archive*
S: 521 ERROR No matching folders found (0 matches)

 Figure 75 



 TOC 

4.25.  Command MAKE - authenticated state

Name: make folder

Argument: type path

Result: 200 510 511

Result 200 - the folder was successfully created.

Result 510 - unknown/unsupported command.

Result 511 - invalid path, unknown/unsupported type or the parent of the new folder does not accept to have subfolders.

Description: Create a folder of a certain type.

Types: They are case insensitive

Note: If it requires parents that does not exist then the server will not create them for the client but it will return a 511 response code.

Examples:


C: MAKE MESG /ARCHIVE/2010
S: 200 OK Folder created

 Figure 76 



C: MAKE
S: 510 UNKNOWN command

 Figure 77 



C: MAKE 1234
S: 511 ERROR Missing folder name
C: MAKE new 1234
S: 511 ERROR Unknown folder type
C: MAKE MESG /INBOX/1234
S: 511 ERROR The parent folder does not accept subfolders.

 Figure 78 



 TOC 

4.26.  Command MOVE - authenticated state

Name: move entry

Arguments: UID_source path_destination_folder

Result: 200 510 511

Result 200 - the move was successful.

Result 510 - unknown/unsupported command.

Result 511 - unknown uid or invalid destination folder.

Description: Move a message/contact/event into another folder (by UID).

Note: For moving a folder the client must use MOVF.

Examples:


C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 200 OK MOVE completed

 Figure 79 



C: MOVE
S: 510 UNKNOWN command

 Figure 80 



C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: MOVE MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination

 Figure 81 



 TOC 

4.27.  Command MOVF - authenticated state

Name: move folder

Arguments: path_source_folder path_destination_folder

Result: 200 510 511

Result 200 - the move was successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid source or destination folder.

Description: Move the content of a folder into another folder.

Note: In the destination folder are moved all entries found in the source without the folders. If the user needs to move the content of the source folder in another folder then he must to create first this new folder with the MAKE command and then use it as argument for MOVF.

Examples:


C: MOVF INBOX ARCHIVE_FOLDER/TODAY
S: 200 OK MOVF completed

 Figure 82 



C: MOVF
S: 510 UNKNOWN command

 Figure 83 



C: MOVF MISSING ARCHIVE_FOLDER/TODAY
S: 511 INVALID Source
C: MOVF INBOX MISSING
S: 511 INVALID Destination

 Figure 84 



 TOC 

4.28.  Command NAME - authenticated state

Name: rename folder

Arguments: path new_name

Results: 200 510 511

Result 200 - the rename was successful.

Result 510 - unknown/unsupported command.

Result 511 - invalid path, new_name or trying to rename a reserved folder name.

Description: Rename a folder.

Note: The new_name does not hold any path hierarchy.

Examples:


C: NAME ARCHIVE/2001 OLD-2001
S: 200 OK NAME completed

 Figure 85 



C: NAME
S: 510 UNKNOWN command

 Figure 86 



C: NAME /INBOX
S: 511 ERROR Missing the new name
C: NAME MissingFolder NewName
S: 511 ERROR Folder to be renamed was not found
C: NAME /INBOX InBox
S: 511 ERROR The folder cannot be renamed
C: NAME /A/Folder /A/new-folder
S: 511 ERROR The second argument must not be a path

 Figure 87 



 TOC 

4.29.  Command NOOP - authenticated state

Name: noop

Arguments: none

Result: 200

Description: It does nothing (eventually announce what changes was done in current folder).

Example:


C: NOOP
S: 200 OK NOOP completed

 Figure 88 



 TOC 

4.30.  Command RETR - authenticated state

Name: retrieve

Arguments for a FILT folder: none

Arguments for other types: UID part?

Results: 200 510 511

Result 200 - the message/contact/event was found or filter content was delivered.

Result 510 - unknown/unsupported command.

Result 511 - invalid UID or part name.

Description: Fetch from server the message/contact/event with the given UID. For a filter folder, it must be called without arguments and it returns the content of the filter. Each line of answer is prefixed with a dot that it is not part of the returned object.

Part: It is a XPATH in the response as it is returned by RETR.

Examples:


C: RETR UIDx1234
S: .<message><header>...</header><body>...</body></message>
S: 200 OK RETR completed
C: RETR UIDx1234 header/subject
S: .<message><header>
S: .<subject>Message's subject</subject>
S: .</header></message>
S: 200 OK RETR completed
C: RETR
S: .<filter>
S: .<folders><folder>/Spam</folder></folders>
S: .<rules></rules>
S: .</filter>
S: 200 OK RETR completed

 Figure 89 



C: RETR
S: 510 UNKNOWN command (only FILT folders do not needs arguments)

 Figure 90 



C: RETR WrongUID
S: 511 INVALID UID
C: RETR UIDx1234 ABC
S: 511 UNKNOWN part name
C: RETR UIDx1234
S: 511 RETR with UID is not allowed for a FILT folder

 Figure 91 



 TOC 

4.31.  Command SLCT - authenticated and not-selected state

Name: select a folder

Argument: path

Result: 200 510 511

Result 200 - the folder was successfully selected.

Result 510 - unknown/unsupported command.

Result 511 - unknown path.

Description: Select a folder. If the selection was not successful then no folder remains selected and the server switch in the 'Not-selected State'.

Examples:


C: SLCT /INBOX
S: 200 OK Folder selected
C: SLCT ARCHIVE/2000
S: 200 OK Folder selected

 Figure 92 



C: SLCT
S: 510 UNKNOWN command

 Figure 93 



C: SLCT 1234
S: 511 INVALID folder

 Figure 94 



 TOC 

4.32.  Command SPAM - authenticated state (MESG folder type)

Name: spam

Argument: UID reason?

Result: 200 510 511

Result 200 - the entry was successfully marked.

Result 510 - unknown/unsupported command.

Result 511 - invalid or not found UID, or invalid reason.

Description: Mark a message as SPAM/MALWARE. The server can ignore this command or it can check the reason (if present) and improve its SPAM detection mechanism.

Reason: It can be the name of a field (ex.: header/subject) eventually followed by equal and the text from that field that identify it as a SPAM. If there is more than one criterion for marking a message as SPAM then the client must supply for each reason a SPAM command. If there is no reason then the whole indicated field's content is used.

Note: It cannot be undone and no tag is set for this message.

Examples:


C: SPAM UIDx1234
S: 200 OK Message added to the spam database
C: SPAM UIDx1234 header/subject
S: 200 OK Message added to the spam database
C: SPAM UIDx1234 body=V1AGRA
S: 200 OK Message added to the spam database

 Figure 95 



C: SPAM
S: 510 UNKNOWN command

 Figure 96 



C: SPAM 1234
S: 511 INVALID UID

 Figure 97 



 TOC 

4.33.  Command STAG - authenticated state

Name: set tags of entries

Arguments: UID_range tag_list

Result: 200 510 511

Result 200 - the tag(s) for UIDs were successful set.

Result 510 - unknown/unsupported command.

Result 511 - invalid UID or UID range.

Description: Set or delete tags associated to one or more messages/contacts/events (by UID).

Examples:


C: STAG UIDx1000 + SEEN
S: 200 OK STAG completed
C: STAG UIDx1000:UIDx1234 + SEEN
S: 200 OK STAG completed

 Figure 98 



C: STAG
S: 510 UNKNOWN command

 Figure 99 



C: STAG -1
S: 511 INVALID UID
C: STAG -1 + SEEN
S: 511 INVALID UID
C: STAG UIDx1234 SEEN
S: 511 INVALID tag list

 Figure 100 



 TOC 

4.34.  Command STAT - authenticated state

Name: status

Arguments: none

Result: 200 512

Result 200 - the status of the folder was successfully delivered.

Result 512 - no folder is selected.

Description: Return the absolute path of the currently selected folder (PATH), its type (TYPE), an FUID that is incremented each time a change is produced to the folder, the tags (TAGS) and eventually additional information associated with this type of folder.

Additional information:

Note: An FUID has the same format as a normal UID and each new FUID is bigger as the precedent one (as is described for UIDs).

Examples:


C: STAT
S: .PATH /INBOX
S: .TYPE MSG
S: .FUID 1
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 2
S: 200 OK Folder status displayed

 Figure 101 



C: STAT
S: 512 ERROR First select a folder

 Figure 102 



 TOC 

4.35.  Command STOR - authenticated state

Name: store

Arguments: none

Result: 200 410 511

Result 200 - the entry was successfully deleted.

Result 410 - if the item cannot be stored.

Result 511 - if the data is not a valid XML or its schema does not correspond to the type of the destination folder.

Description: Store a new message/contact/event/filter into a folder. If it is written a new filter into a FILT folder, then the previous filter is deleted. If the new filter has an invalid XML structure or cannot be saved then the folder remains with the old filter (if any).

Note: Do not send a message content using CDATA as it can hold empty lines and an empty line means for the server the end of the message to be stored.

Examples:


C: STOR
S: 110 Send the message ended with an empty line
C: <message><header>...</header><body>...</body></message>
C:
S: 200 OK Message stored (UID is UIDx1234)

 Figure 103 



C: STOR
S: 110 Send the message ended with an empty line
C: <message><header>...</header><body>...</body></message>
C:
S: 410 Cannot store it, not enough space

 Figure 104 



C: STOR
S: 110 Send the message ended with an empty line
C: msg
C:
S: 511 Cannot store it, the message has an incorrect format

 Figure 105 



 TOC 

5.  Responses



 TOC 

5.1.  Semantic and Syntax

The Response-Code element is a 3-digit integer result code of the attempt to understand and satisfy the request. These codes are fully defined in the following section.

After the Response-Code, can follow a 0x20 character and then a Reason-Phrase intended to give a short textual description of the returned code. The Response-Code is intended for automatic use. The Reason-Phrase is intended for humane persons that debug the connection.

The first digit of the Response-Code defines the class of response. The last two digits do not have any categorization role. There are 4 values for the first digit:

There are commands that return a multi-line response. These are: CAPA, FIND, GTAG, LIST, RETR, and STAT. In this cases, the response code is at the beginning of the last line of the response. All other lines start with a dot (.).



 TOC 

5.2.  1xx Informational



 TOC 

5.2.1.  100 Reserved

Reserved.



 TOC 

5.2.2.  110 Continue

The client SHOULD continue sending the rest of this request. This response informs the client that the server accepted the initial part of the request and it is waiting for the next part of the request. The server sends a final response after the request has been completely received and processed.



 TOC 

5.3.  2xx Success



 TOC 

5.3.1.  200 OK

The request was successfully processed.



 TOC 

5.4.  4xx Temporary Server Error



 TOC 

5.4.1.  400 Reserved

Reserved.



 TOC 

5.4.2.  401 Internal Error

The request could not be processed because it was an internal error (ex.: something is wrong configured).



 TOC 

5.4.3.  410 Retry later

The operation must to be retried later. This return code is used when the data cannot be stored because there was an error (ex.: not enough space on disk).



 TOC 

5.5.  5xx Permanent Server Error



 TOC 

5.5.1.  500 Reserved

Reserved.



 TOC 

5.5.2.  510 Unknown Command

The request could not be processed because this command is unknown or its syntax is wrong.



 TOC 

5.5.3.  511 Invalid Parameter

The request could not be processed because the command has an invalid parameter.

This answer can be returned even if there was more than one 0x20 character between command and its arguments or between arguments.



 TOC 

5.5.4.  512 Out of order

This command has a valid syntax but must to be send after other command required by the logic of the server. (Ex.: PASS after USER in Pre-authenticated State.)



 TOC 

5.5.5.  521 Not found

This command has a valid syntax but the searched argument does not exist or cannot be accessed. (Ex.: LIST with a path does not have any wildcard and it does not exist.)



 TOC 

5.5.6.  531 Banned

The client is not allowed to interact with the server. (Ex.: the client's IP is blacklisted.)



 TOC 

6.  All Possible Response Codes for All Commands



 TOC 

6.1.  Not-authenticated State

The Welcome Message: 200 401 410 531

QUIT: 200

AUTH: 510 511

AUTH mechanism: 200 511

CAPA: 200

SGZP: 200 510

STLS: 200 510

other: 510



 TOC 

6.2.  Pre-authenticating State (PLAIN method)

QUIT: 200

PASS: 510 511 512

PASS password: 200 511 512

USER: 510 511

USER account: 200 511

other: 510



 TOC 

6.3.  Authenticated State

QUIT: 200

COPY: 510 511

COPY arguments: 200 511

CPYF: 510 511

CPYF arguments: 200 511

DATT: 510 511

DATT arguments: 200 511 521

DELE: 510 511

DELE arguments: 200 511

DELF: 510 511

DELF arguments: 200 511

EXIT: 200

FCPY: 510 511

FCPY arguments: 200 511

FDEL: 511

FDEL arguments: 200 511

FIND: 511

FIND arguments: 200 511

FMOV: 510 511

FMOV arguments: 200 511

FTAG: 510 511

FTAG arguments: 200 511

GTAG: 510 511

GTAG arguments: 200 511

LIST: 200

LIST arguments: 200 511 521

MAKE: 510 511

MAKE arguments: 200 511

MOVE: 510 511

MOVE arguments: 200 511

MOVF: 510 511

MOVF arguments: 200 511

NAME: 510 511

NAME arguments: 200 511

NOOP: 200

RETR: 510 511

RETR arguments: 199 200 511

SLCT: 510 511

SLCT arguments: 200 511

SPAM: 510 511

SPAM arguments: 200 511 512

STAG: 510 511

STAG arguments: 200 511

STAT: 200 512

STOR: 200 410 511

other: 510



 TOC 

6.4.  Not-selected State

LIST: 200

LIST arguments: 200 511 521

SLCT: 510 511

SLCT arguments: 200 511

other: 510



 TOC 

7.  Example of Conversations



 TOC 

7.1.  Successful connection and authentication



S: 200 Welcome
C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 200 OK Send PASS
C: PASS password
S: 200 OK Authenticated
C: STAT
S: .PATH /INBOX
S: .TYPE MSG
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 2
S: 200 OK Folder status displayed

 Figure 106 



 TOC 

7.2.  Successful connection but unsuccessful authentication



S: 200 Welcome
C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 200 OK Send PASS
C: PASS password
S: 511 WRONG user/password pair

 Figure 107 



 TOC 

7.3.  Connection refused



S: 531 Your IP is blacklisted

 Figure 108 



S: 410 Too many connections, please retry later

 Figure 109 



S: 401 Internal error, the server has an error in its configuration

 Figure 110 



 TOC 

7.4.  Find what folders are available with messages



C: LIST /*
S: .MESG /INBOX
S: .MESG /TRASH
S: .CALE /CALENDAR
S: 200 OK LIST completed (3 matches)

 Figure 111 



 TOC 

7.5.  Retrieve a message



C: SLCT /INBOX
S: 200 OK Folder selected
C: FIND
S: 100 OK SEND filter definition (end it with an empty line)
C: TAG NEW AND IS header/subject = 'Newsletter from Example.com'
C:
S: .UIDx1234
S: .UIDx1235
S: .UIDx2340
S: 200 OK FIND completed (3 matches)
C: RETR UIDx1234
S: .<message><header>
S: .<from>HCCP&lt;news@example.com&gt;</from>
S: .<to>newsletter@localhost.localdomain</to>
S: .<subject>HCCP Newsletter</subject>
S: .</header><body>
S: .<text>This is your weekly newsletter.</text>
S: .</body></message>
S: 200 OK RETR completed

 Figure 112 



 TOC 

7.6.  Retrieve a contact



C: SLCT /CONTACT
S: 200 OK Folder selected
C: FIND
S: 100 OK SEND filter definition (end it with an empty line)
C: REGEX vcard/fn/text = 'RADU.*?' OR vcard/fn/text = '.*? Iulian'
C:
S: .CONx0001
S: 200 OK FIND completed (1 match)
C: RETR CONx0001
S: .<vcards xmlns="urn:ietf:params:xml:ns:vcard-4.0">
S: .    <vcard>
S: .      <fn><text>Iulian Radu</text></fn>
S: .      <n>
S: .        <surname><text>Radu</text></surname>
S: .        <given><text>Iulian</text></given>
S: .        <suffix>
S: .          <text>Dipl.-Ing.</text>
S: .        </suffix>
S: .      </n>
S: .      <sex>1</sex>
S: .      <lang>
S: .        <parameters><pref>1</pref></parameters>
S: .        <language-tag>de</language-tag>
S: .      </lang>
S: .      <org>
S: .        <parameters><type>work</type></parameters>
S: .        <text>Example Com</text>
S: .      </org>
S: .      <email>
S: .        <parameters><type>work</type></parameters>
S: .        <text>iulian.radu@gmx.at</text>
S: .      </email>
S: .      <class>PUBLIC</class>
S: .   </vcard>
S: .</vcards>
S: 200 OK RETR completed

 Figure 113 



 TOC 

7.7.  Retrieve an event



C: SLCT /CALENDAR
S: 200 OK Folder selected
C: FIND
S: 100 OK SEND filter definition (end it with an empty line)
C: IS vcalendar/components/vevent/properties/location = 'Wien'
C: OR IS vcalendar/components/vevent/properties/uid/text =
C:       'uidx1234@example.com'
C:
S: .EVNx0001
S: 200 OK FIND completed (1 match)
C: RETR EVNx0001
S: .<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
S: .    <vcalendar>
S: .        <properties>
S: .            <prodid>
S: .                <text>-//amap/calender//NONSGML v1.0//EN</text>
S: .            </prodid>
S: .            <version><text>2.0</text></version>
S: .        </properties>
S: .        <components>
S: .            <vevent>
S: .                <properties>
S: .                    <location>Vienna</location>
S: .                    <dtstamp>
S: .                        <date-time utc='yes'>
S: .                            <year>2010</year>
S: .                            <month>1</month>
S: .                            <day>31</day>
S: .                            <hour>11</hour>
S: .                            <minute>0</minute>
S: .                            <second>0</second>
S: .                        </date-time>
S: .                    </dtstamp>
S: .                    <dtstart>
S: .                        <date>
S: .                            <year>2010</year>
S: .                            <month>11</month>
S: .                            <day>2</day>
S: .                            <hour>21</hour>
S: .                            <minute>30</minute>
S: .                            <second>0</second>
S: .                        </date>
S: .                    </dtstart>
S: .                    <dtend>
S: .                        <date>
S: .                            <year>2010</year>
S: .                            <month>11</month>
S: .                            <day>2</day>
S: .                        </date>
S: .                    </dtend>
S: .                    <summary>
S: .                        <text>An event in Wien.</text>
S: .                    </summary>
S: .                    <uid>
S: .                        <text>uidx1234@example.com</text>
S: .                    </uid>
S: .                </properties>
S: .            </vevent>
S: .        </components>
S: .    </vcalendar>
S: .</icalendar>
S: 200 OK RETR completed

 Figure 114 



 TOC 

7.8.  Store a message



C: SLCT /OUTBOX
S: 200 OK Folder selected
C: STOR
S: 110 Send the message ended with an empty line
C: <message><header>
C: <from>HCCP&lt;news@example.com&gt;</from>
C: <to>newsletter@localhost.localdomain</to>
C: <subject>HCCP Newsletter</subject>
C: </header><body>
C: <text>This is your weekly newsletter.</text>
C: </body></message>
C:
S: 200 OK Message stored (UID is UIDx1234)

 Figure 115 



 TOC 

7.9.  Store a contact



C: SLCT /CONTACT
S: 200 OK Folder selected
C: STOR
S: 110 Send the contact info ended with an empty line
C: <vcards xmlns="urn:ietf:params:xml:ns:vcard-4.0">
C:     <vcard>
C:       <fn><text>Iulian Radu</text></fn>
C:       <n>
C:         <surname><text>Radu</text></surname>
C:         <given><text>Iulian</text></given>
C:         <suffix>
C:           <text>Dipl.-Ing.</text>
C:         </suffix>
C:       </n>
C:       <sex>1</sex>
C:       <lang>
C:         <parameters><pref>1</pref></parameters>
C:         <language-tag>de</language-tag>
C:       </lang>
C:       <org>
C:         <parameters><type>work</type></parameters>
C:         <text>Example Com</text>
C:       </org>
C:       <email>
C:         <parameters><type>work</type></parameters>
C:         <text>iulian.radu@gmx.at</text>
C:       </email>
C:       <class>PUBLIC</class>
C:    </vcard>
C: </vcards>
C:
S: 200 OK Contact stored (UID is UIDx1234)

 Figure 116 



 TOC 

7.10.  Store an event



C: SLCT /CALENDAR
S: 200 OK Folder selected
C: STOR
S: 110 Send the contact info ended with an empty line
C: <icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
C:     <vcalendar>
C:         <properties>
C:             <prodid>
C:                 <text>-//amap/calender//NONSGML v1.0//EN</text>
C:             </prodid>
C:             <version><text>2.0</text></version>
C:         </properties>
C:         <components>
C:             <vevent>
C:                 <properties>
C:                     <location>Vienna</location>
C:                     <dtstamp>
C:                         <date-time utc='yes'>
C:                             <year>2010</year>
C:                             <month>1</month>
C:                             <day>31</day>
C:                             <hour>11</hour>
C:                             <minute>0</minute>
C:                             <second>0</second>
C:                         </date-time>
C:                     </dtstamp>
C:                     <dtstart>
C:                         <date>
C:                             <year>2010</year>
C:                             <month>11</month>
C:                             <day>2</day>
C:                             <hour>21</hour>
C:                             <minute>30</minute>
C:                             <second>0</second>
C:                         </date>
C:                     </dtstart>
C:                     <dtend>
C:                         <date>
C:                             <year>2010</year>
C:                             <month>11</month>
C:                             <day>2</day>
C:                         </date>
C:                     </dtend>
C:                     <summary>
C:                         <text>An event in Wien.</text>
C:                     </summary>
C:                     <uid>
C:                         <text>uidx1234@example.com</text>
C:                     </uid>
C:                 </properties>
C:             </vevent>
C:         </components>
C:     </vcalendar>
C: </icalendar>
C:
S: 200 OK Event stored (UID is UIDx1234)

 Figure 117 



 TOC 

7.11.  Mark messages as SPAM an move them in a new folder



C: STAG UIDx1000 + SPAM
S: 200 OK STAG completed
C: SPAM UIDx1000 header/subject
S: 200 OK Message added to the spam database
C: MAKE MESG /Archive-SPAM
S: 200 OK Folder created
C: FMOV /Archive-SPAM
S: 100 OK SEND filter definition (end it with an empty line)
C: TAG SPAM
C:
S: 200 OK FMOV completed (19 matches)

 Figure 118 



 TOC 

7.12.  Create a filter folder, find the matching entries of the filter and read its filter definition



C: MAKE FILT /New-messages
S: 200 OK Folder created
C: STOR
S: 110 Send the filter content ended with an empty line
C: <filter>
C: <folders><folder>/INBOX</folder></folders>
C: <rules>
C: <and><not><tag>SEEN</tag></not></and>
C: </rules>
C: </filter>
C:
S: 200 OK Filter stored
C: SLCT /New-messages
S: 200 OK Folder selected
C: FIND
S: .UIDx1234 /INBOX
S: .UIDx1234 /Trash
S: .UIDx1235 /Trash
S: 200 OK FIND completed (3 matches)
C: RETR
S: .<filter>
S: .<folders><folder>/INBOX</folder></folders>
S: .<rules><not><tag>SEEN</tag></not></rules>
S: .</filter>
S: 200 OK RETR completed

 Figure 119 



 TOC 

7.13.  Create a folder and rename it



C: MAKE MESG /My/NewFolder
S: 200 OK Folder created
C: NOOP
S: 200 NOOP OK
C: NAME /My/NewFolder AFolder
S: 200 OK NAME completed

 Figure 120 



 TOC 

7.14.  Find the status for a folder



C: LIST /*
S: .MESG /INBOX
S: .MESG /TRASH
S: .CALE /CALENDAR
S: 200 OK LIST completed (3 matches)
C: SLCT /INBOX
S: 200 OK SELECT completed
C: STAT
S: .PATH /INBOX
S: .TYPE MSG
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 5
S: 200 OK Folder status displayed

 Figure 121 



 TOC 

7.15.  Set and check the tags of a message



C: STAG UIDx1000 + SEEN
S: 200 OK STAG completed
C: GTAG UIDx1000
S: UIDx1000 SEEN SPAM
S: 200 OK GTAG completed

 Figure 122 



 TOC 

7.16.  Find messages that can be SPAM and delete them



C: FTAG + SPAM
S: 100 OK SEND filter definition (end it with an empty line)
C: REGEX header/subject = '[Vv][i1]agra'
C:
S: 200 OK FTAG completed (10 matches)
C: FDEL
S: 100 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 200 OK FDEL completed (10 matches)

 Figure 123 



 TOC 

8.  References



 TOC 

8.1. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2629] Rose, M., “Writing I-Ds and RFCs using XML,” RFC 2629, June 1999 (TXT, HTML, XML).
[RFC3552] Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” BCP 72, RFC 3552, July 2003 (TXT).


 TOC 

8.2. Informative References

[I-D.daboo-et-al-icalendar-in-xml] Daboo, C., Douglass, M., and S. Lees, “xCal: The XML format for iCalendar,” draft-daboo-et-al-icalendar-in-xml-02 (work in progress), March 2010 (TXT).
[I-D.ietf-vcarddav-vcardxml] Perreault, S., “vCard XML Representation,” draft-ietf-vcarddav-vcardxml-03 (work in progress), May 2010 (TXT).
[RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and G. Randers-Pehrson, “GZIP file format specification version 4.3,” RFC 1952, May 1996 (TXT, PS, PDF).
[RFC2821] Klensin, J., “Simple Mail Transfer Protocol,” RFC 2821, April 2001 (TXT).
[RFC3629] Yergeau, F., “UTF-8, a transformation format of ISO 10646,” STD 63, RFC 3629, November 2003 (TXT).
[RFC3921] Saint-Andre, P., Ed., “Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence,” RFC 3921, October 2004 (TXT, HTML, XML).
[RFC5545] Desruisseaux, B., “Internet Calendaring and Scheduling Core Object Specification (iCalendar),” RFC 5545, September 2009 (TXT).


 TOC 

Author's Address

  Iulian Radu (editor)
Email:  iulian.radu@gmx.at