Create a folder

POST/api/v1/mailbox/folders
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Creates a folder and answers with the full folder list.

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
400 The mail server refused the name, for example because a folder by that name exists.
422 The name is empty, longer than 255 characters, or contains /, \ or control characters.

Request body

  • namestringrequired

    The new folder's name, up to 255 characters. Not /, \ or control characters.

Request

POST/api/v1/mailbox/folders
curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/folders' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Clients"
  }'

Response

Successful Response

  • dataarray<object>
    • idstring

      A stable id for the folder (a hash of its name).

    • namestring

      The folder's full name; use it as folder in other calls.

    • rolestring or nullinbox | sent | drafts | trash | junk | archive | scheduled | null
    • totalinteger

      Messages in the folder.

    • unreadinteger
    • uid_nextinteger
    • uid_validityinteger
200application/json
{
  "type": "success",
  "msg": "Folder created successfully",
  "data": [
    {
      "id": "7e33429f656f1e6e9d79b29c3f82c57e",
      "name": "INBOX",
      "role": "inbox",
      "total": 1284,
      "unread": 3,
      "uid_next": 4822,
      "uid_validity": 1712345678
    },
    {
      "id": "ad0b7f0a1fb9a8b5bc8cd2e4c4c6f1a2",
      "name": "Sent",
      "role": "sent",
      "total": 412,
      "unread": 0,
      "uid_next": 413,
      "uid_validity": 1712345679
    },
    {
      "id": "3b9c3ed2a7b3d0c4f1e0a4d9b8f7e6c5",
      "name": "Drafts",
      "role": "drafts",
      "total": 2,
      "unread": 0,
      "uid_next": 31,
      "uid_validity": 1712345680
    },
    {
      "id": "9c1f3a0e2b4d5c6e7f8a9b0c1d2e3f40",
      "name": "Clients",
      "role": null,
      "total": 87,
      "unread": 0,
      "uid_next": 88,
      "uid_validity": 1712345690
    }
  ]
}

Returned inside the standard envelope.

Errors

StatusWhen
400The mail server refused the name, for example because a folder by that name exists.
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
422The name is empty, longer than 255 characters, or contains `/`, `\` or control characters.

Every status, with what causes it and what to do, is on the error reference.