Advanced Groupware Access Protocol

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.

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' . 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 specification.

All data exchanged between the server and the client is done using strings encoded UTF-8 . If the server or client send a string incorrect encoded then the other side can close immediately the connection.

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.

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.

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

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 (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.

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.

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 has 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.

Binary content must be encoded using the BASE64 method and the corresponding tag must have the ENCODED attribute set to "base64". A text content can be passed as it is ( UTF-8 ) or it can be encoded using the BASE64 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.

An SRV record (Service record) defines the location in the DNS (Domain Name System) of a server providing a specified service. It is defined in RFC 2782 . A non-secured port is searched with _agap and a secured port with _agaps as _service name. An SRV record has the form:

_service._proto.name ttl IN SRV priority weight port target service - the symbolic name of the desired service; proto - the transport protocol of the desired service (TCP or UDP); name - the domain name for which this record is valid; ttl - standard DNS time to live field (usually 86400); priority - the priority of the target host (lower value means more preferred); weight - a relative weight for records with the same priority; port - the TCP or UDP port on which the service is present; target - the canonical hostname of the machine providing the service. The following textual entry can be used to specify the location of an AGAP service:

_agap._tcp.example.com. 86400 IN SRV 0 5 143 agapserver.example.com. The following textual entry can be used to specify the location of a secured AGAP port (via SSL):

_agaps._tcp.example.com. 86400 IN SRV 0 5 993 agapserver.example.com.

All folder names are case sensitive and they are encoded according to UTF-8 . 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 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 '..'.

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

The following folder types are defined by this standard: calendar - CALE - holds events; configuration - CONF - holds user accounts configuration (the client is free to store all information it needs for providing roaming); contacts - ADDR - holds contact information; files - FILE - holds files that have no special meanings for the server; filter - FILT - holds the definition of a filter (it does not allow subfolders); folder - FOLD - contains only subfolders; journal - JRNL - holds journal entries; message - MESG - holds e-mail messages; notes - NOTE - holds short texts; tasks - TASK - holds tasks. Each of these types allow for subfolders in them.

All the following reserved folders are located in the root of the user's account: CALENDAR - CALE - holds the main calendar of the user (PUBLIC); CONFIGURATION - CONF - holds account configuration; CONTACT - ADDR - holds the main contact list (PUBLIC); DRAFT - MESG - holds templates for e-mail messages; FILESHARE - FILE - holds shared files (PUBLIC); INBOX - MESG - holds all new e-mail messages (PUBLIC); JOURNAL - JRNL - holds the main journal (PUBLIC); JUNK - MESG - holds all e-mail messages marked as SPAM or VIRUSED by user or the server; NOTE - NOTE - holds short texts (PUBLIC); OUTBOX - MESG - holds all e-mail messages that wait to be sent; SENT - MESG - holds copy of sent e-mail messages; TASK - TASK - holds the main tasks list (PUBLIC); 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.

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.

The following tag names have a meaning set by this standard for folders: FIX-TAGS - the tags of this folder cannot be changed with FTGS; 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; 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; 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; NO-FOLDERS - this entry cannot have subfolders, so the user cannot create subfolders in it with MAKE; 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; NO-RENAME - the name of this folder cannot be changed with NAME; 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; 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: ANSWERED - a replay was sent for this item; FORWARDED - the message was forwarded by the user; SEEN - the message was sow by the user; SPAM - this e-mail message is marked as spam;

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: r - it is allowed to read folder's attributes and tags; A - it is allowed to add entries to the folder; D - it is allowed to delete entries from folder; L - it is allowed to find which entries (IDs) holds the folder; 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 .

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

The format is derived from the one defined for VEVENT and VALARM by the iCalendar standard. The following example corresponds to this VEVENT definition:

Example event:

20110531T114600Z-123456@agap.at 2011-05-31 12:10:00 2011-06-07 18:00:00 2011-06-07 24:00:00

AGAP RFC Party

Celebration of a new revision! 0.4 20110607T170000Z-20110531T114600Z-123456@agap.at ]]> The following example corresponds to this alarm definition related to the previous event:

Example alarm:

20110607T170000Z-20110531T114600Z-123456@agap.at

