Rename a folder

PATCH/api/v1/mailbox/folders/{folder}
Requires amailbox token— it acts as one mailbox holder, not as the organization.

{folder} is the folder's id from GET /folders. Inbox and the special folders (Sent, Drafts, Junk, Trash, Archive) cannot be renamed.

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 new name (for example, it is taken).
409 A special folder: error_code: cannot_rename_special_folder.

Parameters

NameInTypeDescription
folderrequiredpathstring

Request body

  • namestringrequired

    The new name.

Request

PATCH/api/v1/mailbox/folders/{folder}
curl -X PATCH 'https://courier.mailyte.com/api/v1/mailbox/folders/01JBT8XQ2M9WYC3K4F6R7S8T9V' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Clients (2026)"
  }'

Response

Successful Response

  • dataobject
    • idstring
    • namestring
    • foldersarray<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 renamed",
  "data": {
    "id": "1f2e3d4c5b6a79880716253443526170",
    "name": "Clients (2026)",
    "folders": [
      {
        "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 new name (for example, it is taken).
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`.
409A special folder: `error_code: cannot_rename_special_folder`.
422Validation Error

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