diff --git a/doc/folders.rst b/doc/folders.rst
index 3682c66..9f4b0c7 100644
--- a/doc/folders.rst
+++ b/doc/folders.rst
@@ -1,237 +1,242 @@
 ============
 ``/folders``
 ============
 
 ``GET /folders``
 ================
 
 Request a full list of folders.
 
 **Example Result**
 
 .. parsed-literal::
 
     [
         (...)
         {
             "fullpath": "Calendar",
             "name": "Calendar",
             "type": "event.default",
             "uid": "6c11cd1e5283576e"
         },
         {
             "fullpath": "Calendar/Personal",
             "name": "Personal",
             "parent": "6c11cd1e5283576e",
             "type": "event",
             "uid": "2faf3307-7d32-4d22-bb1b-9a8a40fb3872"
         },
         (...)
         {
             "fullpath": "Drafts",
             "name": "Drafts",
             "type": "mail.drafts",
             "uid": "16dd16e25283576d"
         },
         (...)
         {
             "fullpath": "INBOX",
             "name": "INBOX",
             "type": "mail.inbox",
             "uid": "169aad0b52725a31"
         },
         (...)
         {
             "fullpath": "Sent",
             "name": "Sent",
             "type": "mail.sentitems",
             "uid": "5deaff235283576d"
         },
         {
             "fullpath": "Spam",
             "name": "Spam",
             "type": "mail.junkemail",
             "uid": "5df585705283576e"
         },
         (...)
         {
             "fullpath": "Trash",
             "name": "Trash",
             "type": "mail.wastebasket",
             "uid": "0e307e915283576e"
         }
     ]
 
 .. NOTE::
 
     The response includes properties that can be filtered. For example,
     ``GET /folders?properties=name`` will return only the names of the
     folders.
 
 .. NOTE::
 
     This API call requires the client to filter the folders by type.
 
 ``GET /folders/<folder-uid>``
 =============================
 
 Get information about a specific folder.
 
 **Example**
 
 ``GET /folders/169aad0b52725a31``
 
 .. parsed-literal::
 
     {
         "fullpath": "INBOX",
         "name": "INBOX",
         "type": "mail.inbox",
         "uid": "169aad0b52725a31"
     }
 
 .. NOTE::
 
-    This call should include additional metadata about the folder contents;
+    The response includes properties that can be filtered. For example,
+    ``GET /folders/169aad0b52725a31?properties=name`` will return only the names of the
+    folders.
+
+.. NOTE::
 
-    *   recent,
-    *   unread,
-    *   total objects
+    The API supports additional folder metadata, but for performance reasons
+    that isn't returned by default and have to be requested using ``properties``
+    argument. Supported extra properties are: exists, unseen, unread, highestmodseq,
+    uidvalidity, size, deleted, children.
 
 ``DELETE /folders/<folder-uid>``
 ================================
 
 Delete a folder
 
 ``POST /folders``
 =================
 
 Create a folder.
 
 **Example**
 
 ``POST /folders -d '{"name":"Test"}'``
 
 .. parsed-literal:
 
     {
         "uid": "92ba0f35-40fe-4d0c-9b2a-81052e4e2cec"
     }
 
 ``POST /folders/<folder-uid>/deleteobjects``
 ============================================
 
 Delete selected objects from the folder. Supply a list of object UIDs.
 
 **Example**
 
 ``POST /folders/169aad0b52725a31/deleteobjects`` with ``[112,113]`` will delete objects 112 and 113.
 
 ``POST /folders/<folder-uid>/empty``
 ====================================
 
 Clear out the contents of the folder.
 
 ``POST /folders/<folder-uid>/move/<folder-uid>``
 ================================================
 
 Move objects to another folder. The first folder uid is the source, the second folder uid the target.
 
 Supply a list of object uids to move.
 
 ``HEAD /folders/<folder-uid>``
 ==============================
 
 Verify the folder exists.
 
 ``PUT /folders/<folder-uid>``
 =============================
 
 Update the folder properties.
 
 ``GET /folders/<folder-uid>/folders``
 =====================================
 
 Retrieve a list of sub-folders, if any.
 
 ``HEAD /folders/<folder-uid>/folders``
 ======================================
 
 Retrieve the number of sub-folders (as an ``X-Count`` response header value).
 
 ``GET /folders/<folder-uid>/objects``
 =====================================
 
 Obtain a list of objects in the folder specified with ``uid``.
 
 **Example**
 
 ``GET /folders/169aad0b52725a31/objects``
 
 .. parsed-literal::
 
     [
         (...)
         {
             "bcc": [],
             "categories": [],
             "cc": [],
             "date": "Mon,  4 Sep 2017 01:09:20 +0100",
             "flags": [
                 "seen"
             ],
             "from": {
                 "address": "noreply_support@comodo.com",
                 "name": "Comodo Security Services"
             },
             "has-attach": false,
             "internaldate": " 4-Sep-2017 02:16:09 +0200",
             "message-id": "mid:44",
             "reply-to": [],
             "sender": [],
             "size": 2332,
             "subject": "Comodo Domain Validation for \*.kolab.org",
             "to": [
                 {
                     "address": "administrator@kolab.org",
                     "name": "administrator@kolab.org"
                 }
             ],
             "uid": "112"
         },
         (...)
     ]
 
 ``HEAD /folders/<folder-uid>/objects``
 ======================================
 
 Retrieve an object count (as an ``X-Count`` response header value).
 
 ``POST /folders/<folder-uid>/search``
 =====================================
 
 Search objects in the folder specified with ``uid``. Supported search
 fields for mail search are: TEXT, BODY, and any header name. For other
 object types it depends on the object type, e.g. for contact data
 you can use: firstname, surname, name, email, tags.
 
 .. NOTE::
 
     The response includes properties that can be filtered. For example,
     ``POST /folders/169aad0b52725a31/search?properties=uid`` will return only the uids of
     objects.
 
 **Example**
 
 ``POST --data '{"subject":"valid"}' /folders/169aad0b52725a31/search?properties=subject,uid``
 
 .. parsed-literal::
 
     [
         (...)
         {
             "subject": "Domain Validation",
             "uid": "112"
         },
         (...)
     ]