Access to the mail account becomes available after a
    succesful "\SMAP1 LOGIN" or
    "\SMAP1 AUTHENTICATE" command. A
    mail account contains a list of folders. A folder contains a
    list of individual messages. A folder may also contain other
    folders (so-called "subfolders") instead. A folder that
    contains subfolders is called a "folder directory". Subfolders
    may also contain other subfolders, and so on.
Some SMAP servers are capable of creating hybrid folders that contain both messages and other subfolders, but SMAP clients should not depend on the server's ability to create such folders.
SMAP folders are referenced by listing the folder's name,
    the name of its parent folder (if any), then the name of the
    parent folder's parent folder, and so on. The name of the top
    level folder is listed first, and the name of the folder itself
    is listed last, and each folder's name is specified as a
    separate, whitespace-delimited word. Some SMAP1 commands mark the end of the sequence of
    words that identifies a folder by an extra, empty word (folder
    names cannot be empty themselves). For example, the command to
    create a folder called "December" as a subfolder of another
    folder called "2002", which itself is a subfolder of a folder
    called "Important Mail" is:
      CREATE "Important Mail" 2002 December
      
Folder names are written using the UTF-8 character set; they may contain any UTF-8 character except for U+0000 through U+001F.
SMAP servers may allow clients to create top-level folder or folder directories. SMAP servers may also prohibit clients from creating top-level folder or folder directories; instead, they provide a predefined list of top-level folder directories, such as "Private Folders" and "Public Folders", and SMAP clients are directed to to create subfolders under either top level folder directory. Servers that have this restriction should reject attempts to create top-level folders with an informative error message.
        C: CREATE "Private Folders" Todo-List
        S: +OK Folder created
        C: MKDIR Customers
        S: -ERR Folders may not be created here.  Please create a folder in
           "Private Folders" or "Public Folders".
        
The CREATE command creates a
      new folder. The MKDIR command
      creates a new folder directory (a folder that contains other
      folders). The remaining words specify the name of the new
      folder or folder directory.
An SMAP client should not create a new folder directory
        until it is ready to create its first subfolder. The
        MKDIR command should be
        immediately followed by a CREATE command that creates the first
        subfolder in the new folder directory. Empty folder
        directories serve no particular purpose; SMAP servers are
        permitted (but not required) to omit empty folder
        directories when responding to a LIST command. An SMAP client that wishes
        to create a new folder directory now, and a subfolder some
        time later should be implicitly aware of the fact that it
        created a new folder directory even if a subsequent
        LIST command does not reveal
        its presence.
Some SMAP servers can implement hybrid folders that
      contain both folders and subfolders. Clients must explicitly
      use both CREATE and MKDIR commands, which may be used in either
      order. It is possible that hybrid-capable servers do not
      differentiate between the MKDIR
      and CREATE commands. Either one
      creates a folder that's ready to hold messages or subfolders.
      These servers must ignore a duplicate request to create an
      existing folder or folder directory (normally a server SHOULD
      reject such a request). This is because SMAP clients will
      send both command because they cannot rely on this
      behavior.
Use CREATE to create
              a folder, MKDIR to
              create a folder directory.
Clients should create new folder directories just prior creating their first subfolder. Clients should not create new folder directories until they are ready to create the first subfolder.
SMAP servers may ignore MKDIR, and treat it as a no-op, and
              automatically create logical folder directories on
              as-needed basis.
        C: DELETE "Private Folders" Todo-List
        S: +OK Folder deleted
        C: RMDIR Customers
        S: +OK Folder directory deleted
        
The DELETE and RMDIR commands are the opposite of
      CREATE and MKDIR commands. They delete the indicated
      folder or folder directory. Some SMAP servers may
      automatically remove a folder directory after its last
      subfolder is deleted. Normally a server should reject a
      request to remove a non-existent folder or folder directory.
      Servers that automatically remove empty directories should
      not reject requests to remove a non-existent directory, they
      should ignore and accept the request, but do nothing. The
      request to remove a non-existent directory is probably
      initiated by a client that just removed the last subfolder;
      the client cannot assume that the server will delete the
      empty directory, so it explicitly asks the server to do
      that.
        C: RENAME "Dr. Jekyll" "" "Mr. Hyde"
        S: +OK Folder renamed.
        C: RENAME "Saved Mail" "Tomorrow's To-Do List" "" "Saved Mail" "To-Do Today"
        S: +OK Folder renamed.
The RENAME command changes
      the name of an existing folder or folder directory. The
      command is followed by a whitespace-delimited word list that
      specifies an existing folder; then an empty word; then
      another whitespace-delimited word list which specifies a new
      name for the folder or folder directory. Both the old name,
      and the new name, must be complete folder name paths.
