DirectoryTree ImapEngine

https://github.com/directorytree/imapengine
Admin
ImapEngine is a fully-featured IMAP library that provides a simple API for managing mailboxes...
Tokens:132,033
Snippets:1,376
Trust Score:9.2
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install ImapEngine via Composer

Source: https://github.com/directorytree/imapengine/blob/master/readme.md

Use this command to install the ImapEngine package in your project.

```bash
composer require directorytree/imapengine
```

--------------------------------

### all() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates retrieving all messages from a folder.

```php
$all = $folder->messages()->all()->get();
```

--------------------------------

### toArray() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Example of retrieving the folder array representation.

```php
$data = $folder->toArray();
// ['path' => 'INBOX', 'flags' => [...], 'delimiter' => '/']
```

--------------------------------

### jsonSerialize() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Example of encoding the folder object to JSON.

```php
echo json_encode($folder);
```

--------------------------------

### flag() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of adding and removing flags.

```php
$message->flag(ImapFlag::Flagged, '+');
$message->flag('\Custom', '-');
```

--------------------------------

### uid() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates filtering messages by UID range or from a starting UID.

```php
// Messages from UID 1000 to 2000
$messages = $folder->messages()->uid(1000, 2000)->get();

// Messages from UID 1000 onwards
$messages = $folder->messages()->uid(1000, INF)->get();
```

--------------------------------

### List all folders

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Retrieve and iterate through all available folders in the mailbox.

```php
$folders = $mailbox->folders()->get();

foreach ($folders as $folder) {
    echo $folder->path();
    echo $folder->name();
    echo implode(', ', $folder->flags());
}
```

--------------------------------

### paginate() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates how to use the paginate method and display pagination links.

```php
$paginator = $folder->messages()->paginate(20);
echo $paginator->links();
```

--------------------------------

### quota() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Demonstrates retrieving quota data and iterating through resource usage percentages.

```php
$quota = $folder->quota();
// [
//   'STORAGE' => [
//       'usage' => 1024000,  // bytes
//       'limit' => 10485760, // bytes
//   ]
// ]

foreach ($quota as $resource => $info) {
    $percent = ($info['usage'] / $info['limit']) * 100;
    echo "$resource: " . round($percent) . "% used";
}
```

--------------------------------

### move() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of moving a message to the Trash folder.

```php
$message->move('Trash');
```

--------------------------------

### each() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates iterating over messages with a custom chunk size.

```php
$folder->messages()->each(function ($message, $key) {
    echo "$key: " . $message->subject();
    // Return false to break early
}, chunkSize: 50);
```

--------------------------------

### Create folders

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Create a new folder or ensure one exists using firstOrCreate.

```php
// Create a single folder
$mailbox->folders()->create('Projects/2024');

// Create if doesn't exist
$archive = $mailbox->folders()->firstOrCreate('Archive/2024');
```

--------------------------------

### Example Mailbox::make() usage

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Shows the factory method in action with a basic configuration array.

```php
$mailbox = Mailbox::make([
    'host' => 'imap.example.com',
    'username' => 'user@example.com',
    'password' => 'password',
]);
```

--------------------------------

### __toString() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of converting a message to a string and saving it to a file.

```php
$full = (string) $message;
file_put_contents('message.eml', $full);
```

--------------------------------

### chunk() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates processing messages in chunks of 100.

```php
$folder->messages()->chunk(function ($chunk, $page) {
    // Process entire batch
    echo "Processing page $page with " . count($chunk) . " messages";
    
    foreach ($chunk as $message) {
        // ...
    }
}, chunkSize: 100);
```

--------------------------------

### is() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of comparing two messages.

```php
if ($message1->is($message2)) {
    echo "Same message";
}
```

--------------------------------

### Flag operations example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example usage of flag checking and setting methods.

```php
if ($message->isSeen()) {
    echo "Message has been read";
}

$message->markFlagged();
if ($message->hasFlag('\Flagged')) {
    echo "Message is flagged";
}
```

--------------------------------

### copy() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of copying a message to the Archive folder.

```php
$newUid = $message->copy('Archive');
```

--------------------------------

### restore() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of restoring a deleted message.

```php
$message->restore();
```

--------------------------------

### limit() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates how to use the limit method to fetch specific pages of messages.

```php
$page1 = $folder->messages()->limit(10, 1)->get();
$page2 = $folder->messages()->limit(10, 2)->get();
```

--------------------------------

### Example Mailbox configuration

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Demonstrates creating a Mailbox instance with specific connection settings like host, port, and credentials.

```php
$mailbox = new Mailbox([
    'host' => 'imap.gmail.com',
    'port' => 993,
    'username' => 'user@gmail.com',
    'password' => 'app-password',
    'encryption' => 'ssl',
    'timeout' => 30,
]);
```

--------------------------------

### Get all top-level MIME parts with parts()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/body-structure.md

Retrieves all top-level MIME parts from the message structure. The example iterates through the parts and outputs their content type.

