Search by

pylesoft / mailbox

ianfortier

Multi-provider mailbox abstraction for Laravel

Package info

github.com/pylesoft/mailbox

pkg:composer/pylesoft/mailbox

Statistics

Installs: 1 262

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 1

v0.3.1 2026-11-12 20:11 UTC

README

CI workflow PHPStan PHP Laravel License

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 MessageMatcher and 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-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.
  • Provider SDK -- explicit grants, capability differences, durable host boundaries and acceptance limits.

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 --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
  1. 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.