ImapEngine

https://imapengine.com
Admin
ImapEngine is a PHP library that provides a simple, fluent API for managing IMAP mailboxes without...
Tokens:21,041
Snippets:247
Trust Score:5.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install ImapEngine Laravel Package

Source: https://imapengine.com/docs/laravel/installation

Use Composer to install the ImapEngine Laravel package. Ensure PHP 8.1+ and Laravel 10.0+ are met.

```bash
composer require directorytree/imapengine-laravel
```

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

### Install ImapEngine via Composer

Source: https://imapengine.com/docs/installation

Use this Composer command to add ImapEngine to your project dependencies. Ensure you have PHP 8.1 or higher installed.

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

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

### Setup Fake Mailbox for Pest Tests

Source: https://imapengine.com/docs/usage/testing

Use this setup in your Pest tests to create a fake mailbox with pre-defined folders and messages. Ensure the necessary fake classes are imported.

```php
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMailbox;
use DirectoryTree\ImapEngine\Testing\FakeMessage;

beforeEach(function () {
    // Create a fake mailbox for testing
    $this->mailbox = new FakeMailbox(
        config: ['host' => 'imap.example.com', 'port' => 993],
        folders: [
            new FakeFolder(
                path: 'inbox',
                messages: [
                    new FakeMessage(
                        uid: 1,
                        flags: ['\Seen'],
                        contents: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test Email\r\n\r\nThis is a test email.'
                    )
                ]
            )
        ]
    );
});
```

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

### Connect to IMAP Server and Retrieve Messages

Source: https://imapengine.com/

Connect to an IMAP server using SSL and retrieve all messages from the inbox, including their headers. This example demonstrates basic connection and message retrieval.

```php
use DirectoryTree\ImapEngine\Mailbox;


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


$inbox = $mailbox->inbox();


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

```php
use DirectoryTree\ImapEngine\Mailbox;


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


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


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


foreach ($messages as $message) {
    echo $message->from()->email();
}
```

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

### Start Awaiting New Messages with IDLE

Source: https://imapengine.com/docs/usage/monitoring

Initiates the IDLE command to receive push notifications for new messages. This method is blocking and should be run in a background process.

```php
use DirectoryTree\ImapEngine\Message;


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


// Begin idling on the inbox folder.
$inbox->idle(function (Message $message) {
    // Do something with the newly received message
});
```

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

### Create a Basic Draft Message

Source: https://imapengine.com/docs/usage/messages

Use the `append()` method on a folder instance with a `DraftMessage` object to create a new draft. This example shows how to set the sender, recipient, subject, and body content.

```php
use DirectoryTree\ImapEngine\DraftMessage;


$uid = $inbox->messages()->append(
    new DraftMessage(
        from: 'foo@email.com',
        to: 'bar@email.com',
        subject: 'Hello World',
        text: 'This is the message body.',
        html: '<p>This is the message body.</p>',
    )
);

```

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

### Getting Specific Folders

Source: https://imapengine.com/docs/usage/folders

Learn how to find a specific folder by name, retrieve the inbox folder directly, or find and fail if the folder does not exist.

```APIDOC
## Getting a Specific Folder

### Description
To retrieve a specific folder, you may use the `find()` method on the `FolderRepository` instance. The `inbox()` method provides a shortcut to get the mandatory inbox folder.

### Method
`inbox()`, `find(string $name)`, `findOrFail(string $name)`

### Endpoint
N/A (Methods on Mailbox or FolderRepository instances)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
// 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');
```

### Response
#### Success Response (200)
- **folder** (Folder) - An instance of the Folder class representing the found folder.

#### Response Example
(Returns a Folder instance or throws an exception if not found with `findOrFail`)
```

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

### Configure IMAP Mailbox Connection

Source: https://imapengine.com/docs/installation

Instantiate the Mailbox class with your IMAP server details. This basic example includes essential connection parameters like host, port, username, password, and encryption.

```php
use DirectoryTree\ImapEngine\Mailbox;


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

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

### PHPUnit Test with Fake Mailbox

Source: https://imapengine.com/docs/usage/testing

Integrate ImapEngine's testing utilities into your PHPUnit tests by setting up a `FakeMailbox` in the `setUp` method. This allows you to simulate email scenarios and test your processing logic.

```php
use PHPUnit\Framework\TestCase;
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMailbox;
use DirectoryTree\ImapEngine\Testing\FakeMessage;


class EmailProcessorTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();


        // Create a fake mailbox for testing
        $this->mailbox = new FakeMailbox(
            config: ['host' => 'imap.example.com', 'port' => 993],
            folders: [
                new FakeFolder(
                    path: 'inbox',
                    messages: [
                        new FakeMessage(
                            uid: 1,
                            flags: ['\Seen'],
                            contents: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test Email\r\n\r\nThis is a test email.'
                        )
                    ]
                )
            ]
        );
    }


    public function testProcessNewEmails(): void
    {
        // Get the inbox folder
        $inbox = $this->mailbox->inbox();


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


        // Assert we have one message
        $this->assertCount(1, $messages);


        // Assert the message has the correct subject
        $this->assertEquals('Test Email', $messages->first()->subject());


        // Test your email processing logic here...
    }
}
```

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

### Retrieve Mailbox Server Capabilities

Source: https://imapengine.com/docs/usage/connecting

Get a list of supported IMAP capabilities advertised by the mailbox server by calling the `capabilities()` method.

```php
// ["IMAP4rev1", "IDLE", "UIDPLUS", ...]
$capabilities = $mailbox->capabilities();

```

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

### Work with IMAP Subfolders

Source: https://imapengine.com/docs/usage/folders

Retrieve subfolders of a given folder using the `folders()->get()` method with a wildcard pattern, or find a specific subfolder using `folders()->find()` with its full path.

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


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

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

### Retrieving Folders

Source: https://imapengine.com/docs/usage/folders

This section covers how to get all folders or folders matching a specific pattern from an IMAP mailbox.

```APIDOC
## Retrieving Folders

### Description
To retrieve folders from an IMAP mailbox, you may use the `folders()` method on the `Mailbox` instance. This method returns a `FolderRepository` instance, which provides operations for retrieving, creating, and managing folders.

### Method
`folders()`

### Endpoint
N/A (Method on Mailbox instance)

### Parameters
None

### Request Example
```php
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');
```

### Response
#### Success Response (200)
- **folders** (FolderRepository) - An instance of FolderRepository to perform folder operations.

#### Response Example
(Returns a FolderRepository instance, actual folder data is retrieved via subsequent calls like `get()`)
```

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

### Retrieve IMAP Folders

Source: https://imapengine.com/docs/usage/folders

Use the `folders()->get()` method to retrieve all folders or folders matching a glob pattern. Ensure the Mailbox instance is properly configured.

```php
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');
```

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

### Start Polling for New Messages

Source: https://imapengine.com/docs/usage/monitoring

Initiates the Long Polling method to periodically check for new messages. This method is blocking and should be run in a background process. The frequency parameter controls how often the server is checked.

```php
use DirectoryTree\ImapEngine\Message;


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


// Begin polling the inbox folder every 60 seconds.
$inbox->poll(function (Message $message) {
    // Do something with the newly received message
});
```

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

### Connect with STARTTLS

Source: https://imapengine.com/docs/usage/configuration

Establish a connection using STARTTLS encryption on port 143.

```php
use DirectoryTree\ImapEngine\Mailbox;


$mailbox = new Mailbox([
    'port' => 143,
    'encryption' => 'starttls',
    'username' => 'your-username',
    'password' => 'your-password',
    'host' => 'imap.example.com',
]);
```

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

### Creating Folders

Source: https://imapengine.com/docs/usage/folders

Instructions on how to create new folders, including nested folders, using the `create()` method.

```APIDOC
## Creating Folders

### Description
You may create a new folder using the `create()` method. To create a nested folder, separate the parent and child folder names with your IMAP server’s folder delimiter.

### Method
`create(string $name)`