```php
public function parts(): BodyStructurePart[]
```

```php
$structure = $message->bodyStructure();
$parts = $structure->parts();

foreach ($parts as $part) {
    echo $part->contentType();
}
```

--------------------------------

### from() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates filtering messages from a specific email address.

```php
$fromUser = $folder->messages()->from('user@example.com')->get();
```

--------------------------------

### DraftMessage Usage Example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/types.md

Demonstrates creating a new message and appending it to the inbox.

```php
$draft = new DraftMessage(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello',
    html: '<p>This is HTML</p>',
    text: 'This is plain text',
    attachments: ['/path/to/file.pdf'],
);

$rfc822 = (string) $draft;
$mailbox->inbox()->messages()->append($rfc822, ImapFlag::Seen);
```

--------------------------------

### markAsRead() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates fetching unseen messages and marking them as read.

```php
$messages = $folder->messages()
    ->unseen()
    ->markAsRead()
    ->get();
// Messages are now marked as read
```

--------------------------------

### Address Usage Example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/types.md

Retrieves email and name information from a message sender.

```php
$from = $message->from();
echo $from->email();  // user@example.com
echo $from->name();   // John Doe
```

--------------------------------

### Connect to a Mailbox

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Initialize a new Mailbox instance with connection credentials and establish the connection.

```php
$mailbox = new Mailbox([
    'host' => 'imap.gmail.com',
    'port' => 993,
    'username' => 'user@gmail.com',
    'password' => 'app-password',
]);

$mailbox->connect();
```

--------------------------------

### capabilities()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Get the list of capabilities supported by the IMAP server.

```APIDOC
## capabilities(): array

### Description
Get the list of capabilities supported by the IMAP server (RFC 9051 §6.1.1).

### Returns
- **string[]** - Array of capability names
```

--------------------------------

### delete() method example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Example of deleting a message with immediate expunge.

```php
$message->delete(expunge: true);
```

--------------------------------

### idle() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Shows basic usage with a callback and timeout, as well as usage with a query modifier to filter notifications.

```php
$folder->idle(
    callback: function (MessageInterface $message) {
        echo "New message from: " . $message->from()?->email();
    },
    timeout: 600  // 10 minutes
);

// With query modifier
$folder->idle(
    callback: fn($msg) => echo $msg->subject(),
    query: fn($q) => $q->flagged(),  // Only notify on new flagged messages
    timeout: fn() => time() + 3600   // Timeout at specific time
);
```

--------------------------------

### Implement Custom Logger Class

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

An example of creating a custom logger class implementing LoggerInterface and using it in the Mailbox configuration.

```php
use DirectoryTree\ImapEngine\Connection\Loggers\LoggerInterface;

class DatabaseLogger implements LoggerInterface
{
    public function log(string $message, string $direction = 'sent'): void
    {
        DB::table('imap_logs')->insert([
            'message' => $message,
            'direction' => $direction,
            'created_at' => now(),
        ]);
    }
}

// Use it
$mailbox = new Mailbox([
    'debug' => DatabaseLogger::class,
]);
```

--------------------------------

### get()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Executes the query and retrieves a collection of all matching messages.

```APIDOC
### get()

#### Description
Executes the query and returns all matching messages as a collection.

#### Returns
- **MessageCollection** - A collection of Message objects.
```

--------------------------------

### Capability-Aware Operations

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Perform operations based on server capabilities. This example demonstrates using server-side sorting if available, otherwise falling back to client-side sorting.

```php
$mailbox = new Mailbox($config);
$caps = $mailbox->capabilities();

if (in_array('SORT', $caps)) {
    $messages = $folder->messages()
        ->orderBy(ImapSortKey::Date, 'desc')
        ->get();
} else {
    // Fall back to client-side sorting
    $messages = $folder->messages()
        ->get()
        ->sortByDesc(fn($m) => $m->date()?->timestamp);
}
```

--------------------------------

### find() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates finding a message by UID or message number.

```php
use DirectoryTree\ImapEngine\Enums\ImapFetchIdentifier;

$message = $folder->messages()->find(12345);
// Or by message number
$message = $folder->messages()->find(5, ImapFetchIdentifier::MessageNumber);
```

--------------------------------

### poll() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Demonstrates polling with a fixed frequency and with an adaptive frequency using a callable.

```php
$folder->poll(
    callback: function (MessageInterface $message) {
        echo "New: " . $message->subject();
    },
    frequency: 30  // Check every 30 seconds
);

// With adaptive frequency
$folder->poll(
    callback: fn($msg) => processMessage($msg),
    frequency: fn() => getNextCheckInterval()  // Dynamic interval
);
```

--------------------------------

### subject() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates filtering messages by subject text.

```php
$replies = $folder->messages()->subject('RE:')->get();
```

--------------------------------

### since() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates filtering messages since a specific date.

```php
$recent = $folder->messages()->since('2024-08-01')->get();
```

--------------------------------

