pylesoft/mailbox

Multi-provider mailbox abstraction for Laravel

dev-master 2026-03-05 14:46 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.0
• illuminate/cache: ^12.0
• illuminate/console: ^12.0
• illuminate/contracts: ^12.0
• illuminate/database: ^12.0
• illuminate/filesystem: ^12.0
• illuminate/http: ^12.0
• illuminate/support: ^12.0
• laravel/prompts: ^0.3
• psr/http-message: ^2.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.20
• orchestra/testbench: ^10.0
• orchestra/workbench: ^10.0.8
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• pestphp/pest-plugin-type-coverage: ^3.0

MIT

README

A unified, driver-based mailbox SDK for Laravel.

What Makes It Great

• One API, every provider -- swap between Microsoft 365 and Google Workspace without changing a line of application code.
• Fluent query builder -- filter messages by folder, read status, date range, and free-text search with an Eloquent-like syntax.
• Delta sync built in -- track changes with provider-native delta tokens so you only process what is new.
• Typed DTOs everywhere -- every message, folder, and attachment comes back as a strict, readonly data-transfer object.
• Retry, rate-limit, and batch -- resilient HTTP handling with configurable backoff, concurrency locks, and queue-aware retry strategies.
• Rule matching engine -- evaluate inbound messages against user-defined filter rules with MessageMatcher and expose filterable fields to your UI.

Quick Look

use Pyle\Mailbox\Facades\Mailbox;
use Pyle\Mailbox\Enums\WellKnownFolder;

$invoices = Mailbox::mailbox('[e-mail]')
    ->messages()
    ->inFolder(WellKnownFolder::INBOX)
    ->where('isRead', false)
    ->take(25)
    ->get(); // Collection<int, MessageDto>

Five lines of code -- that is all it takes to pull the 25 most recent unread messages from any supported provider. Mailbox handles authentication, pagination, and provider-specific quirks behind the scenes so you can focus on what your application does with those messages.

Supported Drivers

Driver	Key	Auth Model
Microsoft 365 (Graph API)	ms-graph	Client credentials with mailbox-scoping policies
Google Workspace (Gmail API)	gmail	Service-account delegation or user OAuth

Tip The alias key google-workspace resolves to the gmail driver, so you can use whichever name feels more natural in your configuration.

Documentation

Full documentation lives in the docs/ directory. Here are the pages you will reach for most often:

• Installation -- requirements, Composer setup, publishing config and migrations.
• Configuration -- every option in config/mailbox.php, explained.
• Quickstart -- a working example in under two minutes.
• Messages -- querying, reading, moving, and deleting messages.
• Authentication -- provider-specific credential setup for MS Graph and Gmail.

Contributing

1. Create a feature branch from the latest default branch.
2. Implement changes with tests and documentation updates where applicable.
3. Run the full quality suite:

vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint --test

1. Open a pull request with a clear summary, migration impact, and validation notes.

CI runs on PHP 8.2, 8.3, and 8.4 with latest dependencies, plus a PHP 8.2 prefer-lowest lane.

License

Mailbox is open-source software licensed under the MIT license.