### Endpoint
N/A (Method on FolderRepository instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
// Create a top-level folder.
$folder = $mailbox->folders()->create('Archive');

// Create a nested folder.
$nestedFolder = $mailbox->folders()->create('Parent/Child');
```

### Response
#### Success Response (200)
- **folder** (Folder) - An instance of the Folder class representing the newly created folder.

#### Response Example
(Returns a Folder instance)
```

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

### Initialize FakeFolder with Messages

Source: https://imapengine.com/docs/laravel/usage

When creating a `FakeFolder`, you can directly provide an array of `FakeMessage` objects using the `messages` parameter for initial population.

```php
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMessage;


$inbox = new FakeFolder(
    path: 'inbox',
    flags: ['\Inbox'],
    messages: [
        new FakeMessage(1, ['\Seen'], 'Message content'),
        new FakeMessage(2, ['\Flagged'], 'Another message content'),
    ],
);

```

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

### Build a Custom Mailbox Instance

Source: https://imapengine.com/docs/laravel/usage

Construct a custom mailbox instance by providing its configuration details directly to the `Imap::build` method.

```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;


$mailbox = Imap::build([
    'host' => 'imap.example.com',
    'port' => 993,
    'username' => 'username',
    'password' => 'password',
    'encryption' => 'ssl',
]);

```

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

### Get Multipart Message Structure

Source: https://imapengine.com/docs/usage/messages

Retrieve the body structure of a multipart message to understand its composition. Access subtypes, content types, boundaries, and child parts.

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


// Get the multipart subtype (e.g., "mixed", "alternative", "related")
$structure->subtype(); // "alternative"


// Get the content type
$structure->contentType(); // "multipart/alternative"


// Get the boundary parameter
$structure->boundary(); // "Aq14h3UL"


// Get all parameters
$structure->parameters(); // ['boundary' => 'Aq14h3UL']


// Get direct child parts
$structure->parts(); // Array of BodyStructurePart or BodyStructureCollection


// Count the number of parts
$structure->count(); // 2
```

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

### Create a Fake Mailbox for Testing

Source: https://imapengine.com/docs/usage/testing

Instantiate `FakeMailbox` to create a mock IMAP mailbox. You can configure its host, port, credentials, and pre-populate it with fake folders and capabilities.

```php
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMailbox;
use DirectoryTree\ImapEngine\Testing\FakeMessage;


// Create a fake mailbox with configuration
$mailbox = new FakeMailbox(
    // Configuration
    config: [
        'host' => 'imap.example.com',
        'port' => 993,
        'username' => 'test@example.com',
        'password' => 'password',
        'encryption' => 'ssl',
    ],
    // Folders
    folders: [
        new FakeFolder('inbox'),
        new FakeFolder('sent'),
        new FakeFolder('trash'),
    ],
    // Capabilities
    capabilities: ['IMAP4rev1', 'IDLE', 'UIDPLUS']
);
```

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

### Publish ImapEngine Configuration

Source: https://imapengine.com/docs/laravel/installation

Publish the package's configuration file using the vendor:publish Artisan command. This creates a config/imap.php file.

```bash
php artisan vendor:publish --provider=DirectoryTree\ImapEngine\Laravel\ImapServiceProvider
```

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

### Get Specific IMAP Folder

Source: https://imapengine.com/docs/usage/folders

Retrieve a specific folder by name using `folders()->find()` or `folders()->findOrFail()`. The `inbox()` method provides a shortcut for the mandatory INBOX folder.

```php
// 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');
```

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

### Stop IMAP Polling with a Closure

Source: https://imapengine.com/docs/usage/monitoring

To stop polling, return `false` from the frequency parameter using a closure. This example demonstrates stopping the poll after a message with the subject 'Stop' is processed.

```php
$shouldContinue = true;

$inbox->poll(
    function (Message $message) use (&$shouldContinue) {
        // Process message...


        // Stop polling after processing a specific message
        if ($message->subject() === 'Stop') {
            $shouldContinue = false;
        }
    },
    frequency: function () use (&$shouldContinue) {
        return $shouldContinue ? 60 : false;
    }
);
```

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

### Configure IMAP via Environment Variables

Source: https://imapengine.com/docs/laravel/installation

If your application uses only one IMAP mailbox, configure its details directly in your .env file for simplicity.

```dotenv
IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_USERNAME=your-username
IMAP_PASSWORD=your-password
IMAP_ENCRYPTION=ssl
```

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

### Use RayLogger for Debugging

Source: https://imapengine.com/docs/usage/configuration

Integrate Spatie Ray for debugging by setting the 'debug' option to the RayLogger class name.

```php
use DirectoryTree\ImapEngine\Mailbox;
use DirectoryTree\ImapEngine\Connection\Loggers\RayLogger;


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

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

### Access FileMessage Content

Source: https://imapengine.com/docs/usage/mbox

Interact with FileMessage instances to retrieve raw message content, check for a body, get headers, and process attachments. Note that the uid() method is not available for FileMessage instances.

```php
/** @var \DirectoryTree\ImapEngine\FileMessage $message */
foreach ($mbox->messages() as $message) {
    // Get the raw contents of the message:
    $raw = $message->raw();


    // Check if the message has a body:
    if ($message->hasBody()) {
        // Retrieve the message body.
        $body = $message->body();
    }


    // Retrieve headers (if available):
    $headers = $message->headers();


    // Retrieve attachments:
    foreach ($message->attachments() as $attachment) {
        // Work with each attachment.
        $attachmentContents = $attachment->contents();
    }
}
```

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

### Test EmailService with fake mailbox using Pest

Source: https://imapengine.com/docs/usage/testing

Demonstrates testing the EmailService with a fake mailbox implementation using Pest.

```php
it('retrieves messages from the service', function () {
    // Create a fake mailbox
    $mailbox = new FakeMailbox(
        folders: [
            new FakeFolder(
                path: 'inbox',
                messages: [
                    new FakeMessage(1, ['\Seen'], 'From: sender1@example.com\r\nSubject: Read Email\r\n\r\nRead email.'),
                    new FakeMessage(2, [], 'From: sender2@example.com\r\nSubject: Unread Email\r\n\r\nUnread email.'),
                ]
            )
        ]
    );


    // Create the service with the fake mailbox
    $service = new EmailService($mailbox);


    // Test the method
    $messages = $service->messages();


    // Assert we get both messages
    expect($messages)->toHaveCount(2);
});
```

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

### Folder Properties

Source: https://imapengine.com/docs/usage/folders

How to access properties of a Folder instance such as name, path, and delimiter.

```APIDOC
## Folder Properties

### Description
Once you have a `Folder` instance, you may retrieve various properties like its name, full path, and the server's folder delimiter.

### Method
`name()`, `path()`, `delimiter()`

### Endpoint
N/A (Methods on Folder instance)

### Parameters
None

### Request Example
```php
$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();
```

### Response
#### Success Response (200)
- **name** (string) - The name of the folder.
- **path** (string) - The full path of the folder.
- **delimiter** (string) - The folder delimiter used by the IMAP server.

#### Response Example
```json
{
    "name": "Inbox",
    "path": "Inbox",
    "delimiter": "/"
}
```
```

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

### Create Folders Test with Pest

Source: https://imapengine.com/docs/usage/testing

This Pest test verifies the folder creation functionality. It demonstrates creating a folder, asserting its presence in the mailbox, and adding a message to the newly created folder.

```php
it('creates folders', function () {
    // Create a new folder
    $folder = $this->mailbox->folders()->create('Archive');


    // Assert the folder was created
    expect($this->mailbox->folders()->find('Archive'))->not->toBeNull();


    // Add a message to the new folder
    $folder->addMessage(
        new FakeMessage(
            uid: 1,
            flags: [],
            contents: 'From: sender@example.com\r\nSubject: Archived Email\r\n\r\nThis is an archived email.'
        )
    );


    // Assert the message was added
    expect($folder->messages()->get())->toHaveCount(1);
});
```

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

### Deleting Folders

Source: https://imapengine.com/docs/usage/folders

Instructions for deleting a folder using the `delete()` method on a Folder instance.

```APIDOC
## Deleting Folders

### Description
To delete a folder, call the `delete()` method on the `Folder` instance.

### Method
`delete()`

### Endpoint
N/A (Method on Folder instance)

### Parameters
None

### Request Example
```php
$folder = $mailbox->folders()->find('Archive');
$folder->delete();
```

### Response
#### Success Response (200)
No specific return value, operation is performed.

#### Response Example
N/A
```

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

### Test EmailService with fake mailbox using PHPUnit

Source: https://imapengine.com/docs/usage/testing

Demonstrates testing the EmailService with a fake mailbox implementation using PHPUnit.

```php
class EmailServiceTest extends TestCase
{
    public function testMessages(): void
    {
        // Create a fake mailbox
        $mailbox = new FakeMailbox(
            folders: [
                new FakeFolder(
                    path: 'inbox',
                    messages: [
                        new FakeMessage(1, ['\Seen'], 'From: sender1@example.com\r\nSubject: Read Email\r\n\r\nRead email.'),
                        new FakeMessage(2, [], 'From: sender2@example.com\r\nSubject: Unread Email\r\n\r\nUnread email.'),
                    ]
                )
            ]
        );


        // Create the service with the fake mailbox
        $service = new EmailService($mailbox);


        // Test the method
        $messages = $service->messages();


        // Assert we get both messages
        $this->assertCount(2, $messages);
    }
}
```

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

### Instantiate Mbox and Retrieve Messages

Source: https://imapengine.com/docs/usage/mbox

Instantiate the Mbox class with the path to your Mbox file and iterate over its messages. This method processes the file message-by-message, avoiding high memory usage.

```php
use DirectoryTree\ImapEngine\Mbox;


$mbox = new Mbox('/home/username/mail/stevebauman.mbox');


/** @var \DirectoryTree\ImapEngine\FileMessage $message */
foreach ($mbox->messages() as $message) {
    // Work with each FileMessage instance.
}
```

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

### Fake a Default Mailbox and Add Messages

Source: https://imapengine.com/docs/laravel/usage

Use `Imap::fake` to create a test mailbox. You can specify mailbox name, configuration, and initial folders. Fake messages can be added to folders after creation.

```php
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMailbox;
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;


// Fake the default mailbox
$mailbox = Imap::fake(
    mailbox: 'default',
    config: ['host' => 'imap.example.com', ...],
    folders: [new FakeFolder('inbox'), new FakeFolder('sent')],
);


$inbox = $mailbox->inbox();


// Add a fake message to the folder
$inbox->addMessage(
    new FakeMessage(
        uid: 1,
        flags: ['\Seen'],
        contents: 'Hello, world.',
    )
);


// Assert that the message is present
$this->get(route('mailbox.messages.index', [
    'mailbox' => 'default',
    'folder' => 'inbox',
]))->assertSee('Hello, world.');

```

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

### Renaming / Moving Folders

Source: https://imapengine.com/docs/usage/folders

How to rename or move a folder using the `move()` method on a Folder instance.

```APIDOC
## Renaming / Moving Folders

### Description
To rename a folder, use the `move()` method on the `Folder` instance. This method can also be used to move a folder to a different parent.

### Method
`move(string $newNameOrPath)`

### Endpoint
N/A (Method on Folder instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
$folder = $mailbox->folders()->find('OldName');
$folder->move('NewName');

// To move to a different parent folder:
$folder->move('NewParent/NewName');
```

### Response
#### Success Response (200)
No specific return value, operation is performed.

#### Response Example
N/A
```

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

### Create Folders Test with PHPUnit

Source: https://imapengine.com/docs/usage/testing

Test folder creation and message addition within a fake mailbox using PHPUnit. This snippet shows how to create a new folder, assert its existence, and add a message to it.

```php
public function testCreatingFolders(): void
{
    // Create a new folder
    $folder = $this->mailbox->folders()->create('Archive');


    // Assert the folder was created
    $this->assertNotNull($this->mailbox->folders()->find('Archive'));


    // Add a message to the new folder
    $folder->addMessage(
        new FakeMessage(
            uid: 1,
            flags: [],
            contents: 'From: sender@example.com\r\nSubject: Archived Email\r\n\r\nThis is an archived email.'
        )
    );


    // Assert the message was added
    $this->assertCount(1, $folder->messages()->get());
}
```

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

### Enable Debugging with FileLogger

Source: https://imapengine.com/docs/usage/configuration

Direct debug messages to a specified log file by setting the 'debug' option to a file path.

```php
use DirectoryTree\ImapEngine\Mailbox;


// Output debug messages to a file.
$mailbox = new Mailbox([
    // ...
    'debug' => '/path/to/log/file.log',
]);
```

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

### Connect with OAuth Token

Source: https://imapengine.com/docs/usage/configuration

Configure the Mailbox for OAuth authentication by providing the token as the password and setting the authentication method.

```php
use DirectoryTree\ImapEngine\Mailbox;


$token = 'your-oauth-token';


$mailbox = new Mailbox([
    'port' => 993,
    'username' => 'your-username',
    'password' => $token,
    'encryption' => 'ssl',
    'authentication' => 'oauth',
    'host' => 'imap.example.com',
]);
```

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

### Create IMAP Folder

Source: https://imapengine.com/docs/usage/folders

Create a new IMAP folder using the `folders()->create()` method. For nested folders, use the server's folder delimiter (usually '/') to separate parent and child names.

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

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

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

### Working with Subfolders

Source: https://imapengine.com/docs/usage/folders

Retrieve subfolders of a given folder or list all subfolders within a parent folder.

```APIDOC
## Working with Subfolders

### Description
You may retrieve subfolders of a folder using the `get()` method on the `FolderRepository` instance, often by using a glob pattern.

### Method
`get(string $pattern)`

### Endpoint
N/A (Method on FolderRepository instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
// Get a specific subfolder by its full path.
$subfolder = $mailbox->folders()->find('Parent/Child');

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

### Response
#### Success Response (200)
- **subfolders** (array) - An array of Folder instances representing the subfolders.

#### Response Example
```json
[
    {
        "name": "Child1",
        "path": "Parent/Child1",
        "delimiter": "/"
    },
    {
        "name": "Child2",
        "path": "Parent/Child2",
        "delimiter": "/"
    }
]
```
```

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

### Fetch Message Body Structure

Source: https://imapengine.com/docs/usage/messages

Fetches the MIME structure of messages using `withBodyStructure()`. This is more efficient than fetching the full body when only structure is needed.

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

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

### On-Demand Fetching for Address Handling

Source: https://imapengine.com/docs/usage/messages

Fetch email addresses such as 'from', 'to', and 'cc' on-demand using the `fetch: true` option.

```php
$from = $message->from(fetch: true);
$to = $message->to(fetch: true);
$cc = $message->cc(fetch: true);
```

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

### Fetch Message Headers On-Demand

Source: https://imapengine.com/docs/usage/messages

Fetch message headers like 'to', 'from', and 'date' on-demand when they are not already loaded. This is useful when you have a message instance but haven't preloaded its data.

```php
$to = $message->to(fetch: true);
$from = $message->from(fetch: true);
$date = $message->date(fetch: true);
$subject = $message->subject(fetch: true);
```

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

### Server-Side Sorting with Enum

Source: https://imapengine.com/docs/usage/messages

Demonstrates using the `ImapSortKey` enum for type-safe server-side message sorting.

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


$messages = $inbox->messages()->sortBy(ImapSortKey::Subject)->get();
```

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

### Mark Messages as Read Test with PHPUnit

Source: https://imapengine.com/docs/usage/testing

Demonstrates how to test marking messages as read using PHPUnit. This involves adding an unread message, asserting its initial state, marking it, and asserting the final state.

```php
public function testMarkingMessagesAsRead(): void
{
    // Get the inbox folder
    $inbox = $this->mailbox->inbox();


    // Add a new unread message
    $inbox->addMessage(
        new FakeMessage(
            uid: 2,
            flags: [], // No flags means unread
            contents: 'From: sender@example.com\r\nSubject: Unread Email\r\n\r\nThis is an unread email.'
        )
    );


    // Get the unread message
    $message = $inbox->messages()->find(2);


    // Assert it's not seen
    $this->assertFalse($message->isSeen());


    // Mark it as seen
    $message->markSeen();


    // Assert it's now seen
    $this->assertTrue($message->isSeen());
}
```

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

### On-Demand Fetching for Unloaded Message

Source: https://imapengine.com/docs/usage/messages

Demonstrates fetching message details like 'from', 'subject', and 'attachments' on-demand when the message data has not been preloaded.

```php
// Find a message without its data
$message = $inbox->messages()->find($uid);


// Fetch what you need on-demand
$from = $message->from(fetch: true);
$subject = $message->subject(fetch: true);
$attachments = $message->attachments(fetch: true);
```

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

### Fetch Full Message Content with IDLE

Source: https://imapengine.com/docs/usage/monitoring

Configures the IDLE method to fetch full message content, including body, headers, and attachments, by adjusting the MessageQuery. You must return the MessageQuery instance from the callback.

```php
use DirectoryTree\ImapEngine\MessageQuery;


$inbox->idle(function (Message $message) {
    // Handle new message...
}, function (MessageQuery $query) {
    // Adjust the query to fetch all message content...
    return $query->withBody()
        ->withHeaders()
        ->withFlags();
});
```

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

### Swap Mailbox Instance

Source: https://imapengine.com/docs/laravel/usage

Replace an existing mailbox instance in the container with a custom one using `Imap::swap`. This is useful for dependency injection testing.

```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;
use DirectoryTree\ImapEngine\Mailbox;


$customMailbox = new Mailbox([
    // Custom configuration
]);


Imap::swap('default', $customMailbox);

```

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

### Load Additional Message Data with Watch Command - Artisan

Source: https://imapengine.com/docs/laravel/usage

Specify additional message data to be loaded when monitoring mailboxes with the `imap:watch` command. Options include flags, headers, and body.

```bash
php artisan imap:watch default --with=flags,headers,body
```

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

### Checking Folder Capabilities

Source: https://imapengine.com/docs/usage/folders

Inspect the IMAP capabilities advertised by the server for the current folder, such as IDLE, MOVE, or QUOTA.

```APIDOC
## Checking Folder Capabilities

### Description
To inspect the IMAP capabilities advertised while working with a folder, call `capabilities()`. This method proxies to the mailbox's capability list, letting you verify support for features like `IDLE`, `MOVE`, or `QUOTA`.

### Method
`capabilities()`

### Endpoint
N/A (Method on Folder instance)

### Parameters
None

### Request Example
```php
$folder = $mailbox->folders()->find('Inbox');
$capabilities = $folder->capabilities(); // array

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

### Response
#### Success Response (200)
- **capabilities** (array) - An array of strings representing the supported IMAP capabilities.

#### Response Example
```json
[
    "IMAP4rev1",
    "IDLE",
    "NAMESPACE",
    "QUOTA",
    "MOVE"
]
```
```

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

### Fetch Message Body Structure

Source: https://imapengine.com/docs/usage/messages

Fetch the body structure of messages by first using `withBodyStructure()` on the message query and then iterating through the results. This allows inspection of MIME structure without downloading the full body.

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


foreach ($messages as $message) {
    if ($message->hasBodyStructure()) {
        $structure = $message->bodyStructure();
    }
}
```

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

### Retrieve and Interact with a Single Message

Source: https://imapengine.com/docs/usage/messages

Demonstrates retrieving the first message from the inbox and accessing its properties like UID, subject, sender, date, and attachments. Also shows how to mark, move, or delete the message.

```php
// Retrieve the first message from the inbox.
$message = $inbox->messages()->first();


// Get the message UID.
$message->uid();


// Get the message subject.
$message->subject();


// Get the message sender.
$message->from(); // Address


// Get the message from name and email.
$message->from()->name();
$message->from()->email();


// Get the message date.
$message->date(); // Carbon\Carbon


// Get the message's attachments.
foreach ($message->attachments() as $attachment) {
    // Get the attachment's filename.
    $attachment->filename();


    // Get the attachment's content type.
    $attachment->contentType();


    // Get the attachment's contents.
    $attachment->contents();




    // Get the attachment's extension.
    $extension = $attachment->extension();


    // Save the attachment to a local file.
    $attachment->save("/path/to/save/attachment.$extension");
}


// Mark the message as read.
$message->markSeen();


// Move the message to an "Archive" folder.
$message->move('Archive');


// Delete the message.
$message->delete();
```

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

### Connect to Mailbox Manually

Source: https://imapengine.com/docs/usage/connecting

Manually connect to the mailbox using the `connect` method. This method can throw `ImapConnectionException` for connection issues or `ImapCommandException` for authentication failures. Import necessary exception classes.

```php
use DirectoryTree\ImapEngine\Mailbox;
use DirectoryTree\ImapEngine\Exceptions\ImapCommandException;
use DirectoryTree\ImapEngine\Exceptions\ImapConnectionException;


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


try {
    $mailbox->connect();
} catch (ImapCommandException $e) {
    // Handle authentication failures (invalid credentials).
} catch (ImapConnectionException $e) {
    // Handle connection failures (network, server issues).
}

```

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

### Add Fake Messages to Folders

Source: https://imapengine.com/docs/usage/testing

Messages can be added to a `FakeFolder` either during its initialization or after its creation using the `addMessage` method. Each message requires a UID, flags, and its raw contents.

```php
// Add messages during folder initialization
$inbox = new FakeFolder(
    path: 'inbox',
    flags: ['\Inbox'],
    messages: [
        new FakeMessage(1, ['\Seen'], 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test Email\r\n\r\nThis is a test email.'),
        new FakeMessage(2, ['\Flagged'], 'From: another@example.com\r\nTo: recipient@example.com\r\nSubject: Important Email\r\n\r\nThis is an important email.'),
    ]
);
```

```php
// Or add messages after folder creation
$inbox = new FakeFolder('inbox');


$inbox->addMessage(
    new FakeMessage(
        uid: 1,
        flags: ['\Seen'],
        contents: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test Email\r\n\r\nThis is a test email.'
    )
);
```

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

### Check IMAP Folder Capabilities

Source: https://imapengine.com/docs/usage/folders

Inspect the IMAP capabilities advertised by the server for a folder using the `capabilities()` method. This allows checking for support of features like IDLE, MOVE, or QUOTA.

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


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

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

### Connect with Unencrypted Connection

Source: https://imapengine.com/docs/usage/configuration

Configure the Mailbox for an unencrypted connection by setting encryption to null and using the standard unencrypted port.

```php
use DirectoryTree\ImapEngine\Mailbox;


$mailbox = new Mailbox([
    'port' => 143,
    'encryption' => null,
    'username' => 'your-username',
    'password' => 'your-password',
    'host' => 'imap.example.com',
]);
```

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

### Select IMAP Folder

Source: https://imapengine.com/docs/usage/folders

Explicitly select an IMAP folder on the server using the `select()` method on the `Folder` instance. This is often done automatically by ImapEngine but can be forced.

```php
$folder->select();


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

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

### Server-Side Sorting with Search Criteria

Source: https://imapengine.com/docs/usage/messages

Combines server-side sorting with search criteria like `unseen()` and `from()`. Ensures efficient retrieval and ordering.

```php
// Get unread messages sorted by arrival time (newest first)
$messages = $inbox->messages()
    ->unseen()
    ->sortByDesc('arrival')
    ->get();


// Get messages from a sender sorted by subject
$messages = $inbox->messages()
    ->from('newsletter@example.com')
    ->sortBy('subject')
    ->get();
```

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

### Connect to Mailbox Automatically

Source: https://imapengine.com/docs/usage/connecting

The ImapEngine automatically connects to the mailbox when a method requiring connectivity is called. Ensure you have the Mailbox class imported.

```php
use DirectoryTree\ImapEngine\Mailbox;


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


// Automatically connects to the mailbox.
$folders = $mailbox->folders()->get();

```

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

### Manage Mailbox Configuration

Source: https://imapengine.com/docs/usage/connecting

Retrieve the entire mailbox configuration array or specific configuration values using the `config()` method. Use dot-notation for nested values.

```php
// Get the entire config.
$config = $mailbox->config();


// Get a specific config value with a default.
$port = $mailbox->config('port', 993);

```

```php
$proxyUsername = $mailbox->config('proxy.username');

```

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

### Access IMAP Folder Properties

Source: https://imapengine.com/docs/usage/folders

Retrieve properties of a `Folder` instance, such as its name, full path, and delimiter. Ensure the folder is retrieved first using `find()`.

```php
$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();
```

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

### Enable Debugging with EchoLogger

Source: https://imapengine.com/docs/usage/configuration

Configure the Mailbox to output debug messages to the console using the EchoLogger by setting the 'debug' option to true.

```php
use DirectoryTree\ImapEngine\Mailbox;


// No debug output.
$mailbox = new Mailbox([
    // ...
    'debug' => false,
]);


// Output debug messages to the console.
$mailbox = new Mailbox([
    // ...
    'debug' => true,
]);
```

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

### Attach Open Resources to a Draft Message

Source: https://imapengine.com/docs/usage/messages

You can attach open resources, such as file handles obtained with `fopen()`, to a draft message by including them in the `attachments` array.

```php
$resource = fopen('/path/to/report.csv', 'r');


$inbox->messages()->append(
    new DraftMessage(
        // ...
        attachments: [
            $resource,
        ]
    )
);

```

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

### Watch Default Mailbox for New Messages - Artisan

Source: https://imapengine.com/docs/laravel/usage

Use the `imap:watch` Artisan command to continuously monitor the default IMAP mailbox for new incoming messages. This command runs indefinitely until stopped.

```bash
php artisan imap:watch default
```

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

### Selecting a Folder

Source: https://imapengine.com/docs/usage/folders

Explicitly select a folder on the IMAP server for operations. Note: ImapEngine often handles this automatically.

```APIDOC
## Selecting a Folder

### Description
If you already have a `Folder` instance, you may explicitly select it on the IMAP server. This tells the server that you want to work with the messages within that folder. This isn't typically necessary as ImapEngine usually selects the folder automatically when needed.

### Method
`select(bool $force = false)`

### Endpoint
N/A (Method on Folder instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
$folder = $mailbox->folders()->find('Inbox');

// Select the folder.
$folder->select();

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

### Response
#### Success Response (200)
No specific return value, operation is performed.

#### Response Example
N/A
```

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

### Retrieving Folder Quotas

Source: https://imapengine.com/docs/usage/folders

Inspect storage limits and usage for a folder if the IMAP server exposes quota information.

```APIDOC
## Retrieving Folder Quotas

### Description
If your IMAP server exposes storage limits, you may inspect them through the `quota()` method. ImapEngine will throw an exception if the connected server does not advertise the `QUOTA` capability.

### Method
`quota()`

### Endpoint
N/A (Method on Folder instance)

### Parameters
None

### Request Example
```php
$folder = $mailbox->folders()->find('INBOX');
$quotas = $folder->quota(); // array
```

### Response
#### Success Response (200)
- **quotas** (array) - An associative array detailing quota usage and limits, typically keyed by quota root and resource type.

#### Response Example
```json
{
    "ROOT": {
        "STORAGE": {
            "usage": 42,
            "limit": 1024
        },
        "MESSAGES": {
            "usage": 150,
            "limit": 500
        }
    }
}
```
```

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

### Retrieve IMAP Folder Quotas

Source: https://imapengine.com/docs/usage/folders

Inspect storage limits for an IMAP folder if exposed by the server, using the `quota()` method. This method throws an exception if the server does not support the QUOTA capability.

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

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

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

### Configure IMAP Mailboxes in config/imap.php

Source: https://imapengine.com/docs/laravel/installation

Define your IMAP mailboxes within the 'mailboxes' array in the published config/imap.php file. You can set up multiple mailboxes, including custom ones like 'work'.

```php
return [
    'mailboxes' => [
        'default' => [
            // ...
        ],


        // You can define additional mailboxes here
        // 'work' => [
        //     'port' => env('WORK_IMAP_PORT', 993),
        //     'host' => env('WORK_IMAP_HOST'),
        //     // ...
        // ],
    ],
];
```

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

### Fetch Message Body Structure On-Demand

Source: https://imapengine.com/docs/usage/messages

Fetch the message's body structure on-demand using the `bodyStructure(fetch: true)` method. This is useful for inspecting MIME structure when the structure is not preloaded.

```php
$structure = $message->bodyStructure(fetch: true);
```

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

### Fake Mailbox Capabilities

Source: https://imapengine.com/docs/laravel/usage

You can specify the capabilities of a fake mailbox when creating it using the `capabilities` parameter. This allows testing logic that depends on specific IMAP extensions.

```php
$fake = Imap::fake('default', capabilities: ['IMAP4rev1', 'IDLE', 'UIDPLUS']);


$mailbox = Imap::mailbox('default');


$this->assertTrue($mailbox->hasCapability('IDLE'));

```

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

### Iterate Over Messages with Each()

Source: https://imapengine.com/docs/usage/messages

The `each()` method provides an alternative way to iterate over messages, processing them chunk by chunk. This is suitable when you need to perform an action on each message individually.

```php
use DirectoryTree\ImapEngine\Message;


$inbox->messages()->each(function (Message $message) {
    // Do something with the message.
}, chunkSize: 20);
```

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

### Test message queries with PHPUnit

Source: https://imapengine.com/docs/usage/testing

Use this snippet to test adding, retrieving, and deleting messages from an inbox using PHPUnit.

```php
public function testMessageQueries(): void
{
    // Get the inbox folder
    $inbox = $this->mailbox->inbox();


    // Add multiple messages
    $inbox->addMessage(new FakeMessage(1, ['\Seen'], 'From: sender1@example.com\r\nSubject: First Email\r\n\r\nFirst email content.'));
    $inbox->addMessage(new FakeMessage(2, [], 'From: sender2@example.com\r\nSubject: Second Email\r\n\r\nSecond email content.'));
    $inbox->addMessage(new FakeMessage(3, ['\Flagged'], 'From: sender3@example.com\r\nSubject: Important Email\r\n\r\nImportant email content.'));


    // Get all messages
    $allMessages = $inbox->messages()->get();
    $this->assertCount(3, $allMessages);


    // Test finding a specific message
    $message = $inbox->messages()->find(2);
    $this->assertEquals('Second Email', $message->subject());


    // Test message deletion
    $inbox->messages()->destroy(2);
    $this->assertNull($inbox->messages()->find(2));
    $this->assertCount(2, $inbox->messages()->get());
}
```

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

### Advanced Mailbox Configuration

Source: https://imapengine.com/docs/usage/configuration

Utilize advanced configuration options for fine-tuning IMAP connections, including timeout, debug, certificate validation, and proxy settings.

```php
use DirectoryTree\ImapEngine\Mailbox;


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