20110531T114600Z-123456@agap.at

2011-06-07 17:00:00 3 900 AUDIO ABCDEFGHIJ== ]]> The BEGIN:VEVENT is replaced with <VEVENT> and END:VEVENT is replaced with </VEVENT>. The BEGIN:VALARM is replaced with <VALARM> and END:VALARM is replaced with </VALARM>. 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. 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 XML. The DURATION must be always a relative value in seconds. 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 an ALARM 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. An VEVENT can have only one VALARM associated.

A response holding the configuration has the following structure:

value... ]]> Example:

1024 ]]>

The format is derived from the one defined by the vCard standard. The following example corresponds to this VCARD definition:

Example:

3.0 Iulian Radu Radu;Iulian;;Dipl.Ing.; Example Com, Inc.;European Division iulian.radu@gmx.at +01:00 2011-05-31 18:46:00 ABCDEFGHIJ== 1. Operngasse 1010 Wien Austria ]]> The BEGIN:VCARD is replaced with <VCARD> and END:VCARD is replaced with </VCARD>. 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 Representation of dates and times. 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 an attribute SOURCE for VCARD type as the content of this VCARD must 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.

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

name content ]]> The valid encodings type are: utf-8 and base64. The default encoding is base64. Example:

Example.txt c3VyZS4= ]]>

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 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. A response holding the content of a file has the following structure:

...? ...... ...... ]]> Example:

A sample FILT filter. /INBOX /Spam Viagra UIDx1234:UIDx4321 SPAM ]]>

The format is derived from the one defined for VJOURNAL by the iCalendar standard. The following example corresponds to this VJOURNAL definition:

Example:

20110531T184600Z-123456@agap.at 2011-06-07 13:52:38 2011-06-07 13:52:38

Revise AGAP Internet-Draft

1. The draft was revised, saved and closed. 2. It is ready to be published. ABCDEFGHIJ== ]]> The BEGIN:VJOURNAL is replaced with <VJOURNAL> and END:VJOURNAL is replaced with </VJOURNAL>. 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. 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:CID:', so referincing parts that cannot exists in this XML.

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

value... value 1 value 2 ... value n......

main text main html

...

... ... ]]> 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:

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

text/plain

See the picture.

image/jpeg

base64

c3VyZS4= ]]> The previous example corresponds to a message with the following structure: multipart/mixed multipart/alternative text/plain text/html text/plain image/jpeg

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

... ... ]]> 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. ]]>

The format is derived from the one defined for VTODO by the iCalendar standard. The following example corresponds to this VTODO definition:

Example:

20110531T184600Z-123456@agap.at 2011-05-31 18:46:00 2011-06-07 12:00:00 2011-06-07 14:00:00 2011-06-07 13:52:38

Revise AGAP Internet-Draft

1 NEEDS-ACTION ABCDEFGHIJ== 20110607T170000Z-20110531T184600Z-123456@agap.at ]]> The following example corresponds to this alarm definition related to the previous task:

Example alarm:

20110607T170000Z-20110531T184600Z-123456@agap.at

20110531T184600Z-123456@agap.at

2011-06-07 17:00:00 3 900 AUDIO ABCDEFGHIJ== ]]> The BEGIN:VTODO is replaced with <VTODO> and END:VTODO is replaced with </VTODO>. The BEGIN:VALARM is replaced with <VALARM> and END:VALARM is replaced with </VALARM>. 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. 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 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 an ALARM 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. An VTODO can have only one VALARM associated.

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.

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'.

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'.

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.

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.

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.

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).

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: = - set only these tags; + - add these tags - - 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:

