Skip to content
Optiwork API Docs

List folders

GET
/mail/mailboxes/{mailbox}/folders
curl --request GET \
  --url https://mail.work.optidata.cloud/api/mail/mailboxes/78/folders \
  --header 'Authorization: Bearer <token>'

The whole folder tree of the mailbox, standard folders first, each with its nested subfolders and its unread and total message counts. Folders other users have shared with the caller appear with their shares populated.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
mailbox
required
integer

Id of the mailbox. Every mailbox the caller may use is listed in their account.

Responses

Section titled “ Responses ”

200

Section titled “200”

The folder tree.

Media typeapplication/json
Array<object>

A folder of a mailbox.

object
id

Id of the folder.

string | integer
uuid
string format: uuid
name
string
path

Full path from the mailbox root.

string
role

What a folder is for. Custom marks a folder the user created; the others are the standard folders of a mailbox.

string
Allowed values: Inbox Snoozed Sent Drafts Archives Junk Trash Custom Important Scheduled SharedWithMe
rgb

Colour, as a hex triplet.

string | null
parentId
string | integer | null
parentUuid
string | null
unreadMessages
integer
totalMessages
integer
sizeBytes
integer
isDeletable

false for the standard folders.

boolean
isTrashFolder
boolean
subfolders
Array<object> recursive
shares

Sharing grants on this folder.

Array<object>
object
Examples
Exampletree
[
  {
    "id": "2",
    "uuid": "fd431533-6039-4ee2-86e1-c8f854e8c15a",
    "name": "Inbox",
    "path": "Inbox",
    "role": "Inbox",
    "rgb": null,
    "parentId": "1",
    "parentUuid": "467ce5ad-84c6-4825-889b-9a28e96bbe4a",
    "unreadMessages": 3,
    "totalMessages": 596,
    "sizeBytes": 131979163,
    "isDeletable": false,
    "isTrashFolder": false,
    "shares": [],
    "subfolders": [
      {
        "id": "416",
        "uuid": "9471a72e-fa9f-4d48-ba3b-1aca4bc49bea",
        "name": "Suppliers",
        "path": "Inbox/Suppliers",
        "role": "Custom",
        "rgb": null,
        "parentId": "2",
        "parentUuid": "fd431533-6039-4ee2-86e1-c8f854e8c15a",
        "unreadMessages": 0,
        "totalMessages": 12,
        "sizeBytes": 20481,
        "isDeletable": true,
        "isTrashFolder": false,
        "subfolders": [],
        "shares": []
      }
    ]
  }
]

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The caller may not act on this mailbox, user or resource.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Exampledenied
{
  "message": "This action is unauthorized."
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}

502

Section titled “502”

The mail platform did not answer as expected — a folder or message that does not exist, or a transient failure. reference is the code to quote to support and fault_code names the underlying condition. A 503 with the same envelope means the platform is in maintenance; retry shortly.

Media typeapplication/json

Failure raised by the mail platform behind the API rather than by the request itself.

object
error
required

What went wrong, phrased for the end user.

string
status
required

Repeats the HTTP status code.

integer
help
required

Suggested next step.

string
reference
required

Support reference, e.g. MZ-502.

string
fault_code

Names the underlying condition, e.g. mail.NO_SUCH_FOLDER.

string | null
Examples

Unknown folder

{
  "error": "The mail server did not answer as expected, so this action could not be completed.",
  "status": 502,
  "help": "If the problem persists, contact support and inform the error code above.",
  "reference": "MZ-502",
  "fault_code": "mail.NO_SUCH_FOLDER"
}