### folders()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Get the folder repository for listing and managing folders.

```APIDOC
## folders(): FolderRepositoryInterface

### Description
Get the folder repository for listing and managing folders.

### Returns
- **FolderRepositoryInterface** - The folder repository instance
```

--------------------------------

### orderBy() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates sorting messages by date in descending order.

```php
use DirectoryTree\ImapEngine\Enums\ImapSortKey;

$sorted = $folder->messages()
    ->orderBy(ImapSortKey::Date, 'desc')
    ->get();
```

--------------------------------

### Get Folder Path

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Retrieves the full path of the folder.

```php
$path = $folder->path();  // "Archives/2024"
```

--------------------------------

### config()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Get configuration values. If no key is provided, returns the entire configuration array.

```APIDOC
## config(?string $key = null, mixed $default = null): mixed

### Description
Get configuration values.

### Parameters
- **key** (string|null) - Optional - Configuration key. If null, returns entire config.
- **default** (mixed) - Optional - Default value if key doesn't exist.

### Returns
- **mixed** - Configuration value or array of all config
```

--------------------------------

### Get folder repository

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Retrieves the repository for listing and managing folders.

```php
$folders = $mailbox->folders();
$allFolders = $folders->get()->all();
$specific = $folders->find('Archive');
```

--------------------------------

### Get attachment parts with attachments()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/body-structure.md

Retrieves all parts identified as attachments, which are defined as non-inline and non-text parts. The example iterates through the attachments and outputs their filenames.

```php
public function attachments(): BodyStructurePart[]
```

```php
$attachments = $structure->attachments();
foreach ($attachments as $part) {
    echo $part->filename();
}
```

--------------------------------

### Enable Echo Logging

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Set the debug option to true to output logs directly to echo.

```php
$mailbox = new Mailbox([
    'debug' => true,  // Output to echo
]);
```

--------------------------------

### Initialize Mailbox with Constructor Options

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Pass an array of configuration options to the Mailbox constructor. All options have sensible defaults.

```php
$mailbox = new Mailbox([
    'host' => 'imap.example.com',
    'port' => 993,
    'username' => 'user@example.com',
    'password' => 'app-password',
    'timeout' => 30,
    'encryption' => 'ssl',
    'validate_cert' => true,
    'authentication' => 'plain',
    'debug' => false,
    'proxy' => [
        'socket' => null,
        'username' => null,
        'password' => null,
        'request_fulluri' => false,
    ],
]);
```

--------------------------------

### Catching ImapCommandException

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Example of catching an ImapCommandException when an IMAP command returns a BAD or NO response.

```php
try {
    $folder = $mailbox->folders()->findOrFail('NonExistent');
} catch (ImapCommandException $e) {
    echo "Command failed: " . $e->command();
    echo "Response: " . $e->response();
}
```

--------------------------------

### leaveUnread() usage example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Demonstrates fetching unseen messages without marking them as read.

```php
$unread = $folder->messages()
    ->unseen()
    ->leaveUnread()
    ->get();
```

--------------------------------

### Configure STARTTLS Encryption

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Use port 143 to upgrade a plain connection to TLS.

```php
[
    'host' => 'imap.example.com',
    'port' => 143,
    'encryption' => 'starttls',
]
```

--------------------------------

### Get configuration values

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Retrieves specific configuration keys or the entire configuration array.

```php
$host = $mailbox->config('host');
$port = $mailbox->config('port', 993);
$allConfig = $mailbox->config();
```

--------------------------------

### Connection and Capability Management

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Methods for managing mailbox connections and handling capability-based operations like IDLE.

```APIDOC
## connect()

### Description
Establishes a connection to the mailbox.

## idle(callable $callback)

### Description
Starts an IDLE session on the folder. Throws ImapCapabilityException if the server does not support IDLE.

### Parameters
- **callback** (callable) - Required - Callback for new messages

## poll(callable $callback)

### Description
Polls the folder for new messages, typically used as a fallback when IDLE is not supported.

### Parameters
- **callback** (callable) - Required - Callback for new messages
```

--------------------------------

### BodyStructurePart Usage Example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/types.md

Iterates through message body parts to display content type, filename, and size.

```php
$structure = $message->bodyStructure();
$parts = $structure->parts();

foreach ($parts as $part) {
    echo $part->contentType() . " - " . $part->filename();
    echo " (" . $part->size() . " bytes)\n";
}
```

--------------------------------

### Get server capabilities

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Retrieves the list of capabilities supported by the IMAP server.

```php
$capabilities = $mailbox->capabilities();
if (in_array('IDLE', $capabilities)) {
    echo "Server supports IDLE";
}
```

--------------------------------

### Attachment Usage Example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/types.md

Iterates through message attachments to display details and save files to a local directory.

```php
$attachments = $message->attachments();
foreach ($attachments as $file) {
    echo $file->filename() . ' (' . $file->contentType() . ')';
    $file->save("/downloads/" . $file->filename());
}
```