Note: After this three commands we have only the following tags: SEEN SPAM=YES JUNK OWNER=RAI.

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: ( ) - grouping for AND and OR; AND - all following rules are with AND bonded (until the end of the current group). It is the implicit rule when the first rule is not an AND or an OR; OR - all following rules are with OR bonded (until the end of the current group); NOT - invert the result of the following rule; UID uid - one UID; 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); TAG tag_name - a tag of an entry; TAG tag_name=tag_value - an entry's tag with a value (tag_value is the complete value); 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: <, <=, =, !=, >=, >; 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. NEW - it is true if an entry is marked as new; after a new entry was reported or retrieved (by DATT, FIND, FRTR, RETC, RETR 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 as it is returned by RETR and must point to a not binary end leaf. It contains only tag names separated with /. Example: /MESSAGE/HEADER/subject, /MESSAGE/HEADER/received, /MESSAGE/TEXT, /MESSAGE/HTML, /MESSAGE/ATTACHMENT-1/HEADER/type, /MESSAGE/ATTACHMENT-1/BODY. There is an exception, for FILT folder types the path /FILTER/FOLDERS returns the list of folders with a folder path per line and the path /FILTER/FOLDERS/FOLDER is invalid. Searching for a TAG without associating and a value to it will match all entries having 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.

Example 2:

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: AND - all its entries must be matched; OR - at least one of its entries must be matched; NOT - invert the result of its child rule; UID uid - one UID; UID uid_begin_range:uid_end_range - inclusive range; TAG tag_name - a tag; TAG tag_name=tag_value - a tag with a value (tag_value is the complete value); 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: <, <=, =, !=, >=, >; 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 as it is returned by RETR and must point to a not binary end leaf. It contains only tag names separated with /. Example: /MESSAGE/HEADER/subject, /MESSAGE/HEADER/received, /MESSAGE/TEXT, /MESSAGE/HTML, /MESSAGE/ATTACHMENT-1/BODY. There is an exception, for FILT folder types the path /FILTER/FOLDERS returns the list of folders with a folder path per line and the path /FILTER/FOLDERS/FOLDER is invalid. 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 ]]> Example 2:

/INBOX From University [^0-9]+@example\.com$ Anonymous ^[A-Za-z]+[0-9]$ ]]>

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:

Name: quit Arguments: none Result: 200 Description: The QUIT command close the connection between the client and server. Example:

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. 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:

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. ADDR - contact information; AUTH-PLAIN - suport plain authentication; AUTH-PRESENCE - suport authentication for asking about presence; AUTH-PRESENCE-MD5 - suport authentication for asking about presence; AUTH-PRESENCE-SHA1 - suport authentication for asking about presence; AUTH-MD5 - suport MD5 authentication; AUTH-SHA1 - suport SHA1 authentication; AUTH-STORING - suport authentication for receiving items; AUTH-STORING-MD5 - suport authentication for receiving items; AUTH-STORING-SHA1 - suport authentication for receiving items; CALE - events; CHNG - list the FCID of all folders; CONF - user accounts configuration; FACL - ACL for folders; FILE - storing files; FILT - definition of a filter; STOR - accepts storing from external sources; JRNL - journal entries; MESG - e-mail messages; NOTE - short texts; PNFO - presence; SGZP - server accepts compression; STLS - server can encrypt the communication channel; TASK - tasks. Example:

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 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:

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:

Name: hash Argument: hash_code Result: 200 510 511 512 Result 200 - the pair user/hash was successfully authenticated. Result 510 - unknown/unsupported command. 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:

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:

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:

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:

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:

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:

Note: A change in /ARCHIVE/2010 will change the FCID of /ARCHIVE/2010, but not the FCID of /ARCHIVE nor /.

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 currently selected folder into another folder (by UID). You cannot copy from a folder having the tag NO-COPY or into a folder with the tag READ-ONLY. Note: For copying a folder the client must use CPYF. Examples:

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):

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 currently selected folder ACLs. Examples:

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:

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:

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:

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:

Name: exit Arguments: none Result: 200 Description: Return the server to the Not-authenticated State. Example:

Name: find entries and returns how many entries matched the filter Argument: filter* 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 currently selected folder (no subfolders) that correspond to a filter and return the number of matched items. 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 0 and the 220 code. If there is no match for the filter then it is returned 0 and the 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:

Name: find and copy entries 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 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 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:

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 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. 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:

Name: find entries Argument: filter* 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 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:

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 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). Examples:

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

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. 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: S: 200 OK Message stored with UID UIDx1234 into INBOX ]]>

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 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:

