Retrieving Folders

To retrieve folders from an IMAP mailbox, you may use the folders() method on the Mailbox instance.

This method returns a FolderRespository instance, which provides operations for retrieving, creating, and managing folders:

use DirectoryTree\ImapEngine\Mailbox;

$mailbox = new Mailbox([
    // ...
]);

// Get all folders.
$folders = $mailbox->folders()->get();

// Get folders matching a glob pattern.
$folders = $mailbox->folders()->get('*/Subfolder');

Getting a Specific Folder

To retrieve a specific folder, you may use the find() method on the FolderRepository instance:

// Get the inbox folder.
$inbox = $mailbox->inbox();

// Find a specific folder by name.
$folder = $mailbox->folders()->find('Sent');

// Find a folder or fail (throw an exception).
$folder = $mailbox->folders()->findOrFail('Important');

Creating Folders

You may create a new folder using the create() method:

$folder = $mailbox->folders()->create('Archive');

To create a nested folder, separate the parent and child folder names with your IMAP server’s folder delimiter:

$nestedFolder = $mailbox->folders()->create('Parent/Child');

Folder Properties

Once you have a Folder instance, you may retrieve various properties:

$folder = $mailbox->folders()->find('Inbox');

// Get the root folder name (excluding parent folders, e.g. "Inbox").
$name = $folder->name();

// Get the full folder path (e.g. "Inbox/Archive").
$path = $folder->path();

// Get the folder delimiter (e.g. "/").
$delimiter = $folder->delimiter();

Deleting Folders

To delete a folder, call the delete() method on the Folder instance:

$folder->delete();

Renaming / Moving Folders

To rename a folder, use the move() method on the Folder instance:

$folder->move('NewName');

Working with Subfolders

You may retrieve subfolders of a folder using the get() method on the FolderRepository instance:

// Get a specific subfolder.
$subfolder = $mailbox->folders()->find('Parent/Child');

// List all subfolders within a parent.
$subfolders = $mailbox->folders()->get('Parent/*');

Selecting a Folder

If you already have a Folder instance, you may explicitly select it on the IMAP server:

$folder->select();

// Or force re-selection
$folder->select(true);

Selecting a folder tells the server that you want to work with the messages within that folder.

Checking Folder Capabilities

To inspect the IMAP capabilities advertised while working with a folder, call capabilities():

$capabilities = $folder->capabilities(); // array

if (in_array('IDLE', $capabilities, strict: true)) {
    // Server supports IDLE for this mailbox.
}

This method proxies to the mailbox's capability list, letting you verify support for features like IDLE, MOVE, or QUOTA without leaving the folder API.

Checking Folder Status

You may retrieve status information for a folder, such as the number of messages, recent messages, and unseen messages:

$status = $folder->status(); // array

This data includes various IMAP-defined keys (e.g. MESSAGES, RECENT, UIDNEXT, etc.).

Retrieving Folder Quotas

If your IMAP server exposes storage limits, you may inspect them through the quota() method:

$quotas = $folder->quota(); // array

Each entry is keyed by the quota root (for example, "ROOT"), followed by quota resources such as STORAGE or MESSAGE. The usage value represents the current consumption, while limit describes the maximum allocation reported by the server:

[
    'ROOT' => [
        'STORAGE' => [
            'usage' => 42,   // Current usage in kilobytes.
            'limit' => 1024, // Maximum storage limit in kilobytes.
        ],
    ],
]

ImapEngine will throw an exception if the connected server does not advertise the QUOTA capability.

Examining a Folder

Examining a folder retrieves additional details in a read-only manner:

$details = $folder->examine(); // array

Use examine() if you want to inspect a folder’s metadata without marking messages as read.

Expunging Messages

After marking a message for deletion via $message->delete(), you may call expunge on the folder to permanently remove them.

When a folder is expunged, the IMAP server removes all messages marked for deletion:

use DirectoryTree\ImapEngine\Message;

// Get the inbox folder.
$inbox = $mailbox->inbox();

// Get all messages in the inbox.
$messages = $inbox->messages()->get();

// Mark each message for deletion.
$messages->each(
    fn (Message $message) => $message->delete()
);

// Permanently remove the deleted messages.
$folder->expunge();

Alternatively, you may pass in true into the first parameter of the delete() method on the Message instance to expunge the message immediately:

$message = $inbox->messages()->first();

// Immediately delete and expunge the message.
$message->delete(expunge: true);