--------------------------------

### Configure encryption settings

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Use ssl or starttls for encrypted connections. Avoid tcp as it transmits credentials in plain text.

```php
[
    'encryption' => 'ssl',      // Implicit encryption (port 993)
    'encryption' => 'starttls', // Explicit encryption (port 143)
]

// Never use unencrypted:
[
    'encryption' => 'tcp',  // Avoid - credentials sent in plain text!
]
```

--------------------------------

### Retrieve folder information

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Access status, quota, and read-only examine information for a specific folder.

```php
$folder = $mailbox->inbox();

// Status information
$status = $folder->status();
echo $status['MESSAGES'];  // Total messages
echo $status['UNSEEN'];    // Unread messages

// Quota information
$quota = $folder->quota();
// ['STORAGE' => ['usage' => 1024000, 'limit' => 10485760]]

// Examine folder (read-only)
$info = $folder->examine();
```

--------------------------------

### Pagination Methods

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Methods for retrieving paginated message collections from a folder. Supports manual limit/page control and Laravel-style pagination objects.

```APIDOC
## limit(int $limit, int $page)

### Description
Retrieves a specific page of messages with a defined limit per page.

### Method
Method

### Parameters
- **limit** (int) - Required - Number of items per page
- **page** (int) - Required - The page number to retrieve

## paginate(int $perPage)

### Description
Returns a paginator instance for the messages collection, providing access to links and metadata.

### Parameters
- **perPage** (int) - Required - Number of items per page
```

--------------------------------

### Catching ImapResponseException

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Example of catching an ImapResponseException when the server response cannot be parsed or is unexpected.

```php
try {
    $messages = $folder->messages()->get();
} catch (ImapResponseException $e) {
    echo "Invalid server response: " . $e->getMessage();
}
```

--------------------------------

### FolderRepository get() Method

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Lists folders matching a specified pattern. The match parameter supports '*' for all folders and '%' for one level.

```php
public function get(?string $match = '*', ?string $reference = ''): FolderCollection
```

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

// Get all subfolders of INBOX
$inbox_subs = $mailbox->folders()->get('INBOX/*');

// Get only top-level folders
$top_level = $mailbox->folders()->get('%');

// Pattern matching
$archives = $mailbox->folders()->get('Archive*');
```

--------------------------------

### getLimit() and setLimit() method definitions

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Defines methods to get or set the query limit.

```php
public function getLimit(): ?int
public function setLimit(int $limit): MessageQueryInterface
```

--------------------------------

### MessageQuery get() method

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Executes the query and returns a collection of matching messages.

```php
public function get(): MessageCollection
```

```php
$messages = $folder->messages()->unseen()->get();
foreach ($messages as $message) {
    echo $message->subject();
}
```

--------------------------------

### Handle Item Not Found

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Catch Illuminate\Support\ItemNotFoundException when using firstOrFail to handle cases where no messages are found.

```php
use Illuminate\Support\ItemNotFoundException;

try {
    $message = $folder->messages()->firstOrFail();
} catch (ItemNotFoundException) {
    echo "No messages found";
}
```

--------------------------------

### Laravel-Style Pagination

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Use the paginate method to return a paginator instance, which provides access to links, current page, and total count.

```php
$paginator = $folder->messages()->paginate(20);

echo $paginator->links();
echo $paginator->currentPage();
echo $paginator->total();
```

--------------------------------

### Configure Plain Authentication

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Uses standard username and password credentials for authentication.

```php
[
    'username' => 'user@example.com',
    'password' => 'password',
    'authentication' => 'plain',
]
```

--------------------------------

### Folder Management

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Methods for listing, creating, and retrieving status or quota information for IMAP folders.

```APIDOC
## Folder Operations

### List All Folders
`$mailbox->folders()->get()`
Returns a collection of folder objects.

### Create Folder
`$mailbox->folders()->create(string $path)`
Creates a new folder at the specified path.

### First or Create Folder
`$mailbox->folders()->firstOrCreate(string $path)`
Retrieves an existing folder or creates it if it does not exist.

### Folder Status
`$folder->status()`
Returns an array containing folder status information such as total messages and unread counts.

### Folder Quota
`$folder->quota()`
Returns storage usage and limit information for the folder.

### Examine Folder
`$folder->examine()`
Opens the folder in read-only mode.
```

--------------------------------

### Configure Ray Debugging

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Integrates with Spatie's Ray for debugging.

```php
[
    'debug' => DirectoryTree\ImapEngine\Connection\Loggers\RayLogger::class,
]
```

--------------------------------

### Catching ImapParserException

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Example of catching an ImapParserException when the IMAP response parser encounters a syntax error.

```php
try {
    $folder->status();
} catch (ImapParserException $e) {
    echo "Parse error in server response: " . $e->getMessage();
}
```

--------------------------------

### Get Unread Messages

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/INDEX.md

Retrieves a collection of unread messages from the inbox.

```APIDOC
## $mailbox->inbox()->messages()->unseen()->get()