Name: get all ACLs for selected folder Arguments: none Result: 200 Result 200 - the command was successful. Description: It returns a list with all defined ACLs for currently selected folder. Examples:

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:

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:

Name: get tag of a folder entry Arguments: UID 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:

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 and ECID , 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 each folder matching the filter is listed together with all its 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 document defines the following flags: 0 - it have no subfolders and no items; 1 - it have no subfolders, but it have items; 2 - it have subfolders, but no items; 3 - it have subfolders and items. Examples:

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 ADDR - it holds contacts; CALE - it holds calendar events; CONF - it holds user's settings for roaming. FILE - it holds normal folders and files; FILT - it holds the results of a filter defined by the user (there can be only one filter per folder); FOLD - it contains only subfolders; JRNL - it holds a journal; NOTE - it holds user's notes; MESG - it holds messages; 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:

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:

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:

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:

Name: noop Arguments: none Result: 200 Description: It does nothing (eventually announce what changes was done in current folder). Example:

Name: fetch presence information Arguments: USER user|BUSY user|FREE user|UID uid user 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 or the uid was found and returned. Result 510 - unknown/unsupported command or not found uid. Result 511 - unknown/unsupported/missing arguments. Description: Fetch information about an user current availability, checks when an user is busy or free and returns the event entries. 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. 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 followed by the UID correspondig to the event associated with this time period. In case there is no time period specified a 511 error is returned by server. Note: If there is present an argument UID then it is returned its associated content only if it is of type VEVENT. Examples:

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: .20110607T170000Z-20110531T114600Z-123456@agap.at S: . ]]>

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 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:

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 or FILE. Description: Fetch from server information about the message or file entry 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. RETC returns for an file its size in bytes instead of its content as RETR. Examples:

...

S: . S: .cid:A12 S: .123456 S: . S: . S: 200 OK RETC completed ]]>

S: .file-test.txt S: .123456 S: . S: 200 OK RETC completed ]]>

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 as it is returned by RETR or RETC and must point to a not binary end leaf. It contains only tag names separated 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. Examples:

...

... 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 ]]>

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:

Name: select a folder Argument: path Result: 200 510 511 Result 200 - the folder was successfully selected. Result 510 - unknown/unsupported command. Result 511 - unknown path 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:

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. Description: Set or delete tags associated to an item. Examples:

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 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 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: ADDR - TOTAL; CALE - TOTAL; CONF - TOTAL. FILE - TOTAL; FILT - TOTAL; FOLD - none; JRNL - TOTAL; MESG - TOTAL and NEW; NOTE - TOTAL; TASK - TOTAL; Examples:

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:

...

... 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 ]]>

...

... C: S: 410 Cannot store it, not enough space ]]>

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 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:

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: 1xx: Informational - Server waits for request continuation or send unrequested data; 2xx: Success - The action was successfully executed; 4xx: Server Error - The server failed to perform the request, retry later; 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 (.).

Reserved.

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.

The request was successfully processed.

The request was successfully applied for at least one item but not for all requested items. (see FCPY, FDEL, FMOV, and FTAG)

The request was successful, but none of the arguments were found. (see DACl, DPBL)

Reserved.

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

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).

Reserved.

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

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.

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.)

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.)

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

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.)

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

PASS: 510 511 512 PASS password: 200 511 512 QUIT: 200 USER: 510 511 USER account: 200 511 other: 510

HASH: 510 511 512 HASH hashcode: 200 511 512 QUIT: 200 USER: 510 511 USER account: 200 511 other: 510

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 DELE: 510 511 DELE arguments: 200 511 DELF: 510 511 DELF arguments: 200 511 EXIT: 200 FCNT: 110 FCNT arguments: 200 220 511 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 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 STAG: 510 511 STAG arguments: 200 410 511 STAT: 200 512 STOR: 110 200 410 511 SUID: 200 511 other: 510

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

PGET: 510 511 PGET arguments: 200 510 511 QUIT: 200 other: 510

FSTO: 510 FSTO arguments: 110 200 410 510 511 541 QUIT: 200 other: 510

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 ]]>

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 ]]>

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 ]]>

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) ]]>

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) ]]>

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) ]]>

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 ]]>

/My/AFolder ]]>