Folders

List folders

Retrieve a list of all IMAP folders/mailboxes for the authenticated alias. This endpoint supports pagination and filtering by subscription status.

get/v1/folders

Request

Base URL: https://api.forwardemail.net
URL: https://api.forwardemail.net/v1/folders
Auth: HTTP basic

Query parameters

pageinteger

Page of results to return. If not specified, value will be 1. Must be a number greater than or equal to 1.

limitinteger

Number of results to return per page. Defaults to 25 if not specified. Must be a number greater than or equal to 1, and less than or equal to 100.

subscribedboolean

Filter folders by subscription status

Response

Folders retrieved successfully

idstring required

Folder ID

pathstring required

Full folder path

namestring required

Folder name (last part of path)

parentstring nullable required

Parent folder path

uid_validityinteger required

IMAP UID validity

uid_nextinteger required

Next UID value

modify_indexinteger required

Modification index

subscribedboolean required

Whether folder is subscribed

flagsstring[] required

Folder flags

retentioninteger nullable required

Message retention period

special_usestring nullable required

Special use designation

created_atstring date-time required

updated_atstring date-time required

object'folder' required

Example response

[
  {
    "id": "folder123",
    "path": "INBOX/Subfolder",
    "name": "Subfolder",
    "parent": "INBOX",
    "uid_validity": 123456,
    "uid_next": 1,
    "modify_index": 1,
    "subscribed": true,
    "flags": [],
    "retention": null,
    "special_use": null,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "object": "folder"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.