pylesoft / mailbox
Multi-provider mailbox abstraction for Laravel
Requires
- php: ^8.2
- egulias/email-validator: ^4.0.4
- guzzlehttp/guzzle: ^7.0
- illuminate/cache: ^12.0||^13.0
- illuminate/console: ^12.0||^13.0
- illuminate/contracts: ^12.0||^13.0
- illuminate/database: ^12.0||^13.0
- illuminate/filesystem: ^12.0||^13.0
- illuminate/http: ^12.0||^13.0
- illuminate/support: ^12.0||^13.0
- laravel/prompts: ^0.3
- psr/http-message: ^2.0
- symfony/mime: ^7.4.22 || ^8.1.10
- zbateson/mail-mime-parser: ^4.0.8
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.20
- orchestra/testbench: ^10.0||^11.0
- orchestra/workbench: ^10.0.8||^11.0
- pestphp/pest: ^3.0||5.x-dev
- pestphp/pest-plugin-arch: ^3.0||5.x-dev
- pestphp/pest-plugin-laravel: ^3.0||5.x-dev
- pestphp/pest-plugin-type-coverage: ^3.0||5.x-dev
Suggests
None
Provides
None
Conflicts
- php-di/php-di: <6.3.0
Replaces
None
- dev-master
- v0.3.1
- v0.3.0
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-fix/outlook-recovery-pages
- dev-fix/6629-graph-request-lifetime
- dev-feat/graph-delta-batch
- dev-fix/received-attachment-transport-retries
- dev-fix/graph-continuation-mailbox-encoding
- dev-feat/mailbox-provider-sdk
- dev-feat/mailbox-message-isolation
- dev-helpdesk-5834-attachment-memory
- dev-fix/5703-graph-attachment-memory
- dev-fix/provider-invalid-json-response
- dev-codex/laravel-13-compat
- dev-codex/retry-transport-failures
- dev-desloppify
- dev-copilot/sub-pr-7
- dev-feat/native-rule-tree-attachment-extension
- dev-feat-all-folders
- dev-feat-renaming
- dev-feat-docs
- dev-codex/plan-google-workspace-parity
- dev-codex/fix-phpstan-bootstrap-error
This package is auto-updated.
Last update: 2026-11-12 22:28:55 UTC
README
A unified, driver-based mailbox SDK for Laravel.
What Makes It Great
- Shared read interfaces -- access Microsoft Graph and Gmail through the same message, folder and attachment contracts, with optional provider capabilities for submission and notifications.
- 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
MessageMatcherand expose filterable fields to your UI.
Quick Look
use Pyle\Mailbox\Facades\Mailbox; use Pyle\Mailbox\Enums\WellKnownFolder; $invoices = Mailbox::mailbox('invoices@acme.com') ->messages() ->inFolder(WellKnownFolder::INBOX) ->where('isRead', false) ->take(25) ->get(); // Collection<int, MessageDto>
Configured application credentials or Workspace delegation power this example. For delegated user access, explicitly select your host-owned grant with Mailbox::forGrant(). Use bounded synchronization when you need resumable progress rather than a selected collection.
Supported Drivers
| Driver | Key | Auth Model |
|---|---|---|
| Microsoft Graph | ms-graph |
Configured application credentials or explicit delegated grants |
| Gmail | gmail |
Workspace service-account delegation or explicit delegated grants |
Personal, organizational and shared-mailbox behavior depends on the selected authorization and provider permissions. The provider SDK guide describes implemented capabilities and host responsibilities. Account-specific live acceptance remains blocked; local fixtures do not establish provider parity or release readiness.
Tip The alias key
google-workspaceresolves to thegmaildriver, 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.
- Provider SDK -- explicit grants, capability differences, durable host boundaries and acceptance limits.
Contributing
- Create a feature branch from the latest default branch.
- Implement changes with tests and documentation updates where applicable.
- Run the full quality suite:
vendor/bin/pest --parallel --processes=2 vendor/bin/phpstan analyse --debug --no-progress vendor/bin/pint --dirty --format agent composer validate --strict composer check-platform-reqs composer audit --locked
- Open a pull request with a clear summary, migration impact, and validation notes.
The testing guide separates supported PHP/Laravel graphs, SDK-only and SQLite tests, serial opt-in wire checks, and actual consumer validation.
License
Mailbox is open-source software licensed under the MIT license.