The first example above renames a folder named "Dr. Jekyll" to "Mr. Hyde". The second example renames a subfolder of "Saved Mail" named "Tomorrow's To-Do List" as "To-Do Today". Most SMAP servers can move a folder/subfolder to a different parent folder. This is done by specifying a different path for the new name.
Both folder and folder directories may be renamed. A renamed folder directory's subfolders "follow along" with their parent folder directory.
        C: LIST
        S: * LIST INBOX "New Mail" FOLDER
        S: * LIST Drafts Drafts FOLDER
        S: * LIST "Saved Mail" "Saved Mail" DIRECTORY
        S: +OK Here are your folders
        C: LIST "Saved Mail"
        S: * LIST 2001 2001 DIRECTORY
        S: * LIST 2002 2002 DIRECTORY
        S: +OK Here are your folders
        C: LIST "Saved Mail" 2002
        S: * LIST February February FOLDER
        S: * LIST January January FOLDER
        S: +OK Here are your folders
        
The LIST command, without any
      arguments, returns a list of top level folders. A list of
      subfolders of an existing folder directories is returned by
      appending the folder name path to the LIST command.
The server responds with zero or more “* LIST” single line replies, one reply for each folder or folder directory. The next word after “* LIST” is the name of the folder or folder directory. The following word (called "description") is usually the same as the name of the folder. Certain reserved folders may have a different description (see below). The remaining words contain keywords that describe the folder's attributes. The following attributes are defined at this time:
FOLDERThis is a regular folder that contains messages.
READONLYThis is a read-only folder.
DIRECTORYThis is a folder directory that contains other folders.
Every “*
      LIST” reply includes either FOLDER or DIRECTORY. Both attributes indicate a hybrid
      folder - a folder that contains both messages and
      subfolders.
Some SMAP servers may not allow clients to create new top-level folders. Instead, they provide a fixed set of top-level folders and folder directories, such as "INBOX", "private", and "public". Clients can only create new subfolders of the reserved folder directories. Other servers may do both: provide a fixed set of reserved, top-level folders, and allow clients to create new top-level folders.
A reserved folder is generally a symbolic representation for a special folder, or a folder directory, with a pre-defined purpose. The most common example would be the mail folder where new mail arrives; it is typically called “INBOX”. Reserved folders usually have brief, curt names, such as “INBOX”, “public”, or “private”. An SMAP server can offer a more meaningful description using the description word in the “* LIST” reply; for example: “New Mail”, “Public Folders”, or “My Folders”. If the client selects a different natural language, at login time, the server can provide a description in the selected language, but still use the same actual folder name.
SMAP clients should always use the official folder name, when referencing the folder in any SMAP command, and display the folder's description to the user (recall that for regular folders they are one and the same).
        C: STATUS FULL "Saved Mail"
        S: * STATUS EXISTS=17 UNSEEN=5
        S: +OK Status retrieved
The STATUS command returns
      the status of a folder. The next word after “STATUS” is a
      comma-delimited list of the following keywords. The remaining
      whitespace-delimited words specify a folder whose requested
      status should be returned.
The first word following “STATUS” contains a
      comma-delimited keyword list. The following keywords are
      defined at this time. Additional keywords may be added in the
      future. SMAP server should ignore keywords they do not
      recognize.
Request the number of messages in the folder (sent
            as the “EXISTS” response),
            and the number of messages that do not have the
            SEEN flag set (the
            “UNSEEN”
            response).
Same as FULL but return
            the message counts only if the server is capable of
            calculating the message counts cheaply and without
            delay. This keyword is mutually-exclusive with
            FULL. If the message
            counts cannot be calculated cheaply, the “* STATUS” response
            is not sent, but the server still responds with an
            “+OK”.
The server's “*
      STATUS” reply gives the requested
      message counts.
Access Control Lists (or “ACL”s) may be optionally implemented by an SMAP server. ACLs are usually implemented by servers that support shared folder access, where accounts may mutually share access to their folders, and ACLs specify which accounts may access which folders. ACLs define certain level of granularity; for example an ACL may specify that a given account may read messages in the folder, but not delete them, or add messages to the folder.
An SMAP server which implements ACLs will include
      “ACL2=method”
      in its capability list. “Method” is the server's method
      for computing ACLs (see below).
Each folder maintains a separate access control list, which applies to that folder only. An access control list consists of zero or more records. Each record contains two data items: an identifier, and rights. “Rights” is a list of zero more characters, that enumerate which kinds of access rights are given to the entity specified by the “identifier”. An identifier may take the following values:
anyoneThe access rights apply to all server accounts.
anonymousThis is an alias for “anonymous”.
user=idThe access rights apply to account named
              “id”. The account name is
              specified using the UTF-8 character set.
group=idThe access rights apply to a group of accounts
              named “id”. The group name is
              specified using the UTF-8 character set. Account groups
              are site-specific lists, maintained in a site-defined
              manner. Each SMAP server implementation needs to
              specify separately the nature and the names of the
              available account groups (if they exist at all).
