ImapEngine is a simple API for managing mailboxes without the PHP extension

Published on February 25th, 2025 by Eric L. Barnes

Steve Bauman talks with us about his newest package, ImapEngine, which provides a simple API for managing mailboxes without the PHP extension and his integration into a new product called Spamwise.

Watch our full interview:

Or you can listen in your podcast app of choice:

ImapEngine Examples:

Connecting to mailboxes

To connect to a mailbox, create a new Mailbox instance with the configuration options:

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

To connect using an OAuth token, pass the token as the password, and set the authentication method to oauth:

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

Retrieving Folders

// Get the mailbox's inbox folder.
$inbox = $mailbox->inbox();
 
// Get all the mailbox's folders.
$folders = $mailbox->folders()->get();
 
// Get all mailbox's folders matching a glob pattern.
$folders = $mailbox->folders()->get('*/Subfolder');
 
// Find a specific folder.
$folder = $mailbox->folders()->find('Folder Name');
 
// Find a specific folder (or fail).
$folder = $mailbox->folders()->findOrFail('Missing Folder');

Retrieving Messages

ImapEngine provides a fluent, chainable API for building advanced message search queries.

This allows you to combine various search criteria and options to retrieve exactly the messages you need:

// Get the inbox folder.
$inbox = $mailbox->folders()->inbox();
 
// Get all message UIDs in the inbox.
$messages = $inbox->messages()->get();
 
// Get all messages in the inbox with various content enabled.
$messages = $inbox->messages()
    ->withHeaders() // Enable fetching message headers.
    ->withFlags() // Enable fetching message flags.
    ->withBody() // Enable fetching message bodies (including attachments).
    ->get();