Internet Engineering Task Force I. Radu, Ed.
Internet-Draft May 9, 2011
Intended status: Informational
Expires: November 10, 2011
Advanced Groupware Access Protocol
draft-iulian-advanced-groupware-access-protocol-03
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 November 10, 2011 [Page 1]
Internet-Draft AGAP May 2011
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 10, 2011.
Copyright Notice
Copyright (c) 2011 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 November 10, 2011 [Page 2]
Internet-Draft AGAP May 2011
Table of Contents
1. How to Read This Document . . . . . . . . . . . . . . . . 6
1.1. Organization of This Document . . . . . . . . . . . . . . 6
1.2. Conventions Used in This Document . . . . . . . . . . . . 6
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 6
2.1. Charset Used for Commands and Responses . . . . . . . . . 6
2.2. Maximal Length of a Command or Response Line . . . . . . . 7
2.3. Numbers in Commands and Responses . . . . . . . . . . . . 7
2.4. Regular Expressions in Commands . . . . . . . . . . . . . 7
2.5. Unique Identification Numbers . . . . . . . . . . . . . . 9
2.6. Folders . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.6.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.6.2. Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . 9
2.6.3. Folder Types . . . . . . . . . . . . . . . . . . . . . . . 10
2.6.4. Reserved Folders . . . . . . . . . . . . . . . . . . . . . 10
2.7. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.7.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.7.2. Reserved Tag Names . . . . . . . . . . . . . . . . . . . . 12
2.8. The Responses for Each Type of Folder . . . . . . . . . . 13
2.8.1. Format and Conventions . . . . . . . . . . . . . . . . . . 13
2.8.2. Response for Calendar Folders . . . . . . . . . . . . . . 13
2.8.3. Response for Configuration Folders . . . . . . . . . . . . 15
2.8.4. Response for Contact Folders . . . . . . . . . . . . . . . 16
2.8.5. Response for File Folders . . . . . . . . . . . . . . . . 17
2.8.6. Response for Filter Folders . . . . . . . . . . . . . . . 18
2.8.7. Response for Journal Folders . . . . . . . . . . . . . . . 18
2.8.8. Response for Message Folders . . . . . . . . . . . . . . . 19
2.8.9. Response for Note Folders . . . . . . . . . . . . . . . . 22
2.8.10. Response for Task Folders . . . . . . . . . . . . . . . . 22
3. States . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1. Not-authenticated State . . . . . . . . . . . . . . . . . 23
3.2. Pre-authentication State . . . . . . . . . . . . . . . . . 24
3.3. Authenticated (and Selected) State . . . . . . . . . . . . 24
3.4. (Authenticated but) Not-selected State . . . . . . . . . . 25
4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.1. Semantic and Syntax . . . . . . . . . . . . . . . . . . . 25
4.2. Syntax of a Tag List . . . . . . . . . . . . . . . . . . . 25
4.3. Syntax of a Filter . . . . . . . . . . . . . . . . . . . . 26
4.3.1. Syntax of a Filter for a Command . . . . . . . . . . . . . 26
4.3.2. Syntax of a Filter for a FILT Folder . . . . . . . . . . . 28
4.4. The Welcome Message - not-authenticated state . . . . . . 30
4.5. Command QUIT - all states . . . . . . . . . . . . . . . . 31
4.6. Command AUTH mechanism - not-authenticated state . . . . . 31
4.7. Command CAPA - not-authenticated state . . . . . . . . . . 32
4.8. Command SGZP - not-authenticated state . . . . . . . . . . 33
4.9. Command STLS - not-authenticated state . . . . . . . . . . 33
4.10. Command PASS password - pre-authenticated state (PLAIN) . 34
Radu Expires November 10, 2011 [Page 3]
Internet-Draft AGAP May 2011
4.11. Command USER account - pre-authenticated state (PLAIN) . . 35
4.12. Command CHNG - authenticated state . . . . . . . . . . . . 36
4.13. Command COPY - authenticated state . . . . . . . . . . . . 38
4.14. Command CPYF - authenticated state . . . . . . . . . . . . 39
4.15. Command DATT - authenticated state (MESG folder type) . . 40
4.16. Command DELE - authenticated state . . . . . . . . . . . . 41
4.17. Command DELF - authenticated state . . . . . . . . . . . . 42
4.18. Command EXIT - authenticated state . . . . . . . . . . . . 43
4.19. Command FCPY - authenticated state . . . . . . . . . . . . 43
4.20. Command FDEL - authenticated state . . . . . . . . . . . . 44
4.21. Command FIND - authenticated state . . . . . . . . . . . . 45
4.22. Command FMOV - authenticated state . . . . . . . . . . . . 46
4.23. Command FTAG - authenticated state . . . . . . . . . . . . 47
4.24. Command GTAG - authenticated state . . . . . . . . . . . . 48
4.25. Command LIST - authenticated and not-selected state . . . 49
4.26. Command MAKE - authenticated and not-selected state . . . 50
4.27. Command MOVE - authenticated state . . . . . . . . . . . . 52
4.28. Command MOVF - authenticated state . . . . . . . . . . . . 53
4.29. Command NAME - authenticated state . . . . . . . . . . . . 54
4.30. Command NOOP - authenticated state . . . . . . . . . . . . 55
4.31. Command RETR - authenticated state . . . . . . . . . . . . 55
4.32. Command SLCT - authenticated and not-selected state . . . 57
4.33. Command SPAM - authenticated state (MESG folder type) . . 58
4.34. Command STAG - authenticated state . . . . . . . . . . . . 59
4.35. Command STAT - authenticated state . . . . . . . . . . . . 60
4.36. Command STOR - authenticated state . . . . . . . . . . . . 61
5. Responses . . . . . . . . . . . . . . . . . . . . . . . . 63
5.1. Semantic and Syntax . . . . . . . . . . . . . . . . . . . 63
5.2. 1xx Informational . . . . . . . . . . . . . . . . . . . . 63
5.2.1. 100 Reserved . . . . . . . . . . . . . . . . . . . . . . . 64
5.2.2. 110 Continue . . . . . . . . . . . . . . . . . . . . . . . 64
5.3. 2xx Success . . . . . . . . . . . . . . . . . . . . . . . 64
5.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.4. 4xx Temporary Server Error . . . . . . . . . . . . . . . . 64
5.4.1. 400 Reserved . . . . . . . . . . . . . . . . . . . . . . . 64
5.4.2. 401 Internal Error . . . . . . . . . . . . . . . . . . . . 64
5.4.3. 410 Retry later . . . . . . . . . . . . . . . . . . . . . 64
5.5. 5xx Permanent Server Error . . . . . . . . . . . . . . . . 64
5.5.1. 500 Reserved . . . . . . . . . . . . . . . . . . . . . . . 64
5.5.2. 510 Unknown Command . . . . . . . . . . . . . . . . . . . 64
5.5.3. 511 Invalid Parameter . . . . . . . . . . . . . . . . . . 65
5.5.4. 512 Out of order . . . . . . . . . . . . . . . . . . . . . 65
5.5.5. 521 Not found . . . . . . . . . . . . . . . . . . . . . . 65
5.5.6. 531 Banned . . . . . . . . . . . . . . . . . . . . . . . . 65
6. All Possible Response Codes for All Commands . . . . . . . 65
6.1. Not-authenticated State . . . . . . . . . . . . . . . . . 65
6.2. Pre-authenticating State (PLAIN method) . . . . . . . . . 66
6.3. Authenticated State . . . . . . . . . . . . . . . . . . . 66
Radu Expires November 10, 2011 [Page 4]
Internet-Draft AGAP May 2011
6.4. Not-selected State . . . . . . . . . . . . . . . . . . . . 68
7. Example of Conversations . . . . . . . . . . . . . . . . . 68
7.1. Successful connection and authentication . . . . . . . . . 68
7.2. Successful connection but unsuccessful authentication . . 69
7.3. Connection refused . . . . . . . . . . . . . . . . . . . . 69
7.4. Find what folders are available with messages . . . . . . 70
7.5. Find all entries available in a folder . . . . . . . . . . 70
7.6. Retrieve a message . . . . . . . . . . . . . . . . . . . . 70
7.7. Retrieve a contact . . . . . . . . . . . . . . . . . . . . 71
7.8. Retrieve an event . . . . . . . . . . . . . . . . . . . . 72
7.9. Store a message . . . . . . . . . . . . . . . . . . . . . 74
7.10. Store a contact . . . . . . . . . . . . . . . . . . . . . 74
7.11. Store an event . . . . . . . . . . . . . . . . . . . . . . 75
7.12. Mark messages as SPAM an move them in a new folder . . . . 77
7.13. Create a filter folder, find the matching entries of
the filter and read its filter definition . . . . . . . . 77
7.14. Create a folder and rename it . . . . . . . . . . . . . . 78
7.15. Find the status for a folder . . . . . . . . . . . . . . . 78
7.16. Set and check the tags of a message . . . . . . . . . . . 79
7.17. Find messages that can be SPAM and delete them . . . . . . 79
8. References . . . . . . . . . . . . . . . . . . . . . . . . 80
8.1. Normative References . . . . . . . . . . . . . . . . . . . 80
8.2. Informative References . . . . . . . . . . . . . . . . . . 80
Author's Address . . . . . . . . . . . . . . . . . . . . . 80
Radu Expires November 10, 2011 [Page 5]
Internet-Draft AGAP May 2011
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 November 10, 2011 [Page 6]
Internet-Draft AGAP May 2011
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 November 10, 2011 [Page 7]
Internet-Draft AGAP May 2011
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 November 10, 2011 [Page 8]
Internet-Draft AGAP May 2011
2.5. Unique Identification Numbers
The length of an UID is between 1 and 32 characters.
The UIDs MUST to be unique only between entries from the same folder.
The characters accepted for building an UID are only all 26 Latin
letters (A-Z) in lowercase and uppercase and all 10 Latin digits
(0-9). An UID is case sensitive and it is valid only for the current
connection (the same message/contact/event CAN have different UIDs
for different client connections).
Any new message/contact/event MUST have a bigger UID as all other
existing entries 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 short UID is
before a longer one (9234 before 02345) and any zero (0) before a
number is take into account by the server when two UIDs are compared.
We get an approximately maximum number of 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. Folders
2.6.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.6.2. Hierarchy
None of the reserved folders can have subfolders, exception makes the
TRASH that must to store also deleted folders and FILESHARE that
holds ordinary files.
The character used for delimiting path levels is the slash (/). A
Radu Expires November 10, 2011 [Page 9]
Internet-Draft AGAP May 2011
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.6.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);
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;
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.6.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;
o CONFIGURATION - CONF - holds account configuration (tag: NO-
FOLDERS);
o CONTACT - ADDR - holds the main contact list;
Radu Expires November 10, 2011 [Page 10]
Internet-Draft AGAP May 2011
o DRAFT - MESG - holds templates for e-mail messages;
o FILESHARE - FILE - holds files accessible read-only by other users
(tags: READ-ONLY, and PUBLIC);
o INBOX - MESG - holds all new e-mail messages;
o JOURNAL - JRNL - holds the main journal;
o JUNK - MESG - holds all e-mail messages marked as SPAM or VIRUSED
by the server;
o NOTE - NOTE - holds short texts;
o OUTBOX - MESG - holds all e-mail messages that wait to be sent;
o SENT - MESG - holds copy of sent e-mail messages;
o TASK - TASK - holds the main tasks list;
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.7. Tags
2.7.1. Syntax
The client can set tags only for folder entries, but the server can
set tags also for folders. The tags of a folder are reported by the
STAT command.
The format of a tag is a name optionally followed by the equal sign
(=) and a value. Each time is a tag set, the new value replace the
old one. All tags that have no value assigned are returned only as
name. Assigning an empty value to a tag makes it to return a name
followed by the equal sign and no value. (This means that once a
value is assigned to a tag, it will always be returned together with
an equal sign.) Hint: Deleting and setting again (without a value) a
tag that previously had a value will make it being returned without
an equal sign.
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
Radu Expires November 10, 2011 [Page 11]
Internet-Draft AGAP May 2011
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.7.2. Reserved Tag Names
The following tag names have a meaning set by this standard for
folders:
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 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;
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, 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;
Radu Expires November 10, 2011 [Page 12]
Internet-Draft AGAP May 2011
o PUBLIC - the content of this folder can be read by all other
users;
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 - it was sent a reply to this e-mail message;
o SEEN - this object was already read;
o SPAM - this e-mail message is marked as spam;
2.8. The Responses for Each Type of Folder
2.8.1. Format and Conventions
All responses are in XML format. The tags and their attributes names
are written only in lowercase.
The content is encoded in UTF-8 [RFC3629] format.
Each type of folder returns its entries in a different format.
Each tag written in uppercase must to be send as it is, each tag
written in lowercase will be replaced with the right value at the
time of generation.
Each tag that have a star will be present only if it is the case and
without the star.
If a command is correct but the server cannot execute it because of
an internal error, then the server returns the code 401.
2.8.2. Response for Calendar Folders
The format is the same as the one defined by the xCal
[I-D.daboo-et-al-icalendar-in-xml] standard (work in progress).
Radu Expires November 10, 2011 [Page 13]
Internet-Draft AGAP May 2011
The following example corresponds to this event definition:
BEGIN:VCALENDAR
VERSION:2.0
CALSCALE:GREGORIAN
PRODID:-//agap/calender//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTAMP:20100701T110000Z
DTSTART:20101102T000000Z
DTEND:20101102T235959Z
SUMMARY:AGAP RFC Party
UID:uidx1234@example.com
END:VEVENT
END:VCALENDAR
Figure 2
Example:
Radu Expires November 10, 2011 [Page 14]
Internet-Draft AGAP May 2011
2.0
GREGORIAN
-//agap/calender//NONSGML v1.0//EN
20100701T110000Z
20101102
20101102
AGAP RFC Party
uidx1234@example.com
Figure 3
2.8.3. Response for Configuration Folders
A response holding the configuration has the following structure:
value...
Figure 4
Example:
Radu Expires November 10, 2011 [Page 15]
Internet-Draft AGAP May 2011
10
1024
Figure 5
2.8.4. Response for Contact Folders
The format is the same as the one defined by the vCard XML
Representation [I-D.ietf-vcarddav-vcardxml] standard (work in
progress).
Example:
Radu Expires November 10, 2011 [Page 16]
Internet-Draft AGAP May 2011
Iulian Radu
Radu
Iulian
Dipl.-Ing.
M
1
de
work
Example Com
work
iulian.radu@gmx.at
Europe/Vienna
Figure 6
2.8.5. Response for File Folders
A response holding the content of a file has the following structure:
name
content
Figure 7
The valid encodings type are: utf-8, quoted-printable, and base64.
It CAN be case-insensitive written.
Example:
Radu Expires November 10, 2011 [Page 17]
Internet-Draft AGAP May 2011
Example.txt
c3VyZS4=
Figure 8
2.8.6. Response for Filter Folders
An entryTag can be: and, or, not, uid, tag, is, regex. The value
associated to entryTag is specified as 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 "Syntax of a Filter" for more
information). The first entryTag MUST to be an AND or OR tag.
A response holding the content of a file has the following structure:
...
Figure 9
Example:
Viagra
UIDx1234:UIDx4321>
SPAM>
Figure 10
2.8.7. Response for Journal Folders
A response holding the content of one record in the journal and it
has the following structure:
Radu Expires November 10, 2011 [Page 18]
Internet-Draft AGAP May 2011
yyyy-mm-dd hh:mm:ss
...
...
Figure 11
Note: the category can be any short text. The UIDs for records must
to respect the cronology of entries (a later record must have a
bigger UID). 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'. The timestamp is UTC/GMT.
Example:
2011-04-01 09:02:19
new office/buying
A desk and a
chair were brought for the new office location.
Figure 12
2.8.8. Response for Message Folders
A response holding the content of a message has the following
structure:
Radu Expires November 10, 2011 [Page 19]
Internet-Draft AGAP May 2011
main text
main html
...
...
Figure 13
A parent="0" for an attachment tag means that is it part of the main
message or the parent is unknown. The value for parent is a number
used as id for another attachment entry. An attachment having a
wrong parent id will be considered to have no parent (parent="0").
It is incorrect for a tag to use the same number both for its id and
its parent.
The first item id and the first attachment id has the value 1.
The id of on item tag shows the order of the entries in the original
message.
The default content type for the main body and an attachment is
"text/plain", the default content encoding is utf-8, and the default
parent id is 0.
The entries in the header of the main message and attachments are the
same with the one from the e-mail message.
Example:
Radu Expires November 10, 2011 [Page 20]
Internet-Draft AGAP May 2011
example@no-spam.com
example@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 example
Please see the attachments.
<b>Please</b> see the <u>attachments</u>.
See the picture.
c3VyZS4=
Figure 14
The previous example corresponds to a message with the following
structure:
o multipart/mixed
Radu Expires November 10, 2011 [Page 21]
Internet-Draft AGAP May 2011
* multipart/alternative
+ text/plain
+ text/html
* multipart/related
+ text/plain
+ image/jpeg
2.8.9. Response for Note Folders
A response holding the content of the note has the following
structure:
...
...
Figure 15
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 16
2.8.10. Response for Task Folders
A response holding the content of the task has the following
structure:
Radu Expires November 10, 2011 [Page 22]
Internet-Draft AGAP May 2011
...
yyyy-mm-dd hh:mm:ss
yyyy-mm-dd hh:mm:ss
...
content
Figure 17
Note: the SDATE and EDATE are empty when there is no start or end
date for this task. The status can be any short text. A client GUI
can assign different colored flags for different statuses. 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'. The timestamps are UTC/
GMT.
Example:
buying a new desk
2011-04-01 10:30:00
PREPARING
To buy a new
desk and chair for the new office location.
Figure 18
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
Radu Expires November 10, 2011 [Page 23]
Internet-Draft AGAP May 2011
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'
(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'.
Radu Expires November 10, 2011 [Page 24]
Internet-Draft AGAP May 2011
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'
command or if the INBOX folder does not exists and it cannot be
selected automatically after a successful authentication.
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 and STAG.
A tag list defines what action to be done with its tags.
Radu Expires November 10, 2011 [Page 25]
Internet-Draft AGAP May 2011
Syntax: ACTION TAG TAG ...
ACTION:
o = - set only these tags;
o + - add this tags
o - - delete these tags.
Example:
C: STAG UIDx1234 = SEEN SPAM
C: STAG UIDx1234 + SEEN SPAM
C: STAG UIDx1234 - SEEN SPAM
Figure 19
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 the different messages. It is
defined as lines with rules and it is ended by an empty line.
The keywords of the filter are case insensitive matched (ex.: UID and
Uid are the same).
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 - the implicit rule;
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;
Radu Expires November 10, 2011 [Page 26]
Internet-Draft AGAP May 2011
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);
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 have at least 3 levels and must point to an end leaf. An
exception is for a leaf in header with have ITEM-n children. It
contains only tag names separated with /. Example: /message/header/
subject, /message/header/received/item-2, /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.
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
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 20
Example 2:
Radu Expires November 10, 2011 [Page 27]
Internet-Draft AGAP May 2011
C: IS header/subject = 'From University'
C: REGEX header/from != '[^0-9]+@example\.com$'
C: IS vcard/fn/text = 'Anonymous'
C: REGEX vcard/org/text = '^[A-Za-z]+[0-9]$'
Figure 21
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);
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 have at least 3 levels and must point to an end leaf. An
exception is for a leaf in header with have ITEM-n children. It
contains only tag names separated with /. Example: /message/header/
Radu Expires November 10, 2011 [Page 28]
Internet-Draft AGAP May 2011
subject, /message/header/received/item-2, /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:
/INBOX
UIDx0001:UIDx0010
SPAM
HAS=VIRUS
SEEN
Figure 22
Example 2:
Radu Expires November 10, 2011 [Page 29]
Internet-Draft AGAP May 2011
/INBOX
From University
[^0-9]+@example\.com$
Anonymous
^[A-Za-z]+[0-9]$
Figure 23
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 24
S: 401 Internal error, please contact our administrator
Figure 25
Radu Expires November 10, 2011 [Page 30]
Internet-Draft AGAP May 2011
S: 410 Sorry, too many connections, please retry later
Figure 26
S: 531 Your hostname/IP (localhost:127.0.0.1) is blacklisted
Figure 27
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 28
4.6. Command AUTH mechanism - not-authenticated state
Name: authenticate
Argument: mechanism
Results: 200 510 511
Result 200 - the mechanism is known and accepted.
Result 510 - unknown command.
Result 511 - the mechanism is unknown/unsupported.
Description: Choose an authentication method (exists at least the
mechanism PLAIN).
Examples:
Radu Expires November 10, 2011 [Page 31]
Internet-Draft AGAP May 2011
C: AUTH PLAIN
S: 200 OK Send USER
Figure 29
C: AUTH
S: 510 UNKNOWN command
Figure 30
C: AUTH unknown
S: 511 UNKNWON method
Figure 31
4.7. Command CAPA - not-authenticated state
Name: capabilities
Arguments: none
Result: 200
Description: Ask for the extensions known by the server.
Note: If the server accepts compression then it must advertise the
GZIP capability. If the server can encrypt the communication channel
then it must advertise the TLS capability. (The following example
shows both capabilities advertised.)
Example:
C: CAPA
S: .GZIP
S: .TLS
S: .Extension1
S: .Extension.2 argument1
S: .Extension-3 argument1 argument2
S: 200 OK CAPA completed
Figure 32
Radu Expires November 10, 2011 [Page 32]
Internet-Draft AGAP May 2011
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 33
C: SGZP
S: 510 UNKNOWN command
Figure 34
4.9. Command STLS - not-authenticated state
Name: start using TLS
Arguments: none
Results: 200 510
Radu Expires November 10, 2011 [Page 33]
Internet-Draft AGAP May 2011
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 35
C: STLS
S: 510 UNKNOWN command
Figure 36
4.10. Command PASS password - pre-authenticated state (PLAIN)
Name: password
Argument: password
Result: 200 510 511 512
Result 200 - the pair user/password was successfully authenticated.
Result 510 - unknown/unsupported command.
Result 511 - invalid password.
Result 512 - first send USER and then PASS.
Description: Send the password associated to the previous USER.
Examples:
Radu Expires November 10, 2011 [Page 34]
Internet-Draft AGAP May 2011
C: USER account
S: 200 OK Send PASS
C: PASS password
S: 200 OK Authenticated
Figure 37
C: USER account
S: 200 OK Send PASS
C: PASS
S: 510 UNKNOWN command
Figure 38
C: USER account
S: 200 OK Send PASS
C: PASS password
S: 511 WRONG user/password pair
Figure 39
C: AUTH PLAIN
S: 200 OK AUTH completed
C: PASS password
S: 512 EXPECTED USER
Figure 40
4.11. Command USER account - pre-authenticated state (PLAIN)
Name: user
Argument: account
Result: 200
Result: 200 510 511
Result 200 - the user is accepted and expecting the password.
Result 510 - unknown/unsupported command.
Result 511 - invalid account.
Description: Send an account name for authentication and
Radu Expires November 10, 2011 [Page 35]
Internet-Draft AGAP May 2011
authorization.
Examples:
C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 200 OK Send PASS
Figure 41
C: AUTH PLAIN
S: 200 OK Send USER
C: USER
S: 510 UNKNOWN command
Figure 42
C: AUTH PLAIN
S: 200 OK Send USER
C: USER account
S: 511 INVALID username
Figure 43
4.12. Command CHNG - authenticated state
Name: report all changes from a folder or from all folders
Arguments: path?
Result: 200 510 511
Result 200 - the command was successful.
Result 510 - unknown/unsupported command.
Result 511 - unknown or not absolute path.
Description: Return a list of changes in specified folder or all
changes if there is no path specified. The changes to the tags are
not reported. If there are not changes then the list is empty. A
move is reported in this list as a DITM for the source folder and a
NITM for destination folder. If the argument of CHNG is a deleted
folder then is returned a 200 code and there is in the list only a
Radu Expires November 10, 2011 [Page 36]
Internet-Draft AGAP May 2011
DELF for this folder. All reported changes are deleted after the 200
code is returned so a subsequent call of CHNG will report no changes
(if there are not any new changes).
Returned fields:
o DELF path - a folder was deleted. There is one entry for each
deleted folder. Deleted subfolders of a deleted folder are
reported too;
o NITM uid path - this item was added to the folder;
o DITM uid path - this item was deleted;
The path is an absolute path.
Examples:
C: CHNG
S: .DELF /Temporary
S: .DELF /Temporary/1980
S: .NITM UID1000 /INBOX
S: .DITM UID0900 /INBOX
S: .NITM UID1001 /OLD
S: .DITM UID1001 /INBOX
S: 200 OK CHNG completed
C: CHNG /INBOX
S: .NITM UID1000 /INBOX
S: .DITM UID0900 /INBOX
S: .DITM UID1001 /INBOX
S: 200 OK CHNG completed
C: CHNG /Temporary
S: .DELF /Temporary
S: 200 OK CHNG completed
Figure 44
C: CHNG
S: 510 UNKNOWN command
Figure 45
Radu Expires November 10, 2011 [Page 37]
Internet-Draft AGAP May 2011
C: CHNG ARCHIVE_FOLDER/TODAY
S: 511 PATH is relative
Figure 46
4.13. Command COPY - authenticated state
Name: copy entry
Arguments: UID_source path_destination_folder
Result: 200 510 511
Result 200 - the copy was successful.
Result 510 - unknown/unsupported command.
Result 511 - unknown uid or invalid destination folder.
Description: Copy a message/contact/event from the currently selected
folder into another folder (by UID).
Note: For copying a folder the client must use CPYF.
Examples:
C: COPY UIDx1234 ARCHIVE_FOLDER/TODAY
S: 200 OK COPY completed
Figure 47
C: COPY
S: 510 UNKNOWN command
Figure 48
Radu Expires November 10, 2011 [Page 38]
Internet-Draft AGAP May 2011
C: COPY UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: COPY MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination
Figure 49
4.14. 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
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 50
Radu Expires November 10, 2011 [Page 39]
Internet-Draft AGAP May 2011
C: CPYF
S: 510 UNKNOWN command
Figure 51
C: CPYF MISSING
S: 511 INVALID Destination
Figure 52
4.15. Command DATT - authenticated state (MESG folder type)
Name: delete attachment
Arguments: UID AttNum
Result: 200 510 511 521
Result 200 - the attachment was successfully deleted.
Result 510 - unknown/unsupported command.
Result 511 - unknown uid or uid is not for a message.
Result 521 - wrong attachment number.
Description: Delete from a message an attachment. The first
attachment has number 1. All its children are also deleted.
Note: It cannot be undone.
Examples:
C: DATT UIDx1234 1
S: 200 OK Attachment deleted
Figure 53
Radu Expires November 10, 2011 [Page 40]
Internet-Draft AGAP May 2011
C: DATT
S: 510 UNKNOWN command
Figure 54
C: DATT UIDx1234 1
S: 511 INVALID UID
C: DATT UIDx1234 -1
S: 511 INVALID Attachment number
Figure 55
C: DATT UIDx1234 10
S: 521 There are not so many attachments
Figure 56
4.16. Command DELE - authenticated state
Name: delete entry
Argument: UID
Result: 200 510 511
Result 200 - the entry was successfully deleted.
Result 510 - unknown/unsupported command.
Result 511 - unknown uid.
Description: Delete a message/contact/event by uid.
Note: It cannot be undone.
Examples:
C: DELE UIDx1234
S: 200 OK Message deleted
Figure 57
Radu Expires November 10, 2011 [Page 41]
Internet-Draft AGAP May 2011
C: DELE
S: 510 UNKNOWN command
Figure 58
C: DELE 1234
S: 511 INVALID UID
Figure 59
4.17. 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:
C: DELF
S: 200 OK Folder '/delete/me' was deleted
Figure 60
Radu Expires November 10, 2011 [Page 42]
Internet-Draft AGAP May 2011
C: DELF
S: 510 UNKNOWN command
Figure 61
C: DELF
S: 511 Please select first a folder
C: DELF
S: 511 /INBOX cannot be deleted
Figure 62
4.18. 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 63
4.19. Command FCPY - authenticated state
Name: find and copy entries
Arguments: path_destination_folder filter*
Result: 200 510 511
Result 200 - the find and copy was successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder or wrong filter.
Description: Search for messages/contacts/events only from the
currently selected folder (no subfolders) that correspond to a filter
and copy them to a new folder. The tags are also copied.
Radu Expires November 10, 2011 [Page 43]
Internet-Draft AGAP May 2011
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 64
C: FCPY
S: 510 UNKNOWN command
Figure 65
C: FCPY MISSING
S: 511 INVALID folder
C: FCPY SEND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 66
4.20. Command FDEL - authenticated state
Name: find and delete entries
Argument: filter*
Result: 200 511
Result 200 - the find and delete was successful.
Result 511 - wrong filter (inclusive empty filter).
Description: Search for messages/contacts/events only from the
currently selected folder (no subfolders) that correspond to a filter
and delete them (no copy in TRASH).
Note: The filter is delivered after the acceptance of the command
Radu Expires November 10, 2011 [Page 44]
Internet-Draft AGAP May 2011
(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 67
C: FDEL
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 68
4.21. Command FIND - authenticated state
Name: find entry
Argument: filter*
Result: 200 511
Result 200 - the find was successful.
Result 511 - wrong filter.
Description: Search for messages/contacts/events only from the
currently selected folder (no subfolders) that correspond to a filter
and return their UIDs. If the search is done for a filter folder
then the server does not expect any filter and apply the current
filter (if any). If there is no filter in the filter folder then it
is returned only the return code. The answer consists of the UIDs
and, for a filter folder, they are followed by a 0x20 character and
the absolute path for which are the corresponding UID.
Note: For not FILT folders, the filter is delivered after the
acceptance of the command. An empty filter matches all messages/
contacts/events from that folder.
Examples:
Radu Expires November 10, 2011 [Page 45]
Internet-Draft AGAP May 2011
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 69
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 70
4.22. Command FMOV - authenticated state
Name: find and move
Arguments: path_destination_folder filter*
Result: 200 510 511
Result 200 - the find and move was successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid destination folder or wrong filter.
Description: Search for messages/contacts/events only from the
currently selected folder (no subfolders) that correspond to a filter
and move them to a new folder. The tags are also moved.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Radu Expires November 10, 2011 [Page 46]
Internet-Draft AGAP May 2011
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 71
C: FMOV
S: 510 UNKNOWN command
Figure 72
C: FMOV MISSING
S: 511 INVALID folder
C: FMOV SEND
S: 110 OK SEND filter definition (end it with an empty line)
C: LATER
C:
S: 511 INVALID filter definition
Figure 73
4.23. Command FTAG - authenticated state
Name: find and tag entries
Arguments: tag_list filter*
Result: 200 510 511
Result 200 - the find and set of tag(s) were successful.
Result 510 - unknown/unsupported command.
Result 511 - invalid tag list or wrong filter.
Description: Search for messages/contacts/events only from the
currently selected folder (no subfolders) that correspond to a filter
and change their tags.
Note: The filter is delivered after the acceptance of the command
(response code 110).
Radu Expires November 10, 2011 [Page 47]
Internet-Draft AGAP May 2011
Examples:
C: FTAG + SEEN
S: 110 OK SEND filter definition (end it with an empty line)
C: UID 00000001:00001000 AND TAG NEW
C:
S: 200 OK FTAG completed (10 matches)
Figure 74
C: FTAG
S: 510 UNKNOWN command
Figure 75
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 76
4.24. Command GTAG - authenticated state
Name: get tag
Arguments: UID_range
Result: 200 510 511
Result 200 - the tag(s) of UIDs was/were successful displayed.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID or UID range.
Description: Return the tags associated to one or more messages/
contacts/events (by UID).
Examples:
Radu Expires November 10, 2011 [Page 48]
Internet-Draft AGAP May 2011
C: GTAG UIDx1000
S: .UIDx1000 SEEN SPAM
S: 200 OK GTAG completed
C: GTAG UIDx1000:UIDx1234
S: .UIDx1000 SEEN SPAM
S: .UIDx1100
S: .UIDx1200 NEW
S: 200 OK GTAG completed
Figure 77
C: GTAG
S: 510 UNKNOWN command
Figure 78
C: GTAG -1
S: 511 INVALID UID
C: GTAG UIDx1234:UIDx1000
S: 511 INVALID UID range
Figure 79
4.25. Command LIST - authenticated and not-selected state
Name: list
Arguments: path/filter?
Results: 200 511 513
Result 200 - the list was successful delivered (even if it is empty).
Result 511 - filter is invalid, 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 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
Radu Expires November 10, 2011 [Page 49]
Internet-Draft AGAP May 2011
folders in the hierarchy. There can be only a star (*) and must to
be located in the name of the last folder. 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)
C: LIST /archive*
S: 200 OK LIST completed (0 matches)
Figure 80
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 81
4.26. Command MAKE - authenticated and not-selected state
Name: make folder
Argument: type path
Result: 200 510 511
Result 200 - the folder was successfully created.
Result 510 - unknown/unsupported command.
Radu Expires November 10, 2011 [Page 50]
Internet-Draft AGAP May 2011
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.
Note: A new folder has not any tag, except the tag PUBLIC if its
parent has it.
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:
C: MAKE MESG /ARCHIVE/2010
S: 200 OK Folder created
Figure 82
Radu Expires November 10, 2011 [Page 51]
Internet-Draft AGAP May 2011
C: MAKE
S: 510 UNKNOWN command
Figure 83
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 84
4.27. Command MOVE - authenticated state
Name: move entry
Arguments: UID_source path_destination_folder
Result: 200 510 511
Result 200 - the move was successful.
Result 510 - unknown/unsupported command.
Result 511 - unknown uid or invalid destination folder.
Description: Move a message/contact/event into another folder (by
UID).
Note: For moving a folder the client must use MOVF.
Examples:
C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 200 OK MOVE completed
Figure 85
Radu Expires November 10, 2011 [Page 52]
Internet-Draft AGAP May 2011
C: MOVE
S: 510 UNKNOWN command
Figure 86
C: MOVE UIDx1234 ARCHIVE_FOLDER/TODAY
S: 511 INVALID UID
C: MOVE MSGx1234 ARCHIVE_FOLDER/1970
S: 511 INVALID Destination
Figure 87
4.28. 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 November 10, 2011 [Page 53]
Internet-Draft AGAP May 2011
C: SLCT /INBOX
S: 200 Selected /INBOX
C: MOVF /ARCHIVE_FOLDER/TODAY
S: 200 OK MOVF completed
Figure 88
C: MOVF
S: 510 UNKNOWN command
Figure 89
C: MOVF MISSING
S: 511 INVALID Destination
Figure 90
4.29. 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 November 10, 2011 [Page 54]
Internet-Draft AGAP May 2011
C: SLCT ARCHIVE/2001
S: 200 OK
C: NAME OLD-2001
S: 200 OK NAME completed
Figure 91
C: NAME
S: 510 UNKNOWN command
Figure 92
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 93
4.30. 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 94
4.31. Command RETR - authenticated state
Name: retrieve
Arguments for a FILT folder: none
Radu Expires November 10, 2011 [Page 55]
Internet-Draft AGAP May 2011
Arguments for other types: UID part?
Results: 200 510 511
Result 200 - the message/contact/event was found or filter content
was delivered.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID or part name.
Description: Fetch from server the message/contact/event with the
given UID. For a filter folder, it must be called without arguments
and it returns the content of the filter. Each line of answer is
prefixed with a dot that it is not part of the returned object.
Part: It is a PATH in the response as it is returned by RETR and must
have at least 3 levels and must point to an end leaf. An exception
is for a leaf in header with have ITEM-n children. It contains only
tag names separated with /. Example: /message/header/subject,
/message/header/received/item-2, /message/body/html, /message/body/
attachment-1/body. If it is present 'part' then the value of this
entry is returned as text instead of XML. For an entry in the header
with a multivalue are returned each value on its own line.
Examples:
Radu Expires November 10, 2011 [Page 56]
Internet-Draft AGAP May 2011
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 95
C: RETR
S: 510 UNKNOWN command (only FILT folders do not needs arguments)
Figure 96
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 97
4.32. 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 November 10, 2011 [Page 57]
Internet-Draft AGAP May 2011
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 98
C: SLCT
S: 510 UNKNOWN command
Figure 99
C: SLCT 1234
S: 511 INVALID folder
C: SLCT /
S: 511 You cannot select /
Figure 100
4.33. Command SPAM - authenticated state (MESG folder type)
Name: spam
Argument: UID reason?
Result: 200 510 511
Result 200 - the entry was successfully marked.
Result 510 - unknown/unsupported command.
Result 511 - invalid or not found UID, or invalid reason.
Description: Mark a message as SPAM/MALWARE. The server can ignore
this command or it can check the reason (if present) and improve its
Radu Expires November 10, 2011 [Page 58]
Internet-Draft AGAP May 2011
SPAM detection mechanism.
Reason: It can be the name of a field (ex.: header/subject)
eventually followed by equal and the text from that field that
identify it as a SPAM. If there is more than one criterion for
marking a message as SPAM then the client must supply for each reason
a SPAM command. If there is no reason then the whole indicated
field's content is used.
Note: It cannot be undone and no tag is set for this message.
Examples:
C: SPAM UIDx1234
S: 200 OK Message added to the spam database
C: SPAM UIDx1234 header/subject
S: 200 OK Message added to the spam database
C: SPAM UIDx1234 body=V1AGRA
S: 200 OK Message added to the spam database
Figure 101
C: SPAM
S: 510 UNKNOWN command
Figure 102
C: SPAM 1234
S: 511 INVALID UID
Figure 103
4.34. Command STAG - authenticated state
Name: set tags of entries
Arguments: UID_range tag_list
Result: 200 510 511
Result 200 - the tag(s) for UIDs were successful set.
Result 510 - unknown/unsupported command.
Result 511 - invalid UID or UID range.
Radu Expires November 10, 2011 [Page 59]
Internet-Draft AGAP May 2011
Description: Set or delete tags associated to one or more messages/
contacts/events (by UID).
Examples:
C: STAG UIDx1000 + SEEN
S: 200 OK STAG completed
C: STAG UIDx1000:UIDx1234 + SEEN
S: 200 OK STAG completed
Figure 104
C: STAG
S: 510 UNKNOWN command
Figure 105
C: STAG -1
S: 511 INVALID UID
C: STAG -1 + SEEN
S: 511 INVALID UID
C: STAG UIDx1234 SEEN
S: 511 INVALID tag list
Figure 106
4.35. Command STAT - authenticated state
Name: status
Arguments: none
Result: 200 512
Result 200 - the status of the folder was successfully delivered.
Result 512 - no folder is selected.
Description: Return the absolute path of the currently selected
folder (PATH), its type (TYPE), an FCID that is incremented each time
a change is produced into the folder, the tags (TAGS) and eventually
additional information associated with this type of folder.
Additional information:
Radu Expires November 10, 2011 [Page 60]
Internet-Draft AGAP May 2011
o ADDR - none;
o CALE - none;
o CONF - none.
o FILE - TOTAL;
o FILT - TOTAL and NEW;
o FOLD - none;
o JRNL - none;
o MESG - TOTAL and NEW;
o NOTE - TOTAL;
o TASK - TOTAL;
Note: An FCID has the same format as a normal UID and each new value
of FCID is bigger as the precedent one (as is described for UIDs).
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 107
C: STAT
S: 512 ERROR First select a folder
Figure 108
4.36. Command STOR - authenticated state
Name: store
Arguments: none
Radu Expires November 10, 2011 [Page 61]
Internet-Draft AGAP May 2011
Result: 200 410 511
Result 200 - the entry was successfully deleted.
Result 410 - if the item cannot be stored.
Result 511 - if the data is not a valid XML or its schema does not
correspond to the type of the destination folder.
Description: Store a new message/contact/event/filter into a folder.
If it is written a new filter into a FILT folder, then the previous
filter is deleted. If the new filter has an invalid XML structure or
cannot be saved then the folder remains with the old filter (if any).
Note: Do not send a message content using CDATA as it can hold empty
lines and an empty line means for the server the end of the message
to be stored.
Examples:
C: STOR
S: 110 Send the message ended with an empty line
C: ...
C:
S: 200 OK Message stored (UID is UIDx1234)
Figure 109
C: STOR
S: 110 Send the message ended with an empty line
C: ...
C:
S: 410 Cannot store it, not enough space
Figure 110
Radu Expires November 10, 2011 [Page 62]
Internet-Draft AGAP May 2011
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 111
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
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
Radu Expires November 10, 2011 [Page 63]
Internet-Draft AGAP May 2011
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.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.
Radu Expires November 10, 2011 [Page 64]
Internet-Draft AGAP May 2011
5.5.3. 511 Invalid Parameter
The request could not be processed because the command has an invalid
parameter.
This answer can be returned even if there was more than one 0x20
character between command and its arguments or between arguments.
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.)
5.5.5. 521 Not found
This command has a valid syntax but the searched argument does not
exist or cannot be accessed. (Ex.: LIST with a path does not have
any wildcard and it does not exist.)
5.5.6. 531 Banned
The client is not allowed to interact with the server. (Ex.: the
client's IP is blacklisted.)
6. All Possible Response Codes for All Commands
6.1. Not-authenticated State
The Welcome Message: 200 401 410 531
QUIT: 200
AUTH: 510 511
AUTH mechanism: 200 511
CAPA: 200
SGZP: 200 510
STLS: 200 510
other: 510
Radu Expires November 10, 2011 [Page 65]
Internet-Draft AGAP May 2011
6.2. Pre-authenticating State (PLAIN method)
QUIT: 200
PASS: 510 511 512
PASS password: 200 511 512
USER: 510 511
USER account: 200 511
other: 510
6.3. Authenticated State
QUIT: 200
COPY: 510 511
COPY arguments: 200 511
CPYF: 510 511
CPYF arguments: 200 511
DATT: 510 511
DATT arguments: 200 511 521
DELE: 510 511
DELE arguments: 200 511
DELF: 510 511
DELF arguments: 200 511
EXIT: 200
FCPY: 510 511
FCPY arguments: 200 511
FDEL: 511
FDEL arguments: 200 511
Radu Expires November 10, 2011 [Page 66]
Internet-Draft AGAP May 2011
FIND: 511
FIND arguments: 200 511
FMOV: 510 511
FMOV arguments: 200 511
FTAG: 510 511
FTAG arguments: 200 511
GTAG: 510 511
GTAG arguments: 200 511
LIST: 200
LIST arguments: 200 511
MAKE: 510 511
MAKE arguments: 200 511
MOVE: 510 511
MOVE arguments: 200 511
MOVF: 510 511
MOVF arguments: 200 511
NAME: 510 511
NAME arguments: 200 511
NOOP: 200
RETR: 510 511
RETR arguments: 199 200 511
SLCT: 510 511
SLCT arguments: 200 511
SPAM: 510 511
Radu Expires November 10, 2011 [Page 67]
Internet-Draft AGAP May 2011
SPAM arguments: 200 511 512
STAG: 510 511
STAG arguments: 200 511
STAT: 200 512
STOR: 200 410 511
other: 510
6.4. Not-selected State
LIST: 200
LIST arguments: 200 511
SLCT: 510 511
SLCT arguments: 200 511
other: 510
7. Example of Conversations
7.1. Successful connection and authentication
Radu Expires November 10, 2011 [Page 68]
Internet-Draft AGAP May 2011
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 112
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 113
7.3. Connection refused
S: 531 Your IP is blacklisted
Figure 114
S: 410 Too many connections, please retry later
Figure 115
Radu Expires November 10, 2011 [Page 69]
Internet-Draft AGAP May 2011
S: 401 Internal error, the server has an error in its configuration
Figure 116
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 117
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 118
7.6. Retrieve a message
Radu Expires November 10, 2011 [Page 70]
Internet-Draft AGAP May 2011
C: SLCT /INBOX
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: TAG 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: .HCCP Newsletter
S: .
S: .This is your weekly newsletter.
S: .
S: 200 OK RETR completed
Figure 119
7.7. Retrieve a contact
Radu Expires November 10, 2011 [Page 71]
Internet-Draft AGAP May 2011
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/text = 'RADU.*?'
C: REGEX vcard/fn/text = '.*? Iulian'
C:
S: .CONx0001
S: 200 OK FIND completed (1 match)
C: RETR CONx0001
S: .
S: .
S: . Iulian Radu
S: .
S: . Radu
S: . Iulian
S: .
S: . Dipl.-Ing.
S: .
S: .
S: . 1
S: .
S: . 1
S: . de
S: .
S: .
S: . work
S: . Example Com
S: .
S: .
S: . work
S: . iulian.radu@gmx.at
S: .
S: . PUBLIC
S: .
S: .
S: 200 OK RETR completed
Figure 120
7.8. Retrieve an event
C: SLCT /CALENDAR
S: 200 OK Folder selected
C: FIND
S: 110 OK SEND filter definition (end it with an empty line)
C: OR IS vcalendar/components/vevent/properties/location = 'Wien'
Radu Expires November 10, 2011 [Page 72]
Internet-Draft AGAP May 2011
C: IS vcalendar/components/vevent/properties/uid/text =
C: 'uidx1234@example.com'
C:
S: .EVNx0001
S: 200 OK FIND completed (1 match)
C: RETR EVNx0001
S: .
S: .
S: .
S: .
S: . -//agap/calender//NONSGML v1.0//EN
S: .
S: . 2.0
S: .
S: .
S: .
S: .
S: . Vienna
S: .
S: .
S: . 2010
S: . 1
S: . 31
S: . 11
S: . 0
S: . 0
S: .
S: .
S: .
S: .
S: . 2010
S: . 11
S: . 2
S: . 21
S: . 30
S: . 0
S: .
S: .
S: .
S: .
S: . 2010
S: . 11
S: . 2
S: .
S: .
S: .
S: . An event in Wien.
S: .
Radu Expires November 10, 2011 [Page 73]
Internet-Draft AGAP May 2011
S: .
S: . uidx1234@example.com
S: .
S: .
S: .
S: .
S: .
S: .
S: 200 OK RETR completed
Figure 121
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 122
7.10. Store a contact
Radu Expires November 10, 2011 [Page 74]
Internet-Draft AGAP May 2011
C: SLCT /CONTACT
S: 200 OK Folder selected
C: STOR
S: 110 Send the contact info ended with an empty line
C:
C:
C: Iulian Radu
C:
C: Radu
C: Iulian
C:
C: Dipl.-Ing.
C:
C:
C: 1
C:
C: 1
C: de
C:
C:
C: work
C: Example Com
C:
C:
C: work
C: iulian.radu@gmx.at
C:
C: PUBLIC
C:
C:
C:
S: 200 OK Contact stored (UID is UIDx1234)
Figure 123
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:
C:
C:
C: -//agap/calender//NONSGML v1.0//EN
C:
Radu Expires November 10, 2011 [Page 75]
Internet-Draft AGAP May 2011
C: 2.0
C:
C:
C:
C:
C: Vienna
C:
C:
C: 2010
C: 1
C: 31
C: 11
C: 0
C: 0
C:
C:
C:
C:
C: 2010
C: 11
C: 2
C: 21
C: 30
C: 0
C:
C:
C:
C:
C: 2010
C: 11
C: 2
C:
C:
C:
C: An event in Wien.
C:
C:
C: uidx1234@example.com
C:
C:
C:
C:
C:
C:
C:
S: 200 OK Event stored (UID is UIDx1234)
Figure 124
Radu Expires November 10, 2011 [Page 76]
Internet-Draft AGAP May 2011
7.12. Mark messages as SPAM an move them in a new folder
C: STAG UIDx1000 + SPAM
S: 200 OK STAG completed
C: SPAM UIDx1000 header/subject
S: 200 OK Message added to the spam database
C: MAKE MESG /Archive-SPAM
S: 200 OK Folder created
C: FMOV /Archive-SPAM
S: 110 OK SEND filter definition (end it with an empty line)
C: TAG SPAM
C:
S: 200 OK FMOV completed (19 matches)
Figure 125
7.13. Create a filter folder, find the matching entries of the filter
and read its filter definition
Radu Expires November 10, 2011 [Page 77]
Internet-Draft AGAP May 2011
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 126
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 127
7.15. Find the status for a folder
Radu Expires November 10, 2011 [Page 78]
Internet-Draft AGAP May 2011
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 128
7.16. Set and check the tags of a message
C: STAG UIDx1000 + SEEN
S: 200 OK STAG completed
C: GTAG UIDx1000
S: UIDx1000 SEEN SPAM
S: 200 OK GTAG completed
Figure 129
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 130
8. References
Radu Expires November 10, 2011 [Page 79]
Internet-Draft AGAP May 2011
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
[I-D.daboo-et-al-icalendar-in-xml]
Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
format for iCalendar",
draft-daboo-et-al-icalendar-in-xml-08 (work in progress),
April 2011.
[I-D.ietf-vcarddav-vcardxml]
Perreault, S., "vCard XML Representation",
draft-ietf-vcarddav-vcardxml-09 (work in progress),
April 2011.
[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.
[RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
April 2001.
[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.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
Radu Expires November 10, 2011 [Page 80]
Internet-Draft AGAP May 2011
Author's Address
Iulian Radu (editor)
Email: iulian.radu@gmx.at
Radu Expires November 10, 2011 [Page 81]