Access rights are specified using a list of zero or more characters, as follows:
aAdminister this folder. Maintain this folder's ACLs.
cCreate subfolders.
eRemove messages from this folder (the EXPUNGE and the MOVE commands).
iInsert messages into this folder (COPY or MOVE messages to this folder, and
              the ADD command).
lList this folder. This folder is visible, and is
              shown by the LIST
              command.
rRead, or open this folder (the OPEN or the SOPEN command).
sAdd or remove the SEEN flag on messages.
tAdd or remove the DELETED flag on messages.
wAdd or remove any message flag, except for
              SEEN and DELETED; add and remove
              keywords.
xDelete this folder.
An access control list entry may have an identifier that begins with a dash. This access control list entry specifies a “negative right”, which revokes, rather than adds, the corresponding rights from the identifier. For example, consider the the following access control list:
anyone alr user=fred -r
This ACL gives access, list, and read privileges to
        everyone, and revokes read privileges from the fred user. Presumably, everyone except
        fred can administer, list, and read the folder; while fred
        can only administer and read it.
As hinted in the previous example, there may be more than one access control list entry that's applicable to a given user. The SMAP server needs to compute the actual access rights for a folder based on all applicable access control list entries. There are several approaches to do that. The SMAP server declares its chosen method of access rights computation using the “ACL2” capability. At this time, two access computation methods are defined:
Access rights from all applicable ACL entries are combined together, then, all negative rights from all applicable ACL entries are removed, giving the final result. This is the computation method used in the previous example.
Only access rights from the “most specific” ACL entries are factored in. That is, ACL entries referring specifically to the user (the “user=” ACL entries, and/or “owner” entries) are used, if present. Otherwise, any applicable “group=” entries are used, if present. Otherwise, “anyone” and “anonymous” entries are used by default.
Multiple applicable most-specific entries are combined in the same way as the “union” method.
Here's the equivalent “most-specific” version of the earlier example:
anyone alr user=fred al
          C: ACL INBOX
          S: * ACL "aceilrstwx"
          S: +OK ACL retrieved
The ACL command computes
        the requesting client's access rights on the indicated
        folder. The whitespace-delimited words after “ACL” specify the
        folder whose access rights are computed and returned.
The server responds with a “* ACL” message, which contains a single word that lists the access rights on the given folder.
          C: GETACL INBOX
          S: * GETACL "owner" "aceilrstwx" "user=fred" "ace"
          S: +OK ACLs retrieved
The GETACL command returns
        the access control list for the indicated folder. The
        whitespace-delimited words after “GETACL” specify the
        folder whose access control list is requested.
The server responds with a “*
        GETACL” message. The remaining
        whitespace-delimited words after “*
        GETACL” consist of a zero or
        more identifier/rights pairs. In each pair,
        identifier names
        the identity to which rights apply.
The server may respond with two or more “* GETACL” messages when the access control list is very large.
          C: SETACL INBOX "" user=fred ace
          S: * GETACL "owner" "aceilrstwx" "user=fred" "ace"
          S: +OK Updated ACLs
          C: SETACL INBOX "" user=fred +rwx
          S: * GETACL "owner" "aceilrstwx" "user=fred" "acerwx"
          S: +OK Updated ACLs
          
The SETACL command modifies
        rights for a single access control list identifier. The
        whitespace-delimited words after “SETACL” specify the
        folder whose access control list will be modified. The
        folder's name is followed by a single empty word, the
        identifier, then the requested access rights.
The existing access rights assigned to the identifier are replaced by the new rights specified in the command. If the identifier does not exist in the access control list, it is added with the specified rights.
If the access rights are prefixed by “+”, the specified rights are added to the existing rights, for this identifier. If the access rights are prefixed by “-”, the specified rights are removed from the existing rights, for this identifier. It is not an error to add an access right that already exists, or remove an access right that did not exist; in both cases the request is ignored (for that specific access right).
identifier may
        specify a negative right. When the server uses
        “ACL2=UNION” computation method,
        setting an empty access right list for an identifier will
        remove the identifier from the access control list.
The server responds with zero or more “*
        GETACL” messages, that return
        the updated access control list for this folder.
          C: DELETEACL INBOX "" user=fred
          S: * GETACL "owner" "aceilrstwx"
          S: +OK Updated ACLs
          
The DELETEACL command
        removes an identifier from the access control list. The
        identifier may be a negative right. The whitespace-delimited
        words after “DELETEACL” specify the
        folder whose access control list will be modified. The
        folder's name is followed by a single empty word, than the
        identifier to be removed. It is not an error to name an
        identifier that does not exist, the request is effectively
        ignored (but the server still responds with “*
        GETACL” messages).
The server responds with zero or more “*
        GETACL” messages, that return
        the updated access control list for this folder.