The accounts API describes the MailFolder path as "Path to this folder in the account. Although paths look predictable, never guess a folder’s path, as there are a number of reasons why it may not be what you think it is."

So essentially, developers should treat the path as an opaque token. But then, there is no way to know if a folder is the root folder, what depth it has, etc. The best guess for depth is counting the number of /'s in the path, and the root folder is likely the first folder in the array. If we don't define this now, people are going to be using it in this way.

Also, some important stats are missing such as unread count, total messages, and possibly exposing the sort key in some way so they can be consistently sorted.

(In reply to Philipp Kewisch [:Fallen] [:📆] from comment #0)

The accounts API describes the MailFolder path as "Path to this folder in the account. Although paths look predictable, never guess a folder’s path, as there are a number of reasons why it may not be what you think it is."

So essentially, developers should treat the path as an opaque token. But then, there is no way to know if a folder is the root folder, what depth it has, etc. The best guess for depth is counting the number of /'s in the path, and the root folder is likely the first folder in the array. If we don't define this now, people are going to be using it in this way.

I've said that because in some cases the parts of the path do not match what a human would expect. On Windows, for example, some characters cause the path component to be an 8-character hash of the folder name. Counting the slashes is a valid way to establish depth, assuming the same is true of folder URIs:

function folderURIToPath(uri) {
  let path = Services.io.newURI(uri).filePath;
  return path.split("/").map(decodeURIComponent).join("/");
}

Then I think we either need to provide a getter with the depth, or document this accordingly. Do you feel the current folders structure is the best it can be, or do you think there is something that should be changed if there were more time?

There's a few properties that might be useful to people, like the total message count and unread count. Without having written any add-ons for folders I don't really know what might be wanted.

We should move folder-handling stuff into its own namespace instead of accounts. Since I added the majority in the current version I think it would be okay to rename it without notice.

Folder stats (total messages/ unread messages) will be added in bug 1708644 (together with the corresponding onChange listener).
Hierarchy information is added in bug 1520427