### Description
Fetches all messages currently marked as unseen in the inbox.

### Usage
```php
$unread = $mailbox->inbox()->messages()->unseen()->get();
```
```

--------------------------------

### Configure SSL/TLS Encryption

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Use port 993 for an immediate SSL/TLS handshake.

```php
[
    'host' => 'imap.gmail.com',
    'port' => 993,
    'encryption' => 'ssl',
]
```

--------------------------------

### Get Unread Messages

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/INDEX.md

Retrieves a collection of unseen messages from the inbox.

```php
$unread = $mailbox->inbox()->messages()->unseen()->get();
```

--------------------------------

### connection()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Get the underlying IMAP connection instance. Automatically connects if not already connected.

```APIDOC
## connection(): ConnectionInterface

### Description
Get the underlying IMAP connection instance. Automatically connects if not already connected.

### Returns
- **ConnectionInterface** - The connection instance
```

--------------------------------

### Get connection instance

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Retrieves the underlying connection instance, automatically connecting if necessary.

```php
$connection = $mailbox->connection();
$response = $connection->capability();
```

--------------------------------

### Query Messages in a Folder

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Use the fluent interface to filter messages by status or date within a folder.

```php
$folder = $mailbox->inbox();
$unread = $folder->messages()->unseen()->get();
$recent = $folder->messages()->since('2024-08-01')->get();
```

--------------------------------

### Message Queries

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Methods for searching, filtering, and sorting messages within a folder.

```APIDOC
## Message Querying

### Search Criteria
- `since(string $date)`: Filter messages since a specific date.
- `before(string $date)`: Filter messages before a specific date.
- `on(string $date)`: Filter messages on a specific date.
- `from(string $email)`: Filter messages by sender.
- `to(string $email)`: Filter messages by recipient.
- `cc(string $email)`: Filter messages by CC recipient.
- `larger(int $bytes)`: Filter messages larger than specified size.
- `smaller(int $bytes)`: Filter messages smaller than specified size.
- `unseen()`: Filter for unread messages.

### Execution
`$folder->messages()->[criteria]->get()`
Executes the query and returns the matching messages.

### Sorting
`$folder->messages()->orderBy(ImapSortKey $key, string $direction)`
Sorts messages based on a provided ImapSortKey (e.g., Date, From) and direction (asc/desc).
```

--------------------------------

### getPage() and setPage() method definitions

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message-query.md

Defines methods to get or set the current page number.

```php
public function getPage(): int
public function setPage(int $page): MessageQueryInterface
```

--------------------------------

### ImapEngine Project File Structure

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/INDEX.md

The directory structure of the ImapEngine project, showing the organization of core classes, connection handling, enums, and collections.

```text
src/
├── Mailbox.php                    # Entry point
├── Folder.php                     # Folder representation
├── Message.php                    # Message representation
├── MessageQuery.php               # Query builder
├── FolderRepository.php           # Folder management
├── Address.php                    # Email address
├── Attachment.php                 # File attachment
├── BodyStructurePart.php          # MIME part
├── ContentDisposition.php         # Disposition header
├── DraftMessage.php               # Message composer
├── Connection/
│   ├── ImapConnection.php         # IMAP protocol
│   ├── ImapParser.php             # Response parser
│   ├── ImapQueryBuilder.php       # Search syntax
│   └── Streams/
│       └── ImapStream.php         # Socket stream
├── Enums/
│   ├── ImapFlag.php
│   ├── ImapSearchKey.php
│   ├── ImapSortKey.php
│   └── ImapFetchIdentifier.php
├── Exceptions/
│   ├── ImapConnectionFailedException.php
│   ├── ImapCommandException.php
│   └── ... (other exceptions)
└── Collections/
    └── MessageCollection.php
```

--------------------------------

### Perform server-side sorting

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Sort messages using the ImapSortKey enum and the orderBy method.

```php
use DirectoryTree\ImapEngine\Enums\ImapSortKey;

// Sort by date (newest first)
$messages = $folder->messages()
    ->orderBy(ImapSortKey::Date, 'desc')
    ->get();

// Sort by sender
$messages = $folder->messages()
    ->orderBy(ImapSortKey::From, 'asc')
    ->get();
```

--------------------------------

### Monitor for New Messages

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Listen for incoming messages using real-time IDLE capability or periodic polling.

```php
// Real-time monitoring (requires IDLE capability)
$folder->idle(
    callback: function ($message) {
        echo "New: " . $message->subject();
    },
    timeout: 600  // 10 minutes
);

// Or polling
$folder->poll(
    callback: function ($message) {
        echo "New: " . $message->subject();
    },
    frequency: 30  // Check every 30 seconds
);
```

--------------------------------

### Implement Custom Logger

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Create a class implementing LoggerInterface and pass its class name to the debug option to use a custom logging mechanism.

```php
use DirectoryTree\ImapEngine\Connection\Loggers\LoggerInterface;

