README

Raw-socket IMAP client for PHP 8.4+ — zero dependencies, full IMAPv4rev2 support.

Designed from scratch for modern PHP: speaks IMAP directly over sockets, fetches only what you ask for, and gives you full control over the protocol when you need it.

• 🔌 Raw socket connection with TLS / STARTTLS
• 📦 Zero runtime dependencies (only ext-mbstring + ext-openssl)
• 📜 IMAPv4rev2 (RFC 9051) with 18+ extensions
• 🪶 Lazy loading — bodies and attachments fetched on demand
• 🎯 BODYSTRUCTURE-first — 50 MB email with a 12 KB text body? You download 12 KB
• 🔎 Fluent search builder, IDLE + NOTIFY push, OAuth2 with token refresh

Installation

composer require d4ry/imap-client

Requirements: PHP 8.4+, ext-openssl, ext-mbstring

Quick Start

use D4ry\ImapClient\Auth\PlainCredential;
use D4ry\ImapClient\Config;
use D4ry\ImapClient\Mailbox;

$mailbox = Mailbox::connect(new Config(
    host: 'imap.example.com',
    credential: new PlainCredential('user@example.com', 'password'),
));

foreach ($mailbox->inbox()->messages() as $message) {
    echo $message->envelope()->subject . "\n";

    foreach ($message->attachments()->nonInline() as $attachment) {
        $attachment->save('/tmp');
    }
}

$mailbox->disconnect();

Search Example

use D4ry\ImapClient\Search\Search;

$search = (new Search())
    ->unread()
    ->from('notifications@github.com')
    ->after(new DateTime('-7 days'));

foreach ($mailbox->inbox()->messages($search) as $message) {
    printf("[%s] %s\n", $message->envelope()->from[0], $message->envelope()->subject);
    echo $message->hasHtml() ? $message->html() : $message->text();
}

More examples and the full API are in the documentation.

Benchmarks

Head-to-head benchmarks against webklex/php-imap and ddeboer/imap, run against a local Dovecot in Docker with 1 warmup + 10 measured runs per scenario. Time = median ms, memory = per-scenario delta in MB. Bold marks the row winner.

Results depend heavily on how each library is called — see docs/benchmarks.md for the full 7-scenario table and methodology. The adapters and raw data are auditable in D4ryB3rry/imap-client-benchmarks; PRs that improve any adapter are welcome.

Documentation

Guides

• Getting Started
• Configuration
• Authentication (Plain, Login, OAuth2)
• Folders
• Messages
• Attachments
• Search
• IDLE (Push Notifications)
• Error Handling

Reference

• Architecture
• Supported Extensions
• Benchmarks
• Testing

Advanced

• Raw Connection Access
• Namespace
• Recording & Replay

License

Licensed under the Apache License 2.0.