Internet Engineering Task Force I. Radu, Ed.
Internet-Draft November 8, 2012
Intended status: Informational
Advanced Groupware Access Protocol
draft-iulian-advanced-groupware-access-protocol-06
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
[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 [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
[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.
Radu Expires February 4, 2013 [Page 1]
Internet-Draft AGAP August 2012
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 February 4, 2013.
Copyright Notice
Copyright (c) 2012 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.
Radu Expires February 4, 2013 [Page 2]
Internet-Draft AGAP August 2012
Table of Contents
1. How to Read This Document . . . . . . . . . . . . . . . 7
1.1. Organization of This Document . . . . . . . . . . . . . 7
1.2. Conventions Used in This Document . . . . . . . . . . . 7
2. Protocol Overview . . . . . . . . . . . . . . . . . . . 7
2.1. Charset Used for Commands and Responses . . . . . . . . 7
2.2. Maximal Length of a Command or Response Line . . . . . . 8
2.3. Numbers in Commands and Responses . . . . . . . . . . . 8
2.4. Regular Expressions in Commands . . . . . . . . . . . . 8
2.5. Unique Identification Numbers (UID) . . . . . . . . . . 10
2.6. Folder Change Identification Numbers (FCID) . . . . . . 10
2.7. Entries Change Identification Numbers (ECID) . . . . . . 10
2.8. Representation of Text and Binary Content in XML
Bodies . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.9. Folders . . . . . . . . . . . . . . . . . . . . . . . . 11
2.9.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.9.2. Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 11
2.9.3. Folder Types . . . . . . . . . . . . . . . . . . . . . . 11
2.9.4. Reserved Folders . . . . . . . . . . . . . . . . . . . . 12
2.10. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.10.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.10.2. Reserved Tag Names . . . . . . . . . . . . . . . . . . . 13
2.11. Folder's Access Rights and Access Control List (ACL) . . 15
2.12. The Responses for Each Type of Folder . . . . . . . . . 15
2.12.1. Format and Conventions . . . . . . . . . . . . . . . . . 15
2.12.2. Response for Calendar Folders . . . . . . . . . . . . . 16
2.12.3. Response for Configuration Folders . . . . . . . . . . . 18
2.12.4. Response for Contact Folders . . . . . . . . . . . . . . 18
2.12.5. Response for File Folders . . . . . . . . . . . . . . . 20
2.12.6. Response for Filter Folders . . . . . . . . . . . . . . 20
2.12.7. Response for Journal Folders . . . . . . . . . . . . . . 21
2.12.8. Response for Message Folders . . . . . . . . . . . . . . 23
2.12.9. Response for Note Folders . . . . . . . . . . . . . . . 25
2.12.10. Response for Task Folders . . . . . . . . . . . . . . . 25
3. States . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1. Not-authenticated State . . . . . . . . . . . . . . . . 28
3.2. Pre-authentication State . . . . . . . . . . . . . . . . 28
3.3. Authenticated (and Selected) State . . . . . . . . . . . 29
3.4. (Authenticated but) Not-selected State . . . . . . . . . 29
3.5. Presence State . . . . . . . . . . . . . . . . . . . . . 30
3.6. Storing State . . . . . . . . . . . . . . . . . . . . . 30
4. Commands . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1. Semantic and Syntax . . . . . . . . . . . . . . . . . . 30
4.2. Syntax of a Tag List . . . . . . . . . . . . . . . . . . 30
4.3. Syntax of a Filter . . . . . . . . . . . . . . . . . . . 31
4.3.1. Syntax of a Filter for a Command . . . . . . . . . . . . 31
4.3.2. Syntax of a Filter for a FILT Folder . . . . . . . . . . 33
Radu Expires February 4, 2013 [Page 3]
Internet-Draft AGAP August 2012
4.4. The Welcome Message - not-authenticated state . . . . . 35
4.5. Command QUIT - all states . . . . . . . . . . . . . . . 36
4.6. Command AUTH mechanism - not-authenticated state . . . . 36
4.7. Command CAPA - not-authenticated state . . . . . . . . . 40
4.8. Command SGZP - not-authenticated state . . . . . . . . . 42
4.9. Command STLS - not-authenticated state . . . . . . . . . 43
4.10. Command HASH - pre-authenticated state (MD5 and SHA1) . 43
4.11. Command PASS - pre-authenticated state (PLAIN) . . . . . 45
4.12. Command USER - pre-authenticated state (PLAIN, MD5
and SHA1) . . . . . . . . . . . . . . . . . . . . . . . 46
4.13. Command AACL - authenticated state . . . . . . . . . . . 47
4.14. Command APBL - authenticated state . . . . . . . . . . . 48
4.15. Command CHNG - authenticated and not-selected state . . 49
4.16. Command COPY - authenticated state . . . . . . . . . . . 50
4.17. Command CPYF - authenticated state . . . . . . . . . . . 51
4.18. Command DACL - authenticated state . . . . . . . . . . . 52
4.19. Command DATT - authenticated state (MESG folder type) . 53
4.20. Command DELE - authenticated state . . . . . . . . . . . 54
4.21. Command DELF - authenticated state . . . . . . . . . . . 55
4.22. Command DPBL - authenticated state . . . . . . . . . . . 56
4.23. Command EXIT - authenticated state . . . . . . . . . . . 57
4.24. Command FCPY - authenticated state . . . . . . . . . . . 57
4.25. Command FDEL - authenticated state . . . . . . . . . . . 59
4.26. Command FIND - authenticated state . . . . . . . . . . . 60
4.27. Command FMOV - authenticated state . . . . . . . . . . . 62
4.28. Command FRTR - authenticated state . . . . . . . . . . . 64
4.29. Command FSTO - storing state . . . . . . . . . . . . . . 66
4.30. Command FTAG - authenticated state . . . . . . . . . . . 68
4.31. Command GACL - authenticated state . . . . . . . . . . . 69
4.32. Command GFTG - authenticated state . . . . . . . . . . . 70
4.33. Command GPBL - authenticated and not-selected state . . 71
4.34. Command GTAG - authenticated state . . . . . . . . . . . 71
4.35. Command LIST - authenticated and not-selected state . . 72
4.36. Command LSTX - authenticated and not-selected state . . 74
4.37. Command MAKE - authenticated and not-selected state . . 76
4.38. Command MOVE - authenticated state . . . . . . . . . . . 77
4.39. Command MOVF - authenticated state . . . . . . . . . . . 78
4.40. Command NAME - authenticated state . . . . . . . . . . . 79
4.41. Command NOOP - authenticated state . . . . . . . . . . . 80
4.42. Command PGET - authenticated, not-selected and
presence state . . . . . . . . . . . . . . . . . . . . . 80
4.43. Command PSET - authenticated and not-selected state . . 83
4.44. Command RETC - authenticated state (MESG folder type) . 85
4.45. Command RETR - authenticated state . . . . . . . . . . . 86
4.46. Command SFTG - authenticated state . . . . . . . . . . . 88
4.47. Command SLCT - authenticated and not-selected state . . 89
4.48. Command STAG - authenticated state . . . . . . . . . . . 90
4.49. Command STAT - authenticated state . . . . . . . . . . . 91
Radu Expires February 4, 2013 [Page 4]
Internet-Draft AGAP August 2012
4.50. Command STOR - authenticated state . . . . . . . . . . . 93
4.51. Command SUID - authenticated state . . . . . . . . . . . 94
5. Responses . . . . . . . . . . . . . . . . . . . . . . . 95
5.1. Semantic and Syntax . . . . . . . . . . . . . . . . . . 95
5.2. 1xx Informational . . . . . . . . . . . . . . . . . . . 96
5.2.1. 100 Reserved . . . . . . . . . . . . . . . . . . . . . . 96
5.2.2. 110 Continue . . . . . . . . . . . . . . . . . . . . . . 96
5.3. 2xx Success . . . . . . . . . . . . . . . . . . . . . . 96
5.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . . . 96
5.3.2. 210 Partial OK . . . . . . . . . . . . . . . . . . . . . 96
5.3.3. 220 Nothing to do . . . . . . . . . . . . . . . . . . . 97
5.4. 4xx Temporary Server Error . . . . . . . . . . . . . . . 97
5.4.1. 400 Reserved . . . . . . . . . . . . . . . . . . . . . . 97
5.4.2. 401 Internal Error . . . . . . . . . . . . . . . . . . . 97
5.4.3. 410 Retry later . . . . . . . . . . . . . . . . . . . . 97
5.5. 5xx Permanent Server Error . . . . . . . . . . . . . . . 97
5.5.1. 500 Reserved . . . . . . . . . . . . . . . . . . . . . . 97
5.5.2. 510 Unknown Command . . . . . . . . . . . . . . . . . . 97
5.5.3. 511 Invalid Parameter Format . . . . . . . . . . . . . . 97
5.5.4. 512 Out of order . . . . . . . . . . . . . . . . . . . . 97
5.5.5. 521 Not found . . . . . . . . . . . . . . . . . . . . . 98
5.5.6. 531 Banned . . . . . . . . . . . . . . . . . . . . . . . 98
5.5.7. 541 Not enough rights . . . . . . . . . . . . . . . . . 98
6. All Possible Response Codes for All Commands . . . . . . 98
6.1. Not-authenticated State . . . . . . . . . . . . . . . . 98
6.2. Pre-authenticating State (PLAIN method) . . . . . . . . 98
6.3. Pre-authenticating State (MD5 and SHA1 methods) . . . . 99
6.4. Authenticated State . . . . . . . . . . . . . . . . . . 99
6.5. Not-selected State . . . . . . . . . . . . . . . . . . . 102
6.6. Presence State . . . . . . . . . . . . . . . . . . . . . 102
6.7. Storing State . . . . . . . . . . . . . . . . . . . . . 102
7. Example of Conversations . . . . . . . . . . . . . . . . 103
7.1. Successful connection and authentication . . . . . . . . 103
7.2. Successful connection but unsuccessful authentication . 104
7.3. Connection refused . . . . . . . . . . . . . . . . . . . 104
7.4. Find what folders are available with messages . . . . . 105
7.5. Find all entries available in a folder . . . . . . . . . 105
7.6. Retrieve a message . . . . . . . . . . . . . . . . . . . 105
7.7. Retrieve a contact . . . . . . . . . . . . . . . . . . . 106
7.8. Retrieve an event . . . . . . . . . . . . . . . . . . . 107
7.9. Store a message . . . . . . . . . . . . . . . . . . . . 108
7.10. Store a contact . . . . . . . . . . . . . . . . . . . . 108
7.11. Store an event . . . . . . . . . . . . . . . . . . . . . 109
7.12. Mark messages as SPAM an move them in a new folder . . . 109
7.13. Create a filter folder, find the matching entries of
the filter and read its filter definition . . . . . . . 110
7.14. Create a folder and rename it . . . . . . . . . . . . . 111
7.15. Find the status for a folder . . . . . . . . . . . . . . 111
Radu Expires February 4, 2013 [Page 5]
Internet-Draft AGAP August 2012
7.16. Set and check the tags of a message . . . . . . . . . . 111
7.17. Find messages that can be SPAM and delete them . . . . . 112
7.18. Connect for a short period . . . . . . . . . . . . . . . 112
8. References . . . . . . . . . . . . . . . . . . . . . . . 113
8.1. Normative References . . . . . . . . . . . . . . . . . . 113
8.2. Informative References . . . . . . . . . . . . . . . . . 113
Author's Address . . . . . . . . . . . . . . . . . . . . 114
Radu Expires February 4, 2013 [Page 6]
Internet-Draft AGAP August 2012
1. How to Read This Document
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.
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' [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
[RFC3629] specification.
2. Protocol Overview
2.1. Charset Used for Commands and Responses
All data exchanged between the server and the client is done using
strings encoded UTF-8 [RFC3629]. If the server or client send a
string incorrect encoded then the other side can close immediately
the connection.
Radu Expires February 4, 2013 [Page 7]
Internet-Draft AGAP August 2012
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.
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.
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:
Radu Expires February 4, 2013 [Page 8]
Internet-Draft AGAP August 2012
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
Radu Expires February 4, 2013 [Page 9]
Internet-Draft AGAP August 2012
2.5. Unique Identification Numbers (UID)
The length of an UID is between 1 and 32 characters.
The UIDs MUST to be unique only between items 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 the same for each
connections, except after server change it and announce the change by
changing the ECID assigned to the corresponding folder.
Any new item MUST have a bigger UID as all other existing items in
the selected folder. The sorting is made according UTF-8 [RFC3629]
(digits before letters and uppercase letters before the lowercase
letters - 0..9A..Za..z). A shorter 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 4.50+e+17 unique
combinations for 32 characters long UIDs. We get a maximum number of
3381098545 unique combinations for 8 characters long UIDs.
2.6. Folder Change Identification Numbers (FCID)
An FCID has the same format as a normal UID and each new value of an
FCID is bigger as the precedent one (as is described for UIDs). An
FCID is changed for a folder when the structure of the folder is
changed (subfolders are added or removed). The FCID of a folder is
not changed if it is changed the (sub)child of one of its children.
2.7. Entries Change Identification Numbers (ECID)
An ECID has the same format as a normal UID and each new value of an
ECID is bigger as the precedent one (as is described for UIDs). If
the last ECID had already had the biggest valid UID value then its
new value can be the first valid UID value. An ECID is changed for a
folder when items ware added or removed. Or when the server had
changed the UIDs assigned to the items. This can be necessary if,
for example, there is a new item and already last valid UID was
assigned to an other item. The new UIDs must keep the items in the
same order as before the renumbering.
2.8. Representation of Text and Binary Content in XML Bodies
Binary content must be encoded using the BASE64 [RFC4648] method and
the corresponding tag must have the ENCODED attribute set to
"base64".
Radu Expires February 4, 2013 [Page 10]
Internet-Draft AGAP August 2012
A text content can be passed as it is (UTF-8 [RFC3629]) or it can be
encoded using the BASE64 [RFC4648] method. The corresponding tag
must have the ENCODED attribute set to "utf-8", in case of plain
text, and to "base64", if the content was encoded using the BASE64
method.
2.9. Folders
2.9.1. Naming
All folder names are case sensitive and they are encoded according to
UTF-8 [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 [RFC3629]
characters with a value bigger then 0x1f (white space is the first
allowed character), but with the exception of the slash (/ 9x2F),
back slash (\ 0x5C), multiplication sign (* 0x2A), and question mark
(? 0x3F).
The following folder names are also not accepted: '.', and '..'.
2.9.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.
2.9.3. Folder Types
The following folder types are defined by this standard:
o calendar - CALE - holds events;
o configuration - CONF - holds user accounts configuration (the
client is free to store all information it needs for providing
roaming);
Radu Expires February 4, 2013 [Page 11]
Internet-Draft AGAP August 2012
o contacts - ADDR - holds contact information;
o files - FILE - holds files that have no special meanings for the
server;
o filter - FILT - holds the definition of a filter (it does not
allow subfolders);
o folder - FOLD - contains only subfolders;
o journal - JRNL - holds journal entries;
o message - MESG - holds e-mail messages;
o notes - NOTE - holds short texts;
o tasks - TASK - holds tasks.
Each of these types allow for subfolders in them.
2.9.4. Reserved Folders
All the following reserved folders are located in the root of the
user's account:
o CALENDAR - CALE - holds the main calendar of the user (PUBLIC);
o CONFIGURATION - CONF - holds account configuration;
o CONTACT - ADDR - holds the main contact list (PUBLIC);
o DRAFT - MESG - holds templates for e-mail messages;
o FILESHARE - FILE - holds shared files (PUBLIC);
o INBOX - MESG - holds all new e-mail messages (PUBLIC);
o JOURNAL - JRNL - holds the main journal (PUBLIC);
o JUNK - MESG - holds all e-mail messages marked as SPAM or VIRUSED
by user or the server;
o NOTE - NOTE - holds short texts (PUBLIC);
o OUTBOX - MESG - holds all e-mail messages that wait to be sent;
o SENT - MESG - holds copy of sent e-mail messages;
Radu Expires February 4, 2013 [Page 12]
Internet-Draft AGAP August 2012
o TASK - TASK - holds the main tasks list (PUBLIC);
o TRASH - MESG - holds all deleted e-mail messages;
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.
2.10. Tags
2.10.1. Syntax
The client can set tags for folder and folder entries. The tags of a
folder are reported by the STAT command and can be read with GFTG.
The tags of an entry can be get with GTAG. The tags of a server can
be set with SFTG, and the tags for folder entries with STAG.
The format of a tag is a name optionally followed by the equal sign
(=) and a value. Each time a tag is set, the new value replace the
old one. All tags that have no value assigned are returned only as
names. Assigning an empty value to a tag makes it to return a name
followed by the equal sign and no value. Setting a tag without a
value for an entry which previously had the same tag with a value
makes the tag to lose its value and to be returned as name only
(without the equal sign).
The characters accepted for building a TAG are only all 26 Latin
letters (A-Z) in uppercase, all 10 Latin digits (0-9) and the minus
sign (-). A TAG is case insensitive. Its length is between 1 and 32
characters.
The characters accepted for a TAG value are only all 26 Latin letters
(A-Z) in lowercase and uppercase, all 10 Latin digits (0-9), plus the
minus (-), underscore (_) and dot (.) characters. A TAG value is
case sensitive. Its length is between 1 and 32 characters.
The server returns always the TAG names in uppercase, even if the
client set them using a lowercase version. The server should convert
silently any lowercase character in a TAG name (sent by client) to
its corresponding uppercase character.
2.10.2. Reserved Tag Names
The following tag names have a meaning set by this standard for
folders:
Radu Expires February 4, 2013 [Page 13]
Internet-Draft AGAP August 2012
o FIX-TAGS - the tags of this folder cannot be changed with FTGS;
o NO-COPY - the content of this folder cannot be copied with CPYF,
COPY, or FCPY but can be deleted with DELF, DELE, or FDEL or moved
with MOVF, MOVE, or FMOV;
o NO-DELETE - the folder or the content of this folder cannot be
deleted with DELF, DELE or FDEL but can be copied with CPYF, COPY,
or FCPY or moved with MOVF, MOVE, or FMOV;
o NO-DELF - this folder cannot be deleted with DELF but its content
can be deleted with DELF, DELE, or FDEL if the tag NO-DELETE is
not assigned to the folder;
o NO-FOLDERS - this entry cannot have subfolders, so the user cannot
create subfolders in it with MAKE;
o NO-MOVE - the content of this folder cannot be moved with MOVF,
MOVE, or FMOV but can be deleted with DELF, DELE, or FDEL or
copied with CPYF, COPY, or FCPY;
o NO-RENAME - the name of this folder cannot be changed with NAME;
o READ-ONLY - the user can read it with RETR and delete it with
DELF, DELE, or FDEL but cannot write in it with STOR, CPYF, COPY,
FCPY, MOVF, MOVE, or FMOV, create subfolders in it with MAKE or
change the tags of its content with STAG, or FTAG;
o RESERVED - it is a folder reserved by this standard; the user can
write in it with STOR but cannot delete it with DELF or rename it
with NAME;
When the user do a DELF for a folder with the tag NO-DELF but without
the tag NO-DELETE then the non-folder content will gone be deleted
but not the folder.
When the user do a DELF for a folder with the tag NO-DELETE then the
folder and its content will not gone be deleted (the tag NO-DELF is
ignored).
Implicit a folder can be read only by its owner.
The following tag names have a meaning set by this standard for
messages:
o ANSWERED - a replay was sent for this item;
Radu Expires February 4, 2013 [Page 14]
Internet-Draft AGAP August 2012
o FORWARDED - the message was forwarded by the user;
o SEEN - the message was sow by the user;
o SPAM - this e-mail message is marked as spam;
2.11. Folder's Access Rights and Access Control List (ACL)
An access right is represented by a letter between a and z,
respectivelly between A and Z. A lowercase letter represents a
different right then its uppercase version.
This document defines following rights:
o r - it is allowed to read folder's attributes and tags;
o A - it is allowed to add entries to the folder;
o D - it is allowed to delete entries from folder;
o L - it is allowed to find which entries (IDs) holds the folder;
o R - it is allowed to read the folder's entries
The ACL of a folder is made from pairs of rights and an account name.
The rights are checked only at the access moment in the state STORING
and PRESENCE.
The account name is a regexp as defined in chapter 2.4 Regular
Expressions in Commands.
2.12. The Responses for Each Type of Folder
2.12.1. Format and Conventions
All responses are in XML format. The tags and their attributes names
are written only in uppercase. The values for attributes only in
lowercase. The exception are header entries for a message. The tags
keep the case from the message.
The content is encoded in UTF-8 [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.
Radu Expires February 4, 2013 [Page 15]
Internet-Draft AGAP August 2012
Each tag that have a question mark will be present only once if it is
the case and without the question mark.
Each tag that have a star will be present, possible many times, 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.
2.12.2. Response for Calendar Folders
The format is derived from the one defined for VEVENT and VALARM by
the iCalendar [RFC5545] standard.
The following example corresponds to this VEVENT definition:
BEGIN:VEVENT
UID:20110531T114600Z-123456@agap.at
DTSTAMP:2011-05-31T12:10:00Z
DTSTART:2011-06-07T18:00:00Z
DTEND:2011-06-07T24:00:00Z
SUMMARY:AGAP RFC Party
DESCRIPTION:Celebration of a new revision!\n0.4
END:VEVENT
Figure 2
Example event:
20110531T114600Z-123456@agap.at2011-05-31T12:10:00Z2011-06-07T18:00:00Z2011-06-07T24:00:00ZAGAP RFC PartyCelebration of a new revision!
0.420110607T170000Z-20110531T114600Z-123456@agap.at
Figure 3
The following example corresponds to this alarm definition related to
the previous event:
Radu Expires February 4, 2013 [Page 16]
Internet-Draft AGAP August 2012
BEGIN:VALARM
TRIGGER;RELATED=START:2011-06-07T17:00:00Z
REPEAT:3
DURATION:PT15M
ACTION:AUDIO
ATTACH;FMTTYPE=audio/mpeg;VALUE=BINARY;ENCODING=BASE64:
ABCDEFGHIJ==
END:VALARM
Figure 4
Example alarm:
20110607T170000Z-20110531T114600Z-123456@agap.at
20110531T114600Z-123456@agap.at2011-06-07T17:00:00Z3PT15MAUDIO
ABCDEFGHIJ==
Figure 5
The BEGIN:VEVENT is replaced with and END:VEVENT is replaced
with . The BEGIN:VALARM is replaced with and END:
VALARM is replaced with . Each type in VEVENT/VALARM has a
corresponding tag in uppercase. All attributes are lowercase. Any
escaped semicolon or comma in VEVENT/VALARM is also passed prefixed
with a backslash in XML. Any \n is replaced with a real end of line.
The VEVENT/VALARM attributes LANGUAGE, VALUE and CHARSET must not be
present in XML. The attribute ENCODING="BASE64" is replaced with
ENCODED="base64", any other encoding scheme is silently dropped. The
client can also send an attribute ENCODED="utf-8" as this is the
default encoding for tags. The format for a timestamp is: yyyy-mm-
ddThh:mm:ssZ. All times are UTC/GMT times according Representation
of dates and times [ISO.8601.1988]. As VEVENT/VALARM attribute VALUE
is missing then the format of the value is detected automatically
based on the context. For example, a value starting with 'http://'
corresponds to a 'VALUE=uri'; an 'ENCODED="base64"' corresponds to a
'VALUE=binary'. Were VEVENT/VALARM standar accepts a date or a date-
time then we expect to receive a timestamp (date-time). There are
not accepted tags that corresponds to VEVENT/VALARM types having
'VALUE=uri:CID:', so referincing parts that cannot exists in this
Radu Expires February 4, 2013 [Page 17]
Internet-Draft AGAP August 2012
XML. The DURATION must be always a relative value (starts with a P
or -P). As a VALARM is no more a child of a VEVENT we need to link
the two entities. A VEVENT with an associated VALARM must include a
VALARM tag having the UID of the associated VALARM. A VALARM must
have an UID defined and a RELATED-TO tag holding the UID of the
associated VEVENT. Optionally RELATED-TO can have a SOURCE attribute
with a value 'vevent'. An VEVENT can have only one VALARM
associated.
2.12.3. Response for Configuration Folders
A response holding the configuration has the following structure:
value...
Figure 6
Example:
101024
Figure 7
2.12.4. Response for Contact Folders
The format is derived from the one defined by the vCard [RFC2426]
standard.
The following example corresponds to this VCARD definition:
Radu Expires February 4, 2013 [Page 18]
Internet-Draft AGAP August 2012
BEGIN:VCARD
VERSION:3.0
FN:Iulian Radu
N:Radu;Iulian;;Dipl.Ing.;
ORG:Example Com\, Inc.;European Division
EMAIL;TYPE=internet,home:iulian.radu@gmx.at
TZ:+01:00
REV:2011-05-31T18:46:00Z
LOGO;TYPE=JPEG;ENCODING=b:ABCDEFGHIJ==
LABEL;TYPE=work;TYPE=parcel,intl:1. Operngasse\n1010 Wien\nAustria
END:VCARD
Figure 8
Example:
3.0Iulian RaduRadu;Iulian;;Dipl.Ing.;Example Com\, Inc.;European Divisioniulian.radu@gmx.at+01:002011-05-31T18:46:00ZABCDEFGHIJ==
Figure 9
The BEGIN:VCARD is replaced with and END:VCARD is replaced
with . Each type in VCARD has a corresponding tag. As in
RFC all types are defined in uppercase so are also defined all tags.
All attributes are lowercase. All values of attribute TYPE from a
VCARD must to be gathered together in a single list and passed as
attribute TYPE to the corresponding tag (they are delimited by
commas). Any escaped semicolon or comma in VCARD is also passed
prefixed with a backslash in XML. Any \n is replaced with a real end
of line. The VCARD attributes LANGUAGE, VALUE, CONTEXT and CHARSET
must not be present in XML. The attribute ENCODING="b" is replaced
with ENCODED="base64", any other encoding scheme is silently dropped.
The client can also send an attribute ENCODED="utf-8" as this is the
default encoding for tags. The format for a date is: YYYY-MM-DD.
The format for a time is: HH:MM:SS. The format for a timestamp is:
yyyy-mm-ddThh:mm:ssZ. All times are UTC/GMT times according
Radu Expires February 4, 2013 [Page 19]
Internet-Draft AGAP August 2012
Representation of dates and times [ISO.8601.1988]. As VCARD
attribute VALUE is missing then the format of the value is detected
automatically based on the context. For example, a value starting
with 'http://' corresponds to a 'VALUE=uri'; an 'ENCODED="base64"'
corresponds to a 'VALUE=binary'. Were VCARD standar accepts a date
or a date-time then we expect to receive a timestamp (date-time). It
is not accepted a SOURCE VCARD type as the content of this VCARD must
to be defined inside of the XML. Also are not accepted tags that
corresponds to VCARD types having 'VALUE=uri:CID:', so referincing
parts that cannot exists in this XML.
2.12.5. Response for File Folders
A response holding the content of a file has the following structure:
namecontent
Figure 10
The valid encodings type are: utf-8 and base64. The default encoding
is base64.
Example:
Example.txtc3VyZS4=
Figure 11
2.12.6. Response for Filter Folders
An entryTag can be: AND, OR, NOT, UID, TAG, IS, REGEX. The value
associated to entryTag is specified as an 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 4.3 Syntax of a Filter for more
information). The tag RULES group all its rules in an AND group.
There must be assigned at least one folder and must be present at
least a rule. Optionally can be gived a description using ABOUT tag.
Cannot be assigned as folders for being searched folders of the
following types: FILT, FOLD.
Radu Expires February 4, 2013 [Page 20]
Internet-Draft AGAP August 2012
A response holding the content of a file has the following structure:
...?
......
......
Figure 12
Example:
A sample FILT filter./INBOX/SpamViagraUIDx1234:UIDx4321SPAM
Figure 13
2.12.7. Response for Journal Folders
The format is derived from the one defined for VJOURNAL by the
iCalendar [RFC5545] standard.
The following example corresponds to this VJOURNAL definition:
Radu Expires February 4, 2013 [Page 21]
Internet-Draft AGAP August 2012
BEGIN:VJOURNAL
UID:20110531T184600Z-123456@agap.at
DTSTAMP:2011-06-07T13:52:38Z
DTSTART:2011-06-07T13:52:38Z
SUMMARY:Revise AGAP Internet-Draft
DESCRIPTION:1. The draft was revised\, saved and
closed.\n2. It is ready to be published.\n
ATTACH;FMTTYPE=text/plain;VALUE=BINARY;ENCODING=BASE64:
ABCDEFGHIJ==
END:VJOURNAL
Figure 14
Example:
20110531T184600Z-123456@agap.at2011-06-07T13:52:38Z2011-06-07T13:52:38ZRevise AGAP Internet-Draft1. The draft was revised\, saved and closed.
2. It is ready to be published.
ABCDEFGHIJ==
Figure 15
The BEGIN:VJOURNAL is replaced with and END:VJOURNAL is
replaced with . Each type in VJOURNAL has a corresponding
tag in uppercase. All attributes are lowercase. Any escaped
semicolon or comma in VJOURNAL is also passed prefixed with a
backslash in XML. Any \n is replaced with a real end of line. The
VJOURNAL attributes LANGUAGE, VALUE and CHARSET must not be present
in XML. The attribute ENCODING="BASE64" is replaced with
ENCODED="base64", any other encoding scheme is silently dropped. The
client can also send an attribute ENCODED="utf-8" as this is the
default encoding for tags. The format for a timestamp is: yyyy-mm-
ddThh:mm:ssZ. All times are UTC/GMT times according Representation
of dates and times [ISO.8601.1988]. As VTODO attribute VALUE is
missing then the format of the value is detected automatically based
on the context. For example, a value starting with 'http://'
corresponds to a 'VALUE=uri'; an 'ENCODED="base64"' corresponds to a
'VALUE=binary'. Were VJOURNAL standar accepts a date or a date-time
then we expect to receive a timestamp (date-time). There are not
accepted tags that corresponds to VJOURNAL types having 'VALUE=uri:
Radu Expires February 4, 2013 [Page 22]
Internet-Draft AGAP August 2012
CID:', so referincing parts that cannot exists in this XML.
2.12.8. Response for Message Folders
A response holding the content of a message has the following
structure:
value...
value 1
value 2
...
value n......
main text
main html
...
...
...
Figure 16
The first attachment id has value 1.
The id of on item tag shows the order of the entries in the original
message.
The default content encoding is utf-8. It is assumed that the
content for TEXT and HTML is encoded in UTF-8 when the ENCODED
attribut has the value base64.
The entries in the header of the main message and attachments are the
same with the one from the e-mail message.
There can be at most 2,147,483,647 attachments defined and their
numbers must be sequential starting with 1.
Example:
Radu Expires February 4, 2013 [Page 23]
Internet-Draft AGAP August 2012
example@no-spam.comexample@example.com
from mail.yahoo.com by example.com; Tue, 16 Mar 2010 12:14:24 +0100
from no-spam.com by mail.yahoo.com; Mon, 15 Mar 2010 11:13:23 +0100
multipart/mixed; boundary="XYZ"A basic examplePlease see the attachments.
<b>Please</b> see the <u>attachments</u>.
text/plain
See the picture.
image/jpegbase64
c3VyZS4=
Figure 17
The previous example corresponds to a message with the following
structure:
o multipart/mixed
* multipart/alternative
+ text/plain
+ text/html
Radu Expires February 4, 2013 [Page 24]
Internet-Draft AGAP August 2012
* text/plain
* image/jpeg
2.12.9. Response for Note Folders
A response holding the content of the note has the following
structure:
......
Figure 18
Note: the subject can be any short text. The content can be encoded
UTF-8 or BASE64. Implicit is content encoded in utf-8. The type can
be any subtype of 'text/*'. Implicit is 'text/plain'. It is
recommended to be used only 'text/plain' and 'text/html'.
Example:
Important!
To review the code.
Figure 19
2.12.10. Response for Task Folders
The format is derived from the one defined for VTODO by the iCalendar
[RFC5545] standard.
The following example corresponds to this VTODO definition:
Radu Expires February 4, 2013 [Page 25]
Internet-Draft AGAP August 2012
BEGIN:VTODO
UID:20110531T184600Z-123456@agap.at
DTSTAMP:2011-05-31T18:46:00Z
DTSTART:2011-06-07T12:00:00Z
DUE:2011-06-07T14:00:00Z
COMPLETED:2011-06-07T13:52:38Z
SUMMARY:Revise AGAP Internet-Draft
PRIORITY:1
STATUS:NEEDS-ACTION
ATTACH;FMTTYPE=text/plain;VALUE=BINARY;ENCODING=BASE64:
ABCDEFGHIJ==
END:VTODO
Figure 20
Example:
20110531T184600Z-123456@agap.at2011-05-31T18:46:00Z2011-06-07T12:00:00Z2011-06-07T14:00:00Z2011-06-07T13:52:38ZRevise AGAP Internet-Draft1NEEDS-ACTION
ABCDEFGHIJ==20110607T170000Z-20110531T184600Z-123456@agap.at
Figure 21
The following example corresponds to this alarm definition related to
the previous task:
Radu Expires February 4, 2013 [Page 26]
Internet-Draft AGAP August 2012
BEGIN:VALARM
TRIGGER;RELATED=START:2011-06-07T17:00:00Z
REPEAT:3
DURATION:PT15M
ACTION:AUDIO
ATTACH;FMTTYPE=audio/mpeg;VALUE=BINARY;ENCODING=BASE64:
ABCDEFGHIJ==
END:VALARM
Figure 22
Example alarm:
20110607T170000Z-20110531T184600Z-123456@agap.at
20110531T184600Z-123456@agap.at2011-06-07T17:00:00Z3PT15MAUDIO
ABCDEFGHIJ==
Figure 23
The BEGIN:VTODO is replaced with and END:VTODO is replaced
with . The BEGIN:VALARM is replaced with and END:
VALARM is replaced with . Each type in VTODO/VALARM has a
corresponding tag in uppercase. All attributes are lowercase. Any
escaped semicolon or comma in VTODO/VALARM is also passed prefixed
with a backslash in XML. Any \n is replaced with a real end of line.
The VTODO/VALARM attributes LANGUAGE, VALUE and CHARSET must not be
present in XML. The attribute ENCODING="BASE64" is replaced with
ENCODED="base64", any other encoding scheme is silently dropped. The
client can also send an attribute ENCODED="utf-8" as this is the
default encoding for tags. The format for a timestamp is: yyyy-mm-
ddThh:mm:ssZ. All times are UTC/GMT times according Representation
of dates and times [ISO.8601.1988]. As VTODO/VALARM attribute VALUE
is missing then the format of the value is detected automatically
based on the context. For example, a value starting with 'http://'
corresponds to a 'VALUE=uri'; an 'ENCODED="base64"' corresponds to a
'VALUE=binary'. Were VTODO/VALARM standars accept a date or a date-
time then we expect to receive a timestamp (date-time). There are
not accepted tags that corresponds to VTODO/VALARM types having
'VALUE=uri:CID:', so referincing parts that cannot exists in this
Radu Expires February 4, 2013 [Page 27]
Internet-Draft AGAP August 2012
XML. The DURATION must be always a relative value (starts with a P
or -P). As a VALARM is no more a child of a VTODO we need to link
the two entities. A VTODO with an associated VALARM must include a
VALARM tag having the UID of the associated VALARM. A VALARM must
have an UID defined and a RELATED-TO tag holding the UID of the
associated VTODO. Optionally RELATED-TO can have a SOURCE attribute
with a value 'vtodo'. An VTODO can have only one VALARM associated.
3. States
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.
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'
Radu Expires February 4, 2013 [Page 28]
Internet-Draft AGAP August 2012
(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'.
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'.
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'
Radu Expires February 4, 2013 [Page 29]
Internet-Draft AGAP August 2012
command or if the INBOX folder does not exists and it cannot be
selected automatically after a successful authentication.
3.5. Presence State
This is the state in which a client can only ask information about
the presence of an user/account.
In this state the client can use only the command 'PGET' to ask for
presence information of an account (inclusive finding when a meeting
can be scheduled) and the command 'QUIT' for terminating the
connection.
3.6. Storing State
This is the state in which a client can only add items (for example:
messages, events) in an account which it is not his/her.
In this state the client can use only the command 'FSTO' to find and
store the item into a folder of specified type from specified user
and the command 'QUIT' for terminating the connection.
4. Commands
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).
4.2. Syntax of a Tag List
A tag list is used by the following commands: FTAG, GTAG, SFTG and
STAG.
A tag list defines what action to be done with its tags.
Syntax: ACTION TAG TAG=VALUE ...
ACTION:
Radu Expires February 4, 2013 [Page 30]
Internet-Draft AGAP August 2012
o = - set only these tags;
o + - add these tags
o - - delete these tags.
Note: When it is used the delete tags action and for a tag is set a
value then the tag is deleted only if the current value match the
value found in the delete command. If in delete command is specified
a value for a tag which actually has no value set then this tag is
not deleted. If in delete command is specified only the name of a
tag without a value and the tag has a value assigned then the tag is
deleted.
Example:
C: STAG UIDx1234 = SEEN SPAM=YES
C: STAG UIDx1234 + SEEN FLAG=RED OWNER=RAI
C: STAG UIDx1234 - FLAG JUNK OWNER=JOHN SEEN=
Figure 24
Note: After this three commands we have only the following tags: SEEN
SPAM=YES JUNK OWNER=RAI.
4.3. Syntax of a Filter
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 entries. 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).
A rule must be completely defined in the same line (exception are
grouping, AND, OR, and NOT rules).
Accepted rules:
o ( ) - grouping for AND and OR;
o AND - all following rules are with AND bonded (until the end of
the current group). It is the implicit rule when the first rule
Radu Expires February 4, 2013 [Page 31]
Internet-Draft AGAP August 2012
is not an AND or an OR;
o OR - all following rules are with OR bonded (until the end of the
current group);
o NOT - invert the result of the following rule;
o UID uid - one UID;
o UID uid_begin_range:uid_end_range - inclusive range (uid_end_range
is optional and if it missing then it is assumed the maximum valid
UID: 32 of lower-case letter z);
o TAG tag_name - a tag of an entry;
o TAG tag_name=tag_value - an entry's tag with a value (tag_value is
the complete value);
o IS field_path op string - a field from the content (as XML) with
an exact matched text (string is written between ' and ' can be
escaped with \'); op can be: <, <=, =, !=, >=, >;
o REGEX field_path op regex_string - a field from the content (as
XML) with a regular expression matched text (regex_string is
written between ' and ' can be escaped with \'); op can be: =, !=;
the regex_string can match only a part of the content.
o NEW - it is true if an entry is new; after an entry was reported
as new (by FIND, FRTR or a filter folder) it will be marked as no
longer being new and it will not be matched by a new search for
new entries.
The field_path is a PATH in the response as it is returned by RETR
and must point to an end leaf. It contains only tag names separated
with /. Example: /MESSAGE/HEADER/subject, /MESSAGE/HEADER/received,
/MESSAGE/BODY/HTML, /MESSAGE/BODY/ATTACHMENT-1/BODY.
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.
For values which are lists with values delimited by comma or semi-
colon it is possible to extract an item using square brackets ([])
for lists delimited by comma and curly brackets ({}) for lists
delimited by semi-colons.
It can be searched only in the body of attachments that have a
content type of type 'text/*'.
Example 1: These filters find all messages with the UID between
Radu Expires February 4, 2013 [Page 32]
Internet-Draft AGAP August 2012
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 25
Example 2:
C: IS /MESSAGE/HEADER/SUBJECT = 'From University'
C: REGEX /MESSAGE/HEADER/FROM != '[^0-9]+@example\.com$'
C: IS /VCARD/FN = 'Anonymous'
C: REGEX /VCARD/ORG = '^[A-Za-z]+[0-9]$'
Figure 26
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 an 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:
o AND - all its entries must be matched;
o OR - at least one of its entries must be matched;
o NOT - invert the result of its child rule;
o UID uid - one UID;
o UID uid_begin_range:uid_end_range - inclusive range;
o TAG tag_name - a tag;
o TAG tag_name=tag_value - a tag with a value (tag_value is the
complete value);
Radu Expires February 4, 2013 [Page 33]
Internet-Draft AGAP August 2012
o IS field_path op string - a field from the content (as XML) with
an exact matched text (string is written between ' and ' can be
escaped with \'); op can be: <, <=, =, !=, >=, >;
o REGEX field_path op regex_string - a field from the content (as
XML) with a regular expression matched text (regex_string is
written between ' and ' can be escaped with \'); op can be: =, !=;
the regex_string can match only a part of the content.
The field_path is a PATH in the response as it is returned by RETR
and must point to an end leaf. It contains only tag names separated
with /. Example: /MESSAGE/HEADER/subject, /MESSAGE/HEADER/received,
/MESSAGE/BODY/HTML, /MESSAGE/BODY/ATTACHMENT-1/BODY.
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:
/INBOXUIDx0001:UIDx0010SPAMHAS=VIRUSSEEN
Figure 27
Example 2:
Radu Expires February 4, 2013 [Page 34]
Internet-Draft AGAP August 2012
/INBOXFrom University
[^0-9]+@example\.com$Anonymous^[A-Za-z]+[0-9]$
Figure 28
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 29
S: 401 Internal error, please contact our administrator
Figure 30
Radu Expires February 4, 2013 [Page 35]
Internet-Draft AGAP August 2012
S: 410 Sorry, too many connections, please retry later
Figure 31
S: 531 Your hostname/IP (localhost:127.0.0.1) is blacklisted
Figure 32
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 33
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. The name of the
mechanism can contain only latin letters (A-Z), digits (0-9), the
signs minus (-) and underscore (_). It is case insensitive. All
supported mechanisms must to be advertised in CAPA's list of
capabilities as AUTH-MechanismNameInUpperCase.
Radu Expires February 4, 2013 [Page 36]
Internet-Draft AGAP August 2012
The PLAIN Authentication Mechanism: the client send the username and
password in clear text using the commands USER and PASS.
The MD5 and SHA1 Authentication Mechanisms: the server send an
additional line starting with a dot and providing a prefix that will
gone be used by the client to send back to the server an MD5 or SHA-1
value computed on the string build from this prefix and user's
password. This prefix can have between 1 and 256 characters.
Allowed characters are any UTF-8 characters having a code bigger the
decimal value 31 (first valid character is space). The initial dot
is not part of the prefix. The client send the username and the
computed hash using the commands USER and HASH.
The PRESENCE Authentication Mechanism: this mechanism is used by a
client to query the presence of an user having an account on the
server. If the server knows to forward the request to other servers
(in case that requested account in not local) then it can return the
answer from the remote server. The client send the username and
password in clear text using the commands USER and PASS. For an
anonymous access the server can accept as username anonymous and as
password the email address of the connecting user. Once the username
and password are accepted, the server enters in the presence state
and the client can execute only the commands PGET and QUIT.
The PRESENCE-MD5 and PRESENCE-SHA1 Authentication Mechanisms: these
mechanisms are working similar with MD5 and SHA1 authentication
mechanisms, only that move the server in the same status as PRESENCE
authentication mechanism.
The STORING Authentication Mechanism: this mechanism is used by a
client to store items in accounts which are not his/hers. The client
send the username and password in clear text using the commands USER
and PASS. For an anonymous access the server can accept as username
anonymous and as password the email address of the connecting user.
Once the username and password are accepted, the server enters in the
storing state and the client can execute only the commands FSTO and
QUIT.
The STORING-MD5 and STORING-SHA1 Authentication Mechanisms: these
mechanisms are working similar with MD5 and SHA1 authentication
mechanisms, only that move the server in the same status as STORING
authentication mechanism.
Examples:
Radu Expires February 4, 2013 [Page 37]
Internet-Draft AGAP August 2012
C: AUTH PLAIN
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send PASS
C: PASS email@example.com
S: 200 OK User anonymous authenticated
Figure 34
C: AUTH MD5
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 200 OK Authenticated
Figure 35
C: AUTH SHA1
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b4
S: 200 OK Authenticated
Figure 36
C: AUTH PRESENCE
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send PASS
C: PASS email@example.com
S: 200 OK User anonymous authenticated
Figure 37
Radu Expires February 4, 2013 [Page 38]
Internet-Draft AGAP August 2012
C: AUTH PRESENCE-MD5
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 200 OK User anonymous authenticated
Figure 38
C: AUTH PRESENCE-SHA1
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b4
S: 200 OK User anonymous authenticated
Figure 39
C: AUTH STORING
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send PASS
C: PASS email@example.com
S: 200 OK User anonymous authenticated
Figure 40
C: AUTH STORING-MD5
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 200 OK User anonymous authenticated
Figure 41
Radu Expires February 4, 2013 [Page 39]
Internet-Draft AGAP August 2012
C: AUTH STORING-SHA1
S: .Hash prefix ... for user's password
S: 200 OK Send USER
C: USER anonymous
S: 200 OK Send HASH
C: HASH de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b4
S: 200 OK User anonymous authenticated
Figure 42
C: AUTH
S: 510 UNKNOWN command
Figure 43
C: AUTH unknown
S: 511 UNKNWON method
Figure 44
4.7. Command CAPA - not-authenticated state
Name: capabilities
Arguments: none
Result: 200
Description: Ask for the parts of this standards or extensions
supported by the server.
Following is a list with all capabilities defined and covered by this
document. If the server do no present an entry from the following
list then the client must assume that the sever is unable to do the
associated operations of the missing entry.
o ADDR - contact information;
o AUTH-PLAIN - suport plain authentication;
o AUTH-PRESENCE - suport authentication for asking about presence;
o AUTH-PRESENCE-MD5 - suport authentication for asking about
presence;
Radu Expires February 4, 2013 [Page 40]
Internet-Draft AGAP August 2012
o AUTH-PRESENCE-SHA1 - suport authentication for asking about
presence;
o AUTH-MD5 - suport MD5 authentication;
o AUTH-SHA1 - suport SHA1 authentication;
o AUTH-STORING - suport authentication for receiving items;
o AUTH-STORING-MD5 - suport authentication for receiving items;
o AUTH-STORING-SHA1 - suport authentication for receiving items;
o CALE - events;
o CHNG - list the FCID of all folders;
o CONF - user accounts configuration;
o FACL - ACL for folders;
o FILE - storing files;
o FILT - definition of a filter;
o STOR - accepts storing from external sources;
o JRNL - journal entries;
o MESG - e-mail messages;
o NOTE - short texts;
o PNFO - presence;
o SGZP - server accepts compression;
o STLS - server can encrypt the communication channel;
o TASK - tasks.
Example:
Radu Expires February 4, 2013 [Page 41]
Internet-Draft AGAP August 2012
C: CAPA
S: .GZIP
S: .TLS
S: .Extension1
S: .Extension.2 argument1
S: .Extension-3 argument1 argument2
S: 200 OK CAPA completed
Figure 45
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
[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 46
Radu Expires February 4, 2013 [Page 42]
Internet-Draft AGAP August 2012
C: SGZP
S: 510 UNKNOWN command
Figure 47
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 48
C: STLS
S: 510 UNKNOWN command
Figure 49
4.10. Command HASH - pre-authenticated state (MD5 and SHA1)
Name: hash
Argument: hash_code
Result: 200 510 511 512
Result 200 - the pair user/hash was successfully authenticated.
Result 510 - unknown/unsupported command.
Radu Expires February 4, 2013 [Page 43]
Internet-Draft AGAP August 2012
Result 511 - invalid hash.
Result 512 - first send USER and then HASH.
Description: Send the hash code associated to the previous
authentication method (MD5 or SHA1), previous USER and provided
prefix.
Examples:
C: AUTH MD5
S: .prefix is-here!
S: 200 OK Send USER
C: USER account
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 200 OK Authenticated
Figure 50
C: USER account
S: 200 OK Send HASH
C: HASH
S: 510 UNKNOWN command
Figure 51
C: USER account
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 511 WRONG user/hash pair
Figure 52
Radu Expires February 4, 2013 [Page 44]
Internet-Draft AGAP August 2012
C: AUTH SHA1
S: .prefix is-here!
S: 200 OK Send USER
C: HASH de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3
S: 512 EXPECTED USER
Figure 53
4.11. Command PASS - 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 54
C: USER account
S: 200 OK Send PASS
C: PASS
S: 510 UNKNOWN command
Figure 55
Radu Expires February 4, 2013 [Page 45]
Internet-Draft AGAP August 2012
C: USER account
S: 200 OK Send PASS
C: PASS password
S: 511 WRONG user/password pair
Figure 56
C: AUTH PLAIN
S: 200 OK AUTH completed
C: PASS password
S: 512 EXPECTED USER
Figure 57
4.12. Command USER - pre-authenticated state (PLAIN, MD5 and SHA1)
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 58
Radu Expires February 4, 2013 [Page 46]
Internet-Draft AGAP August 2012
C: AUTH PLAIN
S: 200 OK Send USER
C: USER
S: 510 UNKNOWN command
Figure 59
C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 511 INVALID username
Figure 60
4.13. Command AACL - authenticated state
Name: add a ACL for selected folder
Arguments: rights account
Result: 200 510 511
Result 200 - the command was successful.
Result 510 - unknown/unsupported command.
Result 511 - the rights are incorrect or the account is missing.
Description: Add a new ACL to the current list of ACLs for selected
folder or replace the old rights if exists an entry for this account.
Examples:
C: AACL ADR *@mydomain.com
S: 200 OK The ACL was successfully added
C: AACL R *@mydomain.com
S: 200 OK The ACL was successfully replaced
Figure 61
Radu Expires February 4, 2013 [Page 47]
Internet-Draft AGAP August 2012
C: AACL
S: 510 UNKNOWN command
Figure 62
C: AACL GR user@domain.com
S: 511 UNKNOWN right G
Figure 63
4.14. Command APBL - authenticated state
Name: set currently selected folder as public folder for its type
Arguments: none
Result: 200 410 510
Result 200 - the command was successful.
Result 410 - for the moment the selected folder cannot be added to
the list of public folders.
Result 510 - unknown/unsupported command.
Description: Add currently selected folder to the list of public
folders.
Note: If there was already set a folder for this type then the
previously folder is removed from the list.
Examples:
C: APBL
S: 200 OK Folder /MyCalendar was made PUBLIC for CALE
Figure 64
Radu Expires February 4, 2013 [Page 48]
Internet-Draft AGAP August 2012
C: APBL
S: 410 Please retry to add it later
Figure 65
C: APBL
S: 510 UNKNOWN command
Figure 66
4.15. Command CHNG - authenticated and not-selected state
Name: report the FCID (Folder Change ID) for all folders
Arguments: path?
Result: 200 510 511
Result 200 - the command was successful.
Result 510 - unknown/unsupported command.
Result 511 - the path is invalid.
Description: Return a list with the FCID of all folders or of the
specified path.
Note: For no path in the list is included and the root folder for all
other folders as slash ('/').
Examples:
Radu Expires February 4, 2013 [Page 49]
Internet-Draft AGAP August 2012
C: CHNG
S: .0BIH /
S: .0009 /Temporary
S: .0001 /Temporary/1980
S: .0BIG /INBOX
S: .0123 /ARCHIVE
S: .0003 /ARCHIVE/2010
S: .0003 /ARCHIVE/2011
S: .00aA /ARCHIVE/2010/OLD
S: 200 OK CHNG completed
C: CHNG /Temporary/1980
S: .0001 /Temporary/1980
S: 200 OK CHNG completed
Figure 67
Note: A change in /ARCHIVE/2010 will change the FCID of /ARCHIVE/
2010, but not the FCID of /ARCHIVE nor /.
C: CHNG
S: 510 UNKNOWN command
Figure 68
C: CHNG /no/path
S: 511 UNKNOWN path
Figure 69
4.16. 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, invalid destination folder or path not
absolute.
Description: Copy an item from the currently selected folder into
another folder (by UID). You cannot copy from a folder having the
Radu Expires February 4, 2013 [Page 50]
Internet-Draft AGAP August 2012
tag NO-COPY or into a folder with the tag READ-ONLY.
Note: For copying a folder the client must use CPYF.
Examples:
C: COPY UIDx1234 /ARCHIVE_FOLDER/TODAY
S: 200 OK COPY completed
Figure 70
C: COPY
S: 510 UNKNOWN command
Figure 71
C: COPY UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: COPY MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination
Figure 72
4.17. Command CPYF - authenticated state
Name: copy folder
Arguments: path_destination_folder
Result: 200 510 511
Result 200 - the copy was successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder, destination is not an
absolute path or destination does not exists.
Description: Copy the content of a folder into another folder.
Note: In the destination folder are copied all non-folder 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 the CPYF command. If the
user wants to copy the folders found in the source then he must to do
Radu Expires February 4, 2013 [Page 51]
Internet-Draft AGAP August 2012
recursively MAKE and CPYF for each subfolder.
Examples (in TODAY are copied only the messages from INBOX):
C: SLCT /INBOX
S: 200 Selected /INBOX
C: CPYF /ARCHIVE_FOLDER/TODAY
S: 200 OK CPYF completed
Figure 73
C: CPYF
S: 510 UNKNOWN command
Figure 74
C: CPYF MISSING
S: 511 INVALID Destination
Figure 75
4.18. Command DACL - authenticated state
Name: delete an ACL from selected folder
Argument: account
Result: 200 220 510 511
Result 200 - the command was successful and the account was removed
from ACL.
Result 220 - the command was successful, but the account was not
found in ACL.
Result 510 - unknown/unsupported command.
Result 511 - the account is missing or incorrect.
Description: Delete an ACL from the currently selected folder ACLs.
Examples:
Radu Expires February 4, 2013 [Page 52]
Internet-Draft AGAP August 2012
C: DACL *@mydomain.com
S: 200 OK The ACL was successfully deleted
Figure 76
C: DACL user@domain.com
S: 220 Entry not found
Figure 77
C: DACL
S: 510 UNKNOWN command
Figure 78
C: DACL @domain.com
S: 511 UNKNOWN entry format
Figure 79
4.19. 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. If the deleted attachment is not the last
one then the remaining attachments are renumbered. There is no
guarantee that an attachment will keep its previous number had before
the successful DATT command.
Note: It cannot be undone.
Examples:
Radu Expires February 4, 2013 [Page 53]
Internet-Draft AGAP August 2012
C: DATT UIDx1234 1
S: 200 OK Attachment deleted
Figure 80
C: DATT
S: 510 UNKNOWN command
Figure 81
C: DATT UIDx1234 1
S: 511 INVALID UID
C: DATT UIDx1234 0
S: 511 INVALID Attachment number
Figure 82
C: DATT UIDx1234 10
S: 521 There are not so many attachments
Figure 83
4.20. 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 an item by uid.
Note: It cannot be undone.
Examples:
Radu Expires February 4, 2013 [Page 54]
Internet-Draft AGAP August 2012
C: DELE UIDx1234
S: 200 OK Message deleted
Figure 84
C: DELE
S: 510 UNKNOWN command
Figure 85
C: DELE 1234
S: 511 INVALID UID
Figure 86
4.21. Command DELF - authenticated state
Name: delete folder
Arguments: none
Result: 200 510 511
Result 200 - the folder was successfully deleted.
Result 510 - unknown/unsupported command.
Result 511 - no folder was selected or currently selected folder is a
reserved folder.
Description: Delete currently selected folder and all its content and
subfolders. A reserved folder cannot be deleted, but a read-only
folder yes. If the operation is successful then after it no folder
is selected.
Note: It cannot be undone.
Examples:
Radu Expires February 4, 2013 [Page 55]
Internet-Draft AGAP August 2012
C: DELF
S: 200 OK Folder '/delete/me' was deleted
Figure 87
C: DELF
S: 510 UNKNOWN command
Figure 88
C: DELF
S: 511 Please select first a folder
C: DELF
S: 511 /INBOX cannot be deleted
Figure 89
4.22. Command DPBL - authenticated state
Name: remove currently selected folder from the list of public
folders
Arguments: none
Result: 200 220 410 510
Result 200 - the command was successful and currently selected folder
was removed from the list of public folders.
Result 220 - the command was successful, but currently selected
folder was not in the list of public folders.
Result 410 - for the moment the selected folder cannot be removed
from the list of public folders.
Result 510 - unknown/unsupported command.
Description: Remove currently selected folder from the list of public
folders (if it is already there).
Examples:
Radu Expires February 4, 2013 [Page 56]
Internet-Draft AGAP August 2012
C: DPBL
S: 200 OK Folder /MyCalendar is no longer public
Figure 90
C: DPBL
S: 220 OK Folder /MyCalendar was not in the list
Figure 91
C: DPBL
S: 410 Please retry to remove it later
Figure 92
C: DPBL
S: 510 UNKNOWN command
Figure 93
4.23. 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 94
4.24. Command FCPY - authenticated state
Name: find and copy entries
Arguments: path_destination_folder filter*
Result: 110 200 210 220 510 511
Radu Expires February 4, 2013 [Page 57]
Internet-Draft AGAP August 2012
Result 110 - the client can send the filter.
Result 200 - the find and copy was successful for all found UIDs.
Result 210 - the find and copy was successful but not for all found
UIDs.
Result 220 - no entry matching the filter was found.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder, wrong filter, or no right to
copy.
Description: Search for items 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. You cannot copy from a folder
having the tag NO-COPY or into a folder with the tag READ-ONLY. If
there is no match for the filter then it is returned a 200 code.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Examples:
C: FCPY /ARCHIVE/SPAM
S: 110 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 95
C: FCPY /ARCHIVE/SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 210 OK FCPY completed (8 from 10 were copied - out of space)
Figure 96
Radu Expires February 4, 2013 [Page 58]
Internet-Draft AGAP August 2012
C: FCPY /ARCHIVE/SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: 220 OK FCPY completed (no matches)
Figure 97
C: FCPY
S: 510 UNKNOWN command
Figure 98
C: FCPY MISSING
S: 511 INVALID folder or path not absolute
C: FCPY SEND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 99
4.25. Command FDEL - authenticated state
Name: find and delete entries
Argument: filter*
Result: 110 200 210 220 511
Result 110 - the client can send the filter.
Result 200 - the find and delete was successful for all found UIDs.
Result 210 - the find and delete was successful but not for all found
UIDs.
Result 220 - no entry matching the filter was found.
Result 511 - wrong filter (inclusive empty filter) or no right to
delete.
Description: Search for items only from the currently selected folder
(no subfolders) that correspond to a filter and delete them (no copy
in TRASH). You cannot delete from a folder having the tag NO-DELETE.
Radu Expires February 4, 2013 [Page 59]
Internet-Draft AGAP August 2012
If there is no match for the filter then it is returned a 200 code.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Examples:
C: FDEL
S: 110 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 100
C: FDEL
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 210 OK FDEL completed (only 8 from 10 matches were deleted)
Figure 101
C: FDEL
S: 110 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: 220 OK FDEL completed (no matches)
Figure 102
C: FDEL
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 103
4.26. Command FIND - authenticated state
Name: find entries
Argument: filter*
Radu Expires February 4, 2013 [Page 60]
Internet-Draft AGAP August 2012
Result: 110 200 220 511
Result 110 - the client can send the filter.
Result 200 - the find was successful.
Result 220 - no entry matching the filter was found.
Result 511 - wrong filter.
Description: Search for items 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. If there is no match for the filter then it
is returned a 220 code.
Note: For not FILT folders, the filter is delivered after the
acceptance of the command. An empty filter matches all items from
that folder.
Examples:
C: SLCT /MESG-Folder
C: FIND
S: 110 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 104
Radu Expires February 4, 2013 [Page 61]
Internet-Draft AGAP August 2012
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: 220 OK FIND completed (no matches)
Figure 105
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 106
4.27. Command FMOV - authenticated state
Name: find and move
Arguments: path_destination_folder filter*
Result: 110 200 210 220 510 511
Result 110 - the client can send the filter.
Result 200 - the find and move was successful for all found UIDs.
Result 210 - the find and move was successful but not for all found
UIDs.
Result 220 - no entry matching the filter was found.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder, wrong filter, or no right to
move.
Description: Search for items 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. You cannot move from a folder
having the tag NO-MOVE or into a folder with the tag READ-ONLY. If
there is no match for the filter then it is returned a 200 code.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Radu Expires February 4, 2013 [Page 62]
Internet-Draft AGAP August 2012
Examples:
C: FMOV /ARCHIVE/SPAM
S: 110 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 107
C: FMOV /ARCHIVE/SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG SPAM
C:
S: 210 OK FMOV completed (8 from 10 moved - out of space)
Figure 108
C: FMOV /ARCHIVE/SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: 220 OK FMOV completed (no matches)
Figure 109
C: FMOV
S: 510 UNKNOWN command
Figure 110
Radu Expires February 4, 2013 [Page 63]
Internet-Draft AGAP August 2012
C: FMOV MISSING
S: 511 INVALID folder or not absolute path
C: FMOV /SEND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 111
4.28. Command FRTR - authenticated state
Name: find entries and retrieve fields
Argument: filter* part*
Result: 110 200 220 511
Result 110 - the client can send the filter and the items parts.
Result 200 - the find was successful.
Result 220 - no entry matching the filter was found.
Result 511 - wrong filter or items parts.
Description: Search for items only from currently selected folder (no
subfolders) that correspond to a filter and return their UIDs
together with the requested parts from them. 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. If there are
no parts specified then only the UIDs are returned. Each requested
part becomes a number starting with 1 and being assigned in the same
order as the fields. It is defined a special part named TAGS which
returns all tags associated to a UID. Each tag is returned on its
own line prefixed with the starting number.
Note: The number 0 is reserved for the UID. 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.
If the item is marked as new then the UID is prefixed with a
multiplication sign (*). The item is then marked as no longer being
new. If there is no match for the filter then it is returned a 220
code.
Note: For not FILT folders, the filter is delivered after the
acceptance of the command. An empty filter matches all items from
Radu Expires February 4, 2013 [Page 64]
Internet-Draft AGAP August 2012
that folder.
Examples: The first message has only a value in To, the second has
two, and the last one none. The second message has no subject.
C: SLCT /MESG-Folder
C: FRTR
S: 110 OK SEND filter&parts definition (end each with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
C: /MESSAGE/HEADER/subject
C: /MESSAGE/HEADER/from
C: /MESSAGE/HEADER/to
C: TAGS
C:
S: .0 UIDx1234
S: .1 Not so important
S: .2 contact@win.com
S: .3 you@example.com
S: .0 *UIDx1235
S: .2 spam@ultimate-spam.com
S: .3 you@example.com
S: .3 your_boss@example.com
S: .0 UIDx2340
S: .1 Please respond
S: .2 office@example.com
S: .4 SEEN
S: .4 EXPIRED=NO
S: 200 OK FRTR completed (3 matches)
C: FRTR
S: 110 OK SEND filter&parts definition (end each with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
C:
S: .0 UIDx1234
S: .0 UIDx1235
S: .0 UIDx2340
S: 200 OK FRTR completed (3 matches)
C: SLCT /FILT-Folder
C: FRTR
S: 110 OK SEND the parts definition (end it with an empty line)
C: /MESSAGE/HEADER/subject
C: /MESSAGE/HEADER/from
C:
S: .0 UIDx1234 /INBOX
S: .1 Please respond
S: .2 office@example.com
Radu Expires February 4, 2013 [Page 65]
Internet-Draft AGAP August 2012
S: .0 UIDx1234 /Trash
S: .1 Very urgent
S: .2 spam@ultimate-spam.com
S: .0 *UIDx1235 /Trash
S: .1 Not so important
S: .2 contact@win.com
S: 200 OK FRTR completed (3 matches)
Figure 112
C: FRTR
S: 110 OK SEND filter&parts definition (end each with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
C: /MESSAGE/HEADER
C:
S: 220 OK FRTR completed (no matches)
Figure 113
C: FRTR
S: 110 OK SEND filter&parts definition (end each with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
C: FRTR
S: 110 OK SEND filter&parts definition (end each with an empty line)
C: UID UIDx0001:UIDx9000
C:
C: INVALID/PATH
C:
S: 511 INVALID part definition
Figure 114
4.29. Command FSTO - storing state
Name: find and write an item into a folder with a specified type from
a certain user
Arguments: FolderType Account
Result: 110 200 410 510 511 541
Result 110 - the requested folder was found and the client can send
the item.
Radu Expires February 4, 2013 [Page 66]
Internet-Draft AGAP August 2012
Result 200 - the item was successfully stored or there was no content
sent by the client.
Result 410 - if the item cannot be stored.
Result 510 - unknown/unsupported command.
Result 511 - invalid folder type, unknown account, the data is not a
valid XML or its schema does not correspond to the type of the
destination folder.
Result 541 - the user does not have enough rights to store the item.
Description: Locate a folder with a specified type in an user account
for receiving items from other users and store there the item sent by
the client. It behaves like STOR.
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: FSTO MESG kontakt@agap.at
S: 110 Send the message ended with an empty line
C: ......
C:
S: 200 OK Message stored with UID UIDx1234 into INBOX
Figure 115
C: FSTO
S: 510 UNKNOWN command
C: FSTO MESG
S: 510 UNKNOWN command
Figure 116
Radu Expires February 4, 2013 [Page 67]
Internet-Draft AGAP August 2012
C: FSTO -1 kontakt@agap.at
S: 511 INVALID folder type
C: FSTO MESG nouser@agap.at
S: 511 UNKNOWN account name
Figure 117
C: FSTO MESG kontakt@agap.at
S: 541 Not enough rights. Please contact your administrator.
Figure 118
4.30. Command FTAG - authenticated state
Name: find and tag entries
Arguments: tag_list filter*
Result: 110 200 210 220 510 511
Result 110 - the client can send the filter.
Result 200 - the find and set of tag(s) was successful for all found
UIDs.
Result 210 - the find and set of tag(s) was successful but not for
all found UIDs.
Result 220 - no entry matching the filter was found.
Result 510 - unknown/unsupported command.
Result 511 - invalid tag list, wrong filter, or no right to tag.
Description: Search for items only from the currently selected folder
(no subfolders) that correspond to a filter and change their tags.
You cannot tag in a folder with the tag READ-ONLY. If there is no
match for the filter then it is returned a 200 code.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Examples:
Radu Expires February 4, 2013 [Page 68]
Internet-Draft AGAP August 2012
C: FTAG + SEEN
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND NEW
C:
S: 200 OK FTAG completed (10 matches)
Figure 119
C: FTAG + SEEN
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND NEW
C:
S: 210 OK FTAG completed (only 8 from 10 matches taged)
Figure 120
C: FTAG + SEEN
S: 110 OK SEND filter definition (end it with an empty line)
C: UID UIDx0001:UIDx9000 TAG SPAM
C:
S: 220 OK FIND completed (no matches)
Figure 121
C: FTAG
S: 510 UNKNOWN command
Figure 122
C: FTAG SEEN
S: 511 INVALID tag list
C: FTAG + SEEN
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 123
4.31. Command GACL - authenticated state
Name: get all ACLs for selected folder
Arguments: none
Radu Expires February 4, 2013 [Page 69]
Internet-Draft AGAP August 2012
Result: 200
Result 200 - the command was successful.
Description: It returns a list with all defined ACLs for currently
selected folder.
Examples:
C: GACL
S: 200 OK No ACL were defined
C: GACL
S: .R anonymous
S: .RAD *@mydomain.com
S: .A partner@extdomain.com
S: 200 OK The ACL list
Figure 124
4.32. Command GFTG - authenticated state
Name: get tags of currently selected folder
Arguments: none
Result: 200 510 511
Result 200 - the tags for UID were successful displayed.
Result 510 - unknown/unsupported command.
Description: Return the tags associated to currently selected folder.
Examples:
C: GFTG
S: .SYNC
S: .HIDDEN=NO
S: 200 OK GFTG completed
Figure 125
Radu Expires February 4, 2013 [Page 70]
Internet-Draft AGAP August 2012
C: GFTG
S: 510 UNKNOWN command
Figure 126
4.33. Command GPBL - authenticated and not-selected state
Name: get the list of public folders
Arguments: none
Results: 200 510
Result 200 - the list was successful delivered (even if it is empty).
Result 510 - unknown command.
Description: Return the list of all folders declared PUBLIC together
with their type.
Note: There should be only one folder for each type.
Examples:
C: GPBL
S: .MESG /INBOX
S: .CALE /CALENDAR
S: .ADDR /Public/CONTACT
S: .FILE /Project X/Public Files
S: .JRNL /JOURNAL
S: .TASK /Project X/Tasks
S: 200 OK GPBL completed
Figure 127
C: GPBL
S: 510 UNKNOWN command
Figure 128
4.34. Command GTAG - authenticated state
Name: get tag of a folder entry
Arguments: UID
Radu Expires February 4, 2013 [Page 71]
Internet-Draft AGAP August 2012
Result: 200 510 511
Result 200 - the tags for UID were successful displayed.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID.
Description: Return the tags associated to an item.
Examples:
C: GTAG UIDx1000
S: .SEEN
S: .SPAM
S: 200 OK GTAG completed
C: GTAG UIDx1001
S: 200 OK GTAG completed
Figure 129
C: GTAG
S: 510 UNKNOWN command
Figure 130
C: GTAG -1
S: 511 INVALID UID
Figure 131
4.35. Command LIST - authenticated and not-selected state
Name: list folders
Arguments: path/filter?
Results: 200 220 511
Result 200 - the list was successful delivered.
Result 220 - the list it is empty.
Result 511 - filter is invalid, the specified path (that has no
wildcard) does not exist, or the specified path before last folder
Radu Expires February 4, 2013 [Page 72]
Internet-Draft AGAP August 2012
name (which has an wildcard) does not exist.
Description: List all folders that correspond to the filter (if it is
provided), otherwise all direct children of currently selected 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 absolute path to the
folder.
Filter's path': 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. Or two stars which must
be the last characters of the filter and means that for each folder
matching the filter are list all their direct and indirect
subfolders. The server can return 511 if it founds '.' or '..' as
folder names or '\' in the filter definition.
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 132
C: LIST /archive*
S: 220 OK LIST completed (0 matches)
Figure 133
Radu Expires February 4, 2013 [Page 73]
Internet-Draft AGAP August 2012
C: LIST */*
S: 511 ERROR path filter can contain only one * in last folder name
C: LIST /ARCHIVE/2000
S: 511 ERROR The specified folder does not exist
C: LIST /ARCHIVE/2000/Documents *.doc
S: 511 ERROR The folder '/ARCHIVE/2000' does not exist
Figure 134
4.36. Command LSTX - authenticated and not-selected state
Name: list folders
Arguments: path/filter?
Results: 200 220 511
Result 200 - the list was successful delivered.
Result 220 - the list it is empty.
Result 511 - filter is invalid, the specified path (that has no
wildcard) does not exist, or the specified path before last folder
name (which has an wildcard) does not exist.
Description: List all folders that correspond to the filter (if it is
provided), otherwise all direct children of currently selected 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 flag indicating some information about that
folder, its FCID (Section 2.6) and ECID (Section 2.7), and the
absolute path to that folder. Between each arguments are exactly
only one white space.
Note: If a folder does not have a ECID, it must to return always the
same value, which must be in a valid UID format.
Filter's path': 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. Or two stars which must
be the last characters of the filter and means that for each folder
matching the filter are list all their direct and indirect
subfolders. The server can return 511 if it founds '.' or '..' as
folder names or '\' in the filter definition.
The flag is a single char and can be only a digit (0-9) or a latin
letter in lower (a-z) or upper case (A-Z) case-sensitive. This
Radu Expires February 4, 2013 [Page 74]
Internet-Draft AGAP August 2012
document defines the following flags:
o 0 - it have no subfolders and no items;
o 1 - it have no subfolders, but it have items;
o 2 - it have subfolders, but no items;
o 3 - it have subfolders and items.
Examples:
C: LSTX
S: .MESG 1 FCIDx012 ECIDx001 YESTERDAY
S: .MESG 3 FCIDx123 ECIDx001 YEAR-2000
S: 200 OK LSTX completed (2 matches)
C: LSTX /*
S: .MESG 2 FCIDx321 ECIDx001 /INBOX
S: .MESG 0 FCIDx001 ECIDx001 /TRASH
S: .CALE 0 FCIDx222 ECIDx001 /CALENDAR
S: 200 OK LSTX completed (3 matches)
C: LSTX YEAR-2010/J*
S: .MESG 1 FCIDx009 ECIDx001 /WORK/YEAR-2010/JUN
S: .MESG 2 FCIDx309 ECIDx001 /WORK/YEAR-2010/JUL
S: 200 OK LSTX completed (2 matches)
Figure 135
C: LSTX /archive*
S: 220 OK LSTX completed (0 matches)
Figure 136
C: LSTX */*
S: 511 ERROR path filter can contain only one * in last folder name
C: LSTX /ARCHIVE/2000
S: 511 ERROR The specified folder does not exist
C: LSTX /ARCHIVE/2000/Documents *.doc
S: 511 ERROR The folder '/ARCHIVE/2000' does not exist
Figure 137
Radu Expires February 4, 2013 [Page 75]
Internet-Draft AGAP August 2012
4.37. Command MAKE - authenticated and not-selected state
Name: make folder
Arguments: 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
o ADDR - it holds contacts;
o CALE - it holds calendar events;
o CONF - it holds user's settings for roaming.
o FILE - it holds normal folders and files;
o FILT - it holds the results of a filter defined by the user (there
can be only one filter per folder);
o FOLD - it contains only subfolders;
o JRNL - it holds a journal;
o NOTE - it holds user's notes;
o MESG - it holds messages;
o TASK - it holds tasks;
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:
Radu Expires February 4, 2013 [Page 76]
Internet-Draft AGAP August 2012
C: MAKE MESG /ARCHIVE/2010
S: 200 OK Folder created
Figure 138
C: MAKE
S: 510 UNKNOWN command
Figure 139
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 140
4.38. 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 an item into another folder (by UID). You cannot
move from a folder having the tag NO-MOVE or into a folder with the
tag READ-ONLY.
Note: For moving a folder the client must use MOVF.
Examples:
Radu Expires February 4, 2013 [Page 77]
Internet-Draft AGAP August 2012
C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 200 OK MOVE completed
Figure 141
C: MOVE
S: 510 UNKNOWN command
Figure 142
C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: MOVE MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination
Figure 143
4.39. Command MOVF - authenticated state
Name: move folder
Arguments: path_destination_folder
Result: 200 510 511
Result 200 - the move was successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder, destination is not an
absolute path or destination does not exists.
Description: Move the content of a folder into another folder.
Note: In the destination folder are moved all non-folder entries
found in the source. 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 the MOVF command. If the
user wants to move the folders found in the source then he must to do
recursively MAKE, MOVF, and DELF for each subfolder.
Examples:
Radu Expires February 4, 2013 [Page 78]
Internet-Draft AGAP August 2012
C: SLCT /INBOX
S: 200 Selected /INBOX
C: MOVF /ARCHIVE_FOLDER/TODAY
S: 200 OK MOVF completed
Figure 144
C: MOVF
S: 510 UNKNOWN command
Figure 145
C: MOVF MISSING
S: 511 INVALID destination
Figure 146
4.40. Command NAME - authenticated state
Name: rename folder
Arguments: new_name
Results: 200 510 511
Result 200 - the rename was successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid new_name or trying to rename a reserved folder
name.
Description: Rename a folder. The currently selected folder remains
selected even if the name was changed. A reserved folder cannot be
renamed.
Note: The new_name does not hold any path hierarchy.
Examples:
Radu Expires February 4, 2013 [Page 79]
Internet-Draft AGAP August 2012
C: SLCT /ARCHIVE/2001
S: 200 OK
C: NAME OLD-2001
S: 200 OK NAME completed
Figure 147
C: NAME
S: 510 UNKNOWN command
Figure 148
C: SLCT /INBOX
S: 200 OK
C: NAME InBox
S: 511 ERROR The folder cannot be renamed (reserved name)
C: NAME /A/new-folder
S: 511 ERROR The argument must not be a path
Figure 149
4.41. 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 150
4.42. Command PGET - authenticated, not-selected and presence state
Name: fetch presence information
Arguments: USER user|BUSY user|FREE user
Radu Expires February 4, 2013 [Page 80]
Internet-Draft AGAP August 2012
Result: 110 200 510 511
Result 110 - the client can send the list of timestamps and
locations.
Result 200 - the presence information for the user were found and
returned.
Result 510 - unknown/unsupported command.
Result 511 - unknown/unsupported/missing arguments.
Description: Fetch information about an user current availability or
checks when an user is busy or free.
Note: If there is present an argument USER then the user wants to
obtain information about the status of an other user or himself. If
the server does not know how to obtain the information about this
user then it returns an UNKNOWN as argument. Otherways can return a
list with all set texts. After an HERE and AWAY is present when was
this set, for an IDLE is the timestamp corresponding to the starting
point of idle period. In answer can be present only one of these
three. For a PSET FOR is returned an HERE for a PGET USER.
Note: If there is present an argument BUSY or FREE then it is
expected a list with timestamp periods and locations for which to be
returned the list of busy, respectively free time frames. The end of
list is marked by sending an empty line to server. Each list line
has three fields: a start and inclusive end timestamp and a location.
Between each argument is exactly only one space character (0x20). A
timestamp has the format: YYYY-MM-DD hh:mm:ss and represents the time
in UTC. The meaning of the timestamp fields could be found in Date
and Time on the Internet: Timestamps [RFC3339]. A location is a
string or the star character (*) for matching any location. The
command returns a list with all available busy or free time frames
for specified period and location. If there cannot be found any busy
or free time frame then no list is returned, but only a 200 return
code. The location name is compared which what was stored by the
user, so there someone can write Vienna and someone else Wien, so the
two of them cannot be found with a list having only one line and
specifing a location. The answer is made of pairs of start and
inclusive end timestamps.
Examples:
Radu Expires February 4, 2013 [Page 81]
Internet-Draft AGAP August 2012
C: PGET USER user@example.com
S: .IDLE 2011-05-27 18:00:00 +1000
S: .STATUS Today I am doing HomeOffice
S: .AT Headquarter, 1010 Vienna, Austria
S: 200 OK USER found
C: PGET USER user2@example.com
S: .HERE 2011-05-27 18:00:00 +1000
S: .STATUS Today I am in Austria
S: .AT Headquarter, 1010 Vienna, Austria
S: 200 OK USER found
C: PGET USER user3@example.com
S: .AWAY 2011-05-27 18:00:00 +1000
S: 200 OK USER found
C: PGET USER user@domain.com
S: .UNKNOWN
S: 200 OK USER not found
C: PGET USER user@domain.com
S: .UNKNOWN
S: 200 OK USER not found
C: PGET BUSY user@domain.com
S: 110 Send the message ended with an empty line
C: 2012-01-01 09:00:00 2012-01-03 17:30:00 Vienna/AT
C: 2012-01-01 09:00:00 2012-01-03 17:30:00 Wien
C:
S: .2012-01-01 10:00:00 2012-01-02 23:59:59 Wien
S: .2012-01-03 14:00:00 2012-01-03 16:30:00 Wien
S: 200 OK 2 BUSY time frames found
C: PGET FREE user@domain.com
S: 110 Send the message ended with an empty line
C: 2012-01-01 09:00:00 2012-01-03 17:30:00 Vienna/AT
C: 2012-01-01 09:00:00 2012-01-03 17:30:00 Wien
C:
S: .2012-01-01 09:00:00 2012-01-01 09:59:59 Wien
S: .2012-01-03 00:00:00 2012-01-03 13:59:59 Wien
S: .2012-01-03 16:30:01 2012-01-03 17:30:00 Wien
S: 200 OK 3 FREE time frames found
Figure 151
Radu Expires February 4, 2013 [Page 82]
Internet-Draft AGAP August 2012
C: PGET USER user@domain.com
S: 510 Presence is not supported
Figure 152
C: PGET
S: 511 Missing argument
C: PGET WRONG
S: 511 UNKNOWN argument WRONG
C: PGET USER
S: 511 Missing argument
Figure 153
4.43. Command PSET - authenticated and not-selected state
Name: announce presence
Arguments: HERE|AWAY|FOR number unit_of_time|IDLE number
unit_of_time|STATUS text|AT text
Result: 200 510 511
Result 200 - the presence of the user was updated or requested
information returned.
Result 510 - unknown/unsupported command.
Result 511 - unknown/unsupported/missing arguments.
Description: Announce that the logged user is still online,
eventually since when is idle. A QUIT command or disconnection means
that the user is no longer online. In state PRESENCE only the "USER
user" arguments are accepted.
If there is present an argument HERE then that means the user is no
longer idle. As there is no information for how long this status is
valid, then it will remain valid until comes a new command which
change it.
If there is present an argument AWAY then that means the user is no
longer connected. As there is no information for how long this
status is valid, then it will remain valid until comes a new command
which change it.
If there is present an argument FOR then that means the user is
suppose to be considered present for the given amount of time. The
Radu Expires February 4, 2013 [Page 83]
Internet-Draft AGAP August 2012
client is expected to send its updated status in this period. If
comes no command to change the state in the specified time, then
after this period the presence will be reported as unknown. The
arguments are as by IDLE.
If there is present an argument IDLE then that means the user is idle
and the arguments must be: IDLE number unit_of_time. The number must
be a positive number and the unit_of_time must be one of the
following: sec, min, hour, day, year. As there is no information for
how long this status is valid, then it will remain valid until comes
a new command which change it.
If there is present an argument STATUS then the user want to change
the text that is associated with its presence online. After STATUS
can follow any text. The text ends to the end of line. If there is
no text then any previous text is deleted and no text is displayed as
status text.
If there is present an argument AT then that user want to change the
text that is associated with its present location. After AT can
follow any text. The text ends to the end of line. If there is no
text then any previous text is deleted and no text is displayed as
location text.
Examples:
C: PSET HERE
S: 200 OK You are online and not idle
C: PSET AWAY
S: 200 OK You are no more online
C: PSET FOR 5 min
S: 200 OK You are now online. Expecting an update in 5 minutes.
C: PSET IDLE 5 min
S: 200 OK You are idle since 5 minutes
C: PSET STATUS Today I am doing HomeOffice
S: 200 OK You changed your status text
C: PSET AT Headquarter, 1010 Vienna, Austria
S: 200 OK You changed your location text
Figure 154
Radu Expires February 4, 2013 [Page 84]
Internet-Draft AGAP August 2012
C: PSET HERE
S: 510 Unknown command
Figure 155
C: PSET
S: 511 Missing argument
C: PSET WRONG
S: 511 UNKNOWN argument WRONG
C: PSET AT
S: 511 Missing argument
Figure 156
4.44. Command RETC - authenticated state (MESG folder type)
Name: retrieve
Argument: UID
Results: 200 510 511
Result 200 - the message was found.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID or folder is not of type MESG.
Description: Fetch from server the message with the given UID. Each
line of answer is prefixed with a dot that it is not part of the
returned object. RETC returns for an attachment its name and size in
bytes instead of its content as RETR.
Examples:
Radu Expires February 4, 2013 [Page 85]
Internet-Draft AGAP August 2012
C: RETC UIDx1234
S: ....
S: .
S: .cid:A12
S: .123456
S: .
S: .
S: 200 OK RETR completed
Figure 157
C: RETC
S: 510 UNKNOWN command
Figure 158
C: RETC WrongUID
S: 511 INVALID UID
C: RETC UIDx1234
S: 511 RETC is allowed only for MESG folders
Figure 159
4.45. 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 item was found or filter content was delivered.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID or part name.
Description: Fetch from server the item with the given UID. For a
filter folder, it must be called without an UID 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 PATH in the response as it is returned by RETR or RETC
and must point to an end leaf. It contains only tag names separated
Radu Expires February 4, 2013 [Page 86]
Internet-Draft AGAP August 2012
with /. Example: /MESSAGE/HEADER/subject, /MESSAGE/HEADER/received,
/MESSAGE/HTML, /MESSAGE/ATTACHMENT-1/BODY. For an entry in the
header with a multivalue are returned each value on its own line.
For values which are lists with values delimited by comma or semi-
colon it is possible to extract an item using: for lists delimited by
comma square brackets ([]) and for lists delimited by semi-colons
curly brackets ({}).
Examples:
C: RETR UIDx1234
S: .......
S: 200 OK RETR completed
C: RETR UIDx1234 /MESSAGE/HEADER/subject
S: .Message's subject
S: 200 OK RETR completed
C: RETR UIDx1234 /MESSAGE/HEADER/received
S: .from s0001.srv.example.com [10.11.12.13] by mx.example.com
S: . (Postfix) with ESMTP id 01234567890 for ;
S: . Thu, 19 Nov 2009 01\:02\:03 +0100 (CET)
S: . by userpc (192.168.192.168) id 20091119010204A;
S: . Thu, 19 Nov 2009 01\:02\:04 +0100 (CET)
S: 200 OK RETR completed
C: RETR
S: .
S: ./Spam
S: .
S: .
S: 200 OK RETR completed
Figure 160
C: RETR
S: 510 UNKNOWN command (only FILT folders do not needs arguments)
Figure 161
Radu Expires February 4, 2013 [Page 87]
Internet-Draft AGAP August 2012
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 162
4.46. Command SFTG - authenticated state
Name: set the tags of currently selected folder
Arguments: tag_list
Result: 200 210 410 510 511 541
Result 200 - all tags for current folder were successful set.
Result 210 - not all tags for current folder were successful set.
Result 410 - for the moment the flags cannot be saved.
Result 510 - unknown/unsupported command.
Result 511 - invalid tag list.
Result 541 - the tag FIX-TAGS does not allow to change the already
set tags.
Description: Set or delete tags of currently selected folder.
Note: Setting the tag FIX-TAGS makes the tags of currently selected
folder unchangable after this command. The tags can only be changed
on the server.
Note: A return code 210 is returned even when no flag could be set if
the tag list is correct.
Examples:
Radu Expires February 4, 2013 [Page 88]
Internet-Draft AGAP August 2012
C: SFTG + SYNC
S: 200 OK SFTG completed
Figure 163
C: SFTG - SYNC TEST
S: 210 OK SFTG did not removed TEST
C: SFTG - TEST
S: 210 OK SFTG did not removed TEST
Figure 164
C: SFTG + SYNC
S: 410 Please retry to set them later
Figure 165
C: SFTG
S: 510 UNKNOWN command
C: SFTG + SYNC
S: 510 Please select a folder first
Figure 166
C: SFTG SYNC
S: 511 INVALID tag list
Figure 167
C: SFTG + SYNC
S: 541 Tag FIX-TAGS prevents the change of tags
Figure 168
4.47. Command SLCT - authenticated and not-selected state
Name: select a folder
Argument: path
Result: 200 510 511
Result 200 - the folder was successfully selected.
Radu Expires February 4, 2013 [Page 89]
Internet-Draft AGAP August 2012
Result 510 - unknown/unsupported command.
Result 511 - unknown path or '/'.
Description: Select a folder. If the selection was not successful
then no folder remains selected and the server switch in the 'Not-
selected State'. The user cannot select the root (/) folder.
Examples:
C: SLCT /INBOX
S: 200 OK Folder selected
C: SLCT ARCHIVE/2000
S: 200 OK Folder selected
Figure 169
C: SLCT
S: 510 UNKNOWN command
Figure 170
C: SLCT 1234
S: 511 INVALID folder
C: SLCT /
S: 511 You cannot select /
Figure 171
4.48. Command STAG - authenticated state
Name: set tags of entries
Arguments: UID tag_list
Result: 200 410 510 511
Result 200 - the tags for UID were successful set.
Result 410 - for the moment the flags cannot be saved.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID.
Radu Expires February 4, 2013 [Page 90]
Internet-Draft AGAP August 2012
Description: Set or delete tags associated to an item.
Examples:
C: STAG UIDx1000 + SEEN SYNC DAY=2012
S: 200 OK STAG completed
Figure 172
C: STAG UIDx1000 + SEEN SYNC DAY=2012
S: 410 Please retry to set them later
Figure 173
C: STAG
S: 510 UNKNOWN command
Figure 174
C: STAG -1
S: 511 INVALID UID
C: STAG 0x1 + SEEN
S: 511 UID not found
C: STAG UIDx1234 SEEN
S: 511 INVALID tag list (missing operator)
Figure 175
4.49. 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), its FCID, its ECID (only for folders
with can hold items), the tags (TAGS) and eventually additional
information associated with this type of folder. A change in a
Radu Expires February 4, 2013 [Page 91]
Internet-Draft AGAP August 2012
folder means that its structure was changed or there was a change of
its items (like new messages, an event was canceled and automatically
removed from a calender).
Additional information:
o ADDR - TOTAL;
o CALE - TOTAL;
o CONF - TOTAL.
o FILE - TOTAL;
o FILT - TOTAL;
o FOLD - none;
o JRNL - TOTAL;
o MESG - TOTAL and NEW;
o NOTE - TOTAL;
o TASK - TOTAL;
Examples:
C: STAT
S: .PATH /INBOX
S: .TYPE MESG
S: .FCID 1
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 2
S: 200 OK Folder status displayed
Figure 176
Radu Expires February 4, 2013 [Page 92]
Internet-Draft AGAP August 2012
C: STAT
S: 512 ERROR First select a folder
Figure 177
4.50. Command STOR - authenticated state
Name: store
Arguments: none
Result: 110 200 410 511
Result 110 - the client can send the item.
Result 200 - the item was successfully stored or there was no content
sent by the client.
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 item/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). The server can
send a 410 or 511 respons before the empty line is send, so the
client must check after each sended line of content if the server had
rejected the content.
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:
Radu Expires February 4, 2013 [Page 93]
Internet-Draft AGAP August 2012
C: STOR
S: 110 Send the message ended with an empty line
C: ......
C:
S: 200 OK Message stored (UID is UIDx1234)
C: STOR
S: 110 Send the message ended with an empty line
C:
S: 200 OK Message not stored as it was empty
Figure 178
C: STOR
S: 110 Send the message ended with an empty line
C: ......
C:
S: 410 Cannot store it, not enough space
Figure 179
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 180
4.51. Command SUID - authenticated state
Name: last UID returned by STOR
Arguments: none
Results: 200 511
Result 200 - the command was accepted and eventually an UID was
returned.
Result 511 - the command is not accepted in the actual state.
Description: This command returns the last UID generated by a STOR
command in the currently selected folder since it was last time
selected. Selecting an other folder or leaving the actual state
makes to forget last generated UID. By selecting a folder, storing
an item and then reselecting the same folder makes the UID to be
Radu Expires February 4, 2013 [Page 94]
Internet-Draft AGAP August 2012
forgot. If there is no UID stored then is returned a 200 without any
line holding an UID. A failling STOR also makes no UID to be
remembered.
Examples:
C: SLCT /Mbox
S: 200 Selected /Mbox
C: SUID
S: 200 OK There was no STOR since last SLCT
C: STOR
...
S: 200 OK STOR completed with UID UIDx1234
C: SUID
S: .UIDx1234
S: 200 OK SUID completed; found UIDx1234
C: SLCT /Mbox
S: 200 Selected /Mbox
C: SUID
S: 200 OK There was no STOR since last SLCT
C: STOR
...
S: 511 ERROR STOR ompleted with error
C: SUID
S: 200 OK There was no successfull STOR since last SLCT
Figure 181
C: SUID
S: 511 ERROR SUID is not accepted in this state
Figure 182
5. Responses
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
Radu Expires February 4, 2013 [Page 95]
Internet-Draft AGAP August 2012
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:
o 1xx: Informational - Server waits for request continuation or send
unrequested data;
o 2xx: Success - The action was successfully executed;
o 4xx: Server Error - The server failed to perform the request,
retry later;
o 5xx: Server Error - The server failed to perform the request,
permanent error;
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 (.).
5.2. 1xx Informational
5.2.1. 100 Reserved
Reserved.
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.
5.3. 2xx Success
5.3.1. 200 OK
The request was successfully processed.
5.3.2. 210 Partial OK
The request was successfully applied for at least one item but not
for all requested items. (see FCPY, FDEL, FMOV, and FTAG)
Radu Expires February 4, 2013 [Page 96]
Internet-Draft AGAP August 2012
5.3.3. 220 Nothing to do
The request was successful, but none of the arguments were found.
(see DACl, DPBL)
5.4. 4xx Temporary Server Error
5.4.1. 400 Reserved
Reserved.
5.4.2. 401 Internal Error
The request could not be processed because it was an internal error
(ex.: something is wrong configured).
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).
5.5. 5xx Permanent Server Error
5.5.1. 500 Reserved
Reserved.
5.5.2. 510 Unknown Command
The request could not be processed because this command is unknown or
its syntax is wrong.
5.5.3. 511 Invalid Parameter Format
The request could not be processed because the command has an invalid
parameter.
This answer can be returned even in the case when more than one 0x20
character were present between command and its arguments or between
arguments.
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.)
Radu Expires February 4, 2013 [Page 97]
Internet-Draft AGAP August 2012
5.5.5. 521 Not found
This command has a valid syntax but the searched argument does not
exist or cannot be accessed. (Ex.: DATT did not found the attachment
to delete.)
5.5.6. 531 Banned
The client is not allowed to interact with the server. (Ex.: the
client's IP is blacklisted.)
5.5.7. 541 Not enough rights
The client is not allowed to do the command because of insufficient
rights. If it had enough rights then the command would have been
successful. (Ex.: the client cannot store a message with FSTO.)
6. All Possible Response Codes for All Commands
6.1. Not-authenticated State
The Welcome Message: 200 401 410 531
AUTH: 510 511
AUTH mechanism: 200 511
CAPA: 200
QUIT: 200
SGZP: 200 510
STLS: 200 510
other: 510
6.2. Pre-authenticating State (PLAIN method)
PASS: 510 511 512
PASS password: 200 511 512
QUIT: 200
USER: 510 511
Radu Expires February 4, 2013 [Page 98]
Internet-Draft AGAP August 2012
USER account: 200 511
other: 510
6.3. Pre-authenticating State (MD5 and SHA1 methods)
HASH: 510 511 512
HASH hashcode: 200 511 512
QUIT: 200
USER: 510 511
USER account: 200 511
other: 510
6.4. Authenticated State
AACL: 510
AACL arguments: 200 511
APBL: 200 410
CHNG: 200 510
CHNG arguments: 200 511
COPY: 510 511
COPY arguments: 200 511
CPYF: 510 511
CPYF arguments: 200 511
DACL: 510
DACL arguments: 200 220 511
DATT: 510 511
DATT arguments: 200 511 521
DPBL: 200 220 410
Radu Expires February 4, 2013 [Page 99]
Internet-Draft AGAP August 2012
DELE: 510 511
DELE arguments: 200 511
DELF: 510 511
DELF arguments: 200 511
EXIT: 200
FCPY: 110
FCPY arguments: 200 210 220 511
FDEL: 110
FDEL arguments: 200 210 220 511
FIND: 110
FIND arguments: 200 220 511
FMOV: 110
FMOV arguments: 200 210 511
FRTR: 110
FRTR arguments: 200 220 511
FTAG: 510
FTAG arguments: 110 200 210 220 511
GACL: 200
GFTG: 200
GPBL: 200
GTAG: 510
GTAG arguments: 200 511
LIST: 200 220
LIST arguments: 200 220 511
Radu Expires February 4, 2013 [Page 100]
Internet-Draft AGAP August 2012
LSTX: 200 220
LSTX arguments: 200 220 511
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
PGET: 510 511
PGET arguments: 110 200 510 511
PSET: 510 511
PSET arguments: 200 510 511
QUIT: 200
RETC: 510
RETC arguments: 200 511
RETR: 510 511
RETR arguments: 200 511
SLCT: 510 511
SLCT arguments: 200 511
SFTG: 510 511
SFTG arguments: 200 410 511 541
Radu Expires February 4, 2013 [Page 101]
Internet-Draft AGAP August 2012
STAG: 510 511
STAG arguments: 200 410 511
STAT: 200 512
STOR: 110 200 410 511
SUID: 200 511
other: 510
6.5. Not-selected State
CHNG: 200 510
CHNG arguments: 200 511
GPBL: 200
LIST: 200
LIST arguments: 200 511
PSET: 510 511
PSET arguments: 200 510 511
SLCT: 510 511
SLCT arguments: 200 511
other: 510
6.6. Presence State
PGET: 510 511
PGET arguments: 200 510 511
QUIT: 200
other: 510
6.7. Storing State
FSTO: 510
Radu Expires February 4, 2013 [Page 102]
Internet-Draft AGAP August 2012
FSTO arguments: 110 200 410 510 511 541
QUIT: 200
other: 510
7. Example of Conversations
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 MESG
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 2
S: 200 OK Folder status displayed
Figure 183
Radu Expires February 4, 2013 [Page 103]
Internet-Draft AGAP August 2012
S: 200 Welcome
C: AUTH MD5
S: .Use this as prefix, please!
S: 200 OK Send USER
C: USER account
S: 200 OK Send HASH
C: HASH 79054025255fb1a26e4bc422aef54eb1
S: 200 OK Authenticated
C: STAT
S: .PATH /INBOX
S: .TYPE MESG
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 2
S: 200 OK Folder status displayed
Figure 184
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 185
7.3. Connection refused
S: 531 Your IP is blacklisted
Figure 186
S: 410 Too many connections, please retry later
Figure 187
Radu Expires February 4, 2013 [Page 104]
Internet-Draft AGAP August 2012
S: 401 Internal error, the server has an error in its configuration
Figure 188
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 189
7.5. Find all entries available in a folder
C: SLCT /INBOX
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C:
S: .UIDx1230
S: .UIDx1231
S: .UIDx1234
S: .UIDx1235
S: .UIDx2340
S: 200 OK FIND completed (5 matches)
Figure 190
7.6. Retrieve a message
Radu Expires February 4, 2013 [Page 105]
Internet-Draft AGAP August 2012
C: SLCT /INBOX
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: NEW 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: .
S: .HCCP<news@example.com>
S: .newsletter@localhost.localdomain
S: .Newsletter from Example.com
S: .
S: .This is your weekly newsletter.
S: .
S: 200 OK RETR completed
Figure 191
7.7. Retrieve a contact
Radu Expires February 4, 2013 [Page 106]
Internet-Draft AGAP August 2012
C: SLCT /CONTACT
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: OR REGEX /VCARD/FN = 'RADU.*?'
C: REGEX /VCARD/FN = '.*? Iulian'
C:
S: .CONx0001
S: 200 OK FIND completed (1 match)
C: RETR CONx0001
S: .
S: . 3.0
S: . Iulian Radu
S: . Radu;Iulian;;Dipl.Ing.;
S: . Example Com;European Division
S: . iulian.radu@gmx.at
S: . +01:00
S: . 2011-05-31T18:46:00Z
S: .
S: 200 OK RETR completed
Figure 192
7.8. Retrieve an event
Radu Expires February 4, 2013 [Page 107]
Internet-Draft AGAP August 2012
C: SLCT /CALENDAR
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: IS /VEVENT/SUMMARY = '*RFC*'
C:
S: .EVNx0001
S: 200 OK FIND completed (1 match)
C: RETR EVNx0001
S: .
S: . 20110531T114600Z-123456@agap.at
S: . 2011-05-31T12:10:00Z
S: . 2011-06-07T18:00:00Z
S: . 2011-06-07T24:00:00Z
S: . AGAP RFC Party
S: . Celebration of a new revision!
S: .0.4
S: .
S: . 20110607T170000Z-20110531T114600Z-123456@agap.at
S: .
S: 200 OK RETR completed
Figure 193
7.9. Store a message
C: SLCT /OUTBOX
S: 200 OK Folder selected
C: STOR
S: 110 Send the message ended with an empty line
C:
C: HCCP<news@example.com>
C: newsletter@localhost.localdomain
C: HCCP Newsletter
C:
C: This is your weekly newsletter.
C:
C:
S: 200 OK Message stored (UID is UIDx1234)
Figure 194
7.10. Store a contact
Radu Expires February 4, 2013 [Page 108]
Internet-Draft AGAP August 2012
C: SLCT /CONTACT
S: 200 OK Folder selected
C: STOR
S: 110 Send the contact info ended with an empty line
C:
C: 3.0
C: Iulian Radu
C: Radu;Iulian;;Dipl.Ing.;
C: Example Com;European Division
C: iulian.radu@gmx.at
C: +01:00
C: 2011-05-31T18:46:00Z
C:
C:
S: 200 OK Contact stored (UID is UIDx1234)
Figure 195
7.11. 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:
C: 20110531T114600Z-123456@agap.at
C: 2011-05-31T12:10:00Z
C: 2011-06-07T18:00:00Z
C: 2011-06-07T24:00:00Z
C: AGAP RFC Party
C: Celebration of a new revision!
C: 0.4
C:
C: 20110607T170000Z-20110531T114600Z-123456@agap.at
C:
C:
S: 200 OK Event stored (UID is UIDx1234)
Figure 196
7.12. Mark messages as SPAM an move them in a new folder
Radu Expires February 4, 2013 [Page 109]
Internet-Draft AGAP August 2012
C: STAG UIDx1000 + SPAM
S: 200 OK STAG completed
C: MAKE MESG /Archive-SPAM
S: 200 OK Folder created
C: FMOV /Archive-SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: TAG SPAM
C:
S: 200 OK FMOV completed (19 matches)
Figure 197
7.13. 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:
C: /INBOX
C:
C: SEEN
C:
C:
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: .
S: ./INBOX
S: .SEEN
S: .
S: 200 OK RETR completed
Figure 198
Radu Expires February 4, 2013 [Page 110]
Internet-Draft AGAP August 2012
7.14. Create a folder and rename it
C: MAKE MESG /My/NewFolder
S: 200 OK Folder created
C: NOOP
S: 200 NOOP OK
C: SLCT /My/NewFolder
S: 200 OK Selected /My/NewFolder
C: NAME AFolder
S: 200 OK /My/NewFolder --> /My/AFolder
Figure 199
7.15. 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 MESG
S: .TAGS RESERVED
S: .TOTAL 10
S: .NEW 5
S: 200 OK Folder status displayed
Figure 200
7.16. Set and check the tags of a message
Radu Expires February 4, 2013 [Page 111]
Internet-Draft AGAP August 2012
C: STAG UIDx1000 + SEEN
S: 200 OK STAG completed
C: GTAG UIDx1000
S: .SPAM
S: .FLAG=RED
S: .SEEN
S: 200 OK GTAG completed
Figure 201
7.17. Find messages that can be SPAM and delete them
C: FTAG + SPAM
S: 110 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: 110 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 202
7.18. Connect for a short period
C: PSET FOR 15 min
S: 200 Nice to se you back
C: PSET AT At Home
S: 200 So you are there
C: PSET STATUS Today I am doing HomeOffice
S: 200 So kind to share your thoughts with us
C: PGET USER coworker
S: .AWAY 2011-05-27 18:00:00 +1000
S: 200 Sorry, your buddy is not here
C: PSET AWAY
S: 200 Oh, so soon
Figure 203
8. References
Radu Expires February 4, 2013 [Page 112]
Internet-Draft AGAP August 2012
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552,
July 2003.
8.2. Informative References
[ISO.8601.1988]
International Organization for Standardization, "Data
elements and interchange formats - Information interchange
- Representation of dates and times", ISO Standard 8601,
June 1988.
[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.
[RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
RFC 2426, September 1998.
[RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
April 2001.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3921] Saint-Andre, P., Ed., "Extensible Messaging and Presence
Protocol (XMPP): Instant Messaging and Presence",
RFC 3921, October 2004.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
Radu Expires February 4, 2013 [Page 113]
Internet-Draft AGAP August 2012
Author's Address
Iulian Radu (editor)
Email: iulian.radu@gmx.at
Radu Expires February 4, 2013 [Page 114]