class MyLogger implements LoggerInterface {
    public function log(string $message, string $direction = 'sent'): void {
        // Custom logging
    }
}

$mailbox = new Mailbox([
    'debug' => MyLogger::class,
]);
```

--------------------------------

### Connect to a Mailbox

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Initialize a connection to an IMAP server using the Mailbox class with host, port, credentials, and encryption settings.

```php
use DirectoryTree\ImapEngine\Mailbox;

$mailbox = new Mailbox([
    'host' => 'imap.gmail.com',
    'port' => 993,
    'username' => 'user@gmail.com',
    'password' => 'your-app-password',
    'encryption' => 'ssl',
]);

$mailbox->connect();
```

--------------------------------

### Create Mailbox instance with make()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Uses the static factory method to instantiate a Mailbox.

```php
public static function make(array $config = []): static
```

--------------------------------

### Search messages by size

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Filter messages by size in bytes using larger or smaller criteria.

```php
$large = $folder->messages()->larger(1048576)->get();  // > 1MB
$small = $folder->messages()->smaller(10240)->get();   // < 10KB
```

--------------------------------

### Get text/plain part with text()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/body-structure.md

Retrieves the text/plain part of the message if it exists.

```php
public function text(): ?BodyStructurePart
```

--------------------------------

### Check IMAP capabilities

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Shows how to retrieve the list of supported server capabilities and verify if a specific capability like IDLE is present.

```php
$caps = $mailbox->capabilities();
// ['IMAP4REV1', 'STARTTLS', 'LOGINDISABLED', 'IDLE', 'NAMESPACE', 'SORT', ...]

if (in_array('IDLE', $caps)) {
    echo "IDLE is supported";
}
```

--------------------------------

### Limit and Page messages

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Use the limit method to retrieve specific pages of messages with a defined number of items per page.

```php
// Get page 1 with 10 items per page
$page1 = $folder->messages()->limit(10, 1)->get();

// Get page 2
$page2 = $folder->messages()->limit(10, 2)->get();
```

--------------------------------

### Enable Echo Debugging

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Outputs debug information directly to stdout.

```php
[
    'debug' => true,  // Outputs to echo
]
```

--------------------------------

### Work with Attachments

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Check for attachments on a message and iterate through them to retrieve metadata or save files to a local directory.

```php
if ($message->hasAttachments()) {
    foreach ($message->attachments() as $file) {
        echo $file->filename();
        echo $file->contentType();
        $file->save("/downloads/" . $file->filename());
    }
}
```

--------------------------------

### Enable File Logging

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Set the debug option to a file path string to log IMAP activity to a specific file.

```php
$mailbox = new Mailbox([
    'debug' => '/var/log/imap.log',
]);
```

--------------------------------

### Enable production certificate validation

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Set validate_cert to true to ensure secure connections in production environments.

```php
[
    'validate_cert' => true,  // Required for production
]
```

--------------------------------

### inbox()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Get the user's primary mailbox (INBOX folder).

```APIDOC
## inbox(): FolderInterface

### Description
Get the user's primary mailbox (INBOX folder).

### Returns
- **FolderInterface** - The INBOX folder

### Throws
- ItemNotFoundException
```

--------------------------------

### Manage Flags

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Update message status or perform bulk operations on folders using flag management methods.

```php
$message->markRead();
$message->markFlagged();
$message->delete();

// Bulk operations
$folder->messages()->unseen()->markRead();
$folder->messages()->flagged()->delete();
```

--------------------------------

### MessageCollection Filtering and Sorting Example

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/types.md

Demonstrates using standard Laravel Collection methods like filter and sortBy on a MessageCollection instance.

```php
$messages = $folder->messages()->get();
$unread = $messages->filter(fn($m) => !$m->isSeen());
$byDate = $messages->sortBy(fn($m) => $m->date()?->timestamp);
```

--------------------------------

### Chunking and Iteration

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Methods for processing large sets of messages efficiently by chunking or iterating through the collection.

```APIDOC
## chunk(callable $callback, int $chunkSize)

### Description
Processes messages in chunks to maintain memory efficiency.

### Parameters
- **callback** (callable) - Required - Function to execute on each chunk
- **chunkSize** (int) - Required - Number of messages per chunk

## each(callable $callback, int $chunkSize)

### Description
Iterates through each message in the collection using chunking for memory management.

### Parameters
- **callback** (callable) - Required - Function to execute on each message
- **chunkSize** (int) - Required - Number of messages to process at once
```

--------------------------------

### Using FolderCollection methods

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

The get() method returns a FolderCollection, which extends Laravel's Collection. You can use standard collection methods, iteration, and array access.

```php
$folders = $mailbox->folders()->get();

// Collection methods
$count = $folders->count();
$first = $folders->first();
$mapped = $folders->map(fn($f) => $f->path());
$filtered = $folders->filter(fn($f) => in_array('\Trash', $f->flags()));

// Iteration
foreach ($folders as $folder) {
    echo $folder->name();
}

// Array access
$all = $folders->all();
```

--------------------------------

### Configure IMAP credentials using environment variables

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Use environment variables to avoid hardcoding sensitive credentials in your source code.

```php
$config = [
    'host' => env('IMAP_HOST'),
    'username' => env('IMAP_USERNAME'),
    'password' => env('IMAP_PASSWORD'),
];
```

--------------------------------

### Access Mailbox Folders

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Retrieve folders using the folder repository or access specific folders like the inbox.

```php
$folders = $mailbox->folders()->get();
$inbox = $mailbox->inbox();
$archive = $mailbox->folders()->find('Archive');
```

--------------------------------

### Combine search criteria

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Chain multiple criteria together to refine message search results.

```php
$results = $folder->messages()
    ->unseen()
    ->since('2024-08-01')
    ->from('important@example.com')
    ->get();
```

--------------------------------

### Get TO addresses

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves an array of all TO addresses associated with the message.

```php
$recipients = $message->to();
foreach ($recipients as $addr) {
    echo $addr->email() . ' (' . $addr->name() . ')';
}
```

--------------------------------

### Search messages by date

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Filter messages based on specific date criteria using since, before, or on methods.

```php
// Since a date
$recent = $folder->messages()->since('2024-08-01')->get();

// Before a date
$old = $folder->messages()->before('2020-01-01')->get();

// On a specific date
$today = $folder->messages()->on('2024-08-16')->get();
```

--------------------------------

### Folder Constructor

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Creates a new Folder instance. This is typically handled by the FolderRepository rather than direct instantiation.

```php
public function __construct(
    protected Mailbox $mailbox,
    protected string $path,
    protected array $flags = [],
    protected string $delimiter = '/',
)
```

--------------------------------

### Get FROM address

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the sender's address from the message.

```php
$from = $message->from();
echo $from->email();  // user@example.com
echo $from->name();   // User Name
```

--------------------------------

### Create new Mailbox instances

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Primary configuration is immutable. To change settings, create a new Mailbox instance and call connect().

```php
$mailbox1 = new Mailbox($config1);
$mailbox2 = clone $mailbox1;

// The clone is disconnected and can connect with its own config
$mailbox2->config = new Config($config2);  // Not actually possible

// Better approach: create new instance
$mailbox2 = new Mailbox($config2);
$mailbox2->connect();
```

--------------------------------

### Get Message ID

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the unique message-id header.

```php
public function messageId(bool $fetch = false): ?string
```

--------------------------------

### FolderRepository firstOrCreate() Method

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Retrieves an existing folder or creates it if it does not exist.

```php
public function firstOrCreate(string $path): FolderInterface
```

```php
$archive = $mailbox->folders()->firstOrCreate('Archive/2024');
```

--------------------------------

### Get Message Subject

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the message subject line.

```php
public function subject(bool $fetch = false): ?string
```

```php
$subject = $message->subject();
```

--------------------------------

### Get Message UID

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the unique identifier for the message.

```php
public function uid(): int
```

```php
$uid = $message->uid();
```

--------------------------------

### Test with fake connections using ImapConnection::fake

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Use this method to simulate IMAP server responses during testing. It requires passing an array of expected server response strings.

```php
use DirectoryTree\ImapEngine\Connection\ImapConnection;

$connection = ImapConnection::fake([
    'OK Connection established',
    '* LIST (...) "INBOX"',
]);

$mailbox = new Mailbox();
$mailbox->connect($connection);
```

--------------------------------

### Get Message Folder

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the folder containing the message.

```php
public function folder(): FolderInterface
```

```php
$folder = $message->folder();
$path = $folder->path();
```

--------------------------------

### Construct a Mailbox instance

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Initializes a new Mailbox instance using an array of configuration options.

```php
public function __construct(array $config = [])
```

--------------------------------

### Handle Capability Errors

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/GUIDE.md

Catch ImapCapabilityException to detect unsupported features like IDLE and implement fallback logic such as polling.

```php
use DirectoryTree\ImapEngine\Exceptions\ImapCapabilityException;

try {
    $folder->idle($callback);
} catch (ImapCapabilityException $e) {
    echo "IDLE not supported. Using polling instead.";
    $folder->poll($callback);
}
```

--------------------------------

### List all folders

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Retrieve all folders and iterate through them to display their paths and flags.

```php
$folders = $mailbox->folders()->get();

foreach ($folders as $folder) {
    echo $folder->path() . "\n";
    echo "  Flags: " . implode(', ', $folder->flags()) . "\n";
}
```

--------------------------------

### get()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Retrieves a collection of all folders associated with the mailbox. The returned object extends Laravel's Collection class, allowing for standard collection operations.

```APIDOC
## get()

### Description
Retrieves all folders for the current mailbox as a FolderCollection.

### Signature
`$mailbox->folders()->get()`
```

--------------------------------

### Configure File Debugging

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Logs debug information to a specified file path.

```php
[
    'debug' => '/var/log/imap-debug.log',
]
```

--------------------------------

### Configure SOCKS Proxy

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Sets up a SOCKS5 proxy connection for the IMAP engine.

```php
[
    'proxy' => [
        'socket' => 'socks5://proxy.example.com:1080',
        'username' => 'proxy_user',
        'password' => 'proxy_pass',
        'request_fulluri' => false,
    ],
]
```

--------------------------------

### Configure Custom Logger Class

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Uses a custom logger class that implements LoggerInterface.

```php
[
    'debug' => CustomLogger::class,
]
```

--------------------------------

### Get INBOX folder

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/mailbox.md

Retrieves the user's primary mailbox folder.

```php
$inbox = $mailbox->inbox();
$messages = $inbox->messages()->get();
```

--------------------------------

### FolderRepository Constructor

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Creates a new FolderRepository instance, typically initialized via Mailbox::folders().

```php
public function __construct(protected Mailbox $mailbox)
```

--------------------------------

### Get Message Date

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the message date as a CarbonInterface instance.

```php
public function date(bool $fetch = false): ?CarbonInterface
```

```php
$date = $message->date();
if ($date) {
    echo $date->format('Y-m-d H:i:s');
}
```

--------------------------------

### Get Message Flags

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves all IMAP flags associated with the message.

```php
public function flags(): array
```

```php
$flags = $message->flags();
// ['\\Seen', '\\Flagged', ...]
```

--------------------------------

### Configure connection timeout settings

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Adjust the timeout value based on network conditions and performance requirements.

```php
[
    'timeout' => 30,    // Standard: 30 seconds
    'timeout' => 60,    // Slow networks: 60 seconds
    'timeout' => 5,     // Fast local: 5 seconds
]
```

--------------------------------

### Get Parent Mailbox

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder.md

Retrieves the parent Mailbox instance associated with the folder.

```php
$mailbox = $folder->mailbox();
$capabilities = $mailbox->capabilities();
```

--------------------------------

### Configure OAuth 2.0 Authentication

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Required for OAuth-enabled servers like Gmail or Outlook using an access token as the password.

```php
[
    'username' => 'user@gmail.com',
    'password' => 'ya29.a0AfH6SMBx...',  // OAuth access token
    'authentication' => 'oauth',
]
```

--------------------------------

### Get JSON-serializable representation with jsonSerialize()

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/attachment.md

Provides a JSON-serializable array representation of the attachment.

```php
public function jsonSerialize(): array
```

```php
$json = json_encode($attachment);
```

--------------------------------

### Create folder hierarchy

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Use firstOrCreate to ensure a folder path exists.

```php
$mailbox->folders()->firstOrCreate('Projects/2024/Q1');
```

--------------------------------

### Configure No Encryption

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/configuration.md

Use port 143 with 'tcp' encryption for plain text connections, which is insecure.

```php
[
    'host' => 'localhost',
    'port' => 143,
    'encryption' => 'tcp',
]
```

--------------------------------

### FolderRepository create() Method

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/folder-repository.md

Creates a new folder at the specified path. Throws an ImapCommandException if the operation fails.

```php
public function create(string $path): FolderInterface
```

```php
$newFolder = $mailbox->folders()->create('Projects/2024');
```

--------------------------------

### __toString() method

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Get the full RFC822 message as a string (headers + body).

```php
public function __toString(): string
```

--------------------------------

### Handle ImapCapabilityException for IDLE

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Demonstrates catching an ImapCapabilityException when the server lacks the required IDLE capability. It also displays how to retrieve and list available server capabilities.

```php
try {
    $mailbox->inbox()->idle(fn($m) => print($m->subject()));
} catch (ImapCapabilityException $e) {
    echo "Server doesn't support IDLE";
    echo "Available: " . implode(', ', $mailbox->capabilities());
}
```

--------------------------------

### Get and save attachments

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves all message attachments and saves them to a specified path.

```php
$attachments = $message->attachments(fetch: true);
foreach ($attachments as $attachment) {
    echo $attachment->filename();
    $attachment->save('/path/to/file');
}
```

--------------------------------

### Get parsed body structure

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/api-reference/message.md

Retrieves the parsed MIME parts of the message.

```php
$structure = $message->bodyStructure();
if ($structure) {
    foreach ($structure->attachments() as $part) {
        echo $part->filename();
    }
}
```

--------------------------------

### Graceful Degradation for IDLE

Source: https://github.com/directorytree/imapengine/blob/master/_autodocs/errors.md

Check for server capabilities before executing operations. If a specific capability like IDLE is missing, fall back to an alternative method like polling.

```php
$mailbox = new Mailbox($config);

// Try IDLE, fall back to polling
try {
    if (in_array('IDLE', $mailbox->capabilities())) {
        $folder->idle($callback);
    }
} catch (ImapCapabilityException) {
    // Use polling instead
    $folder->poll($callback, frequency: 60);
}
```
Tokens:
Raw