laravel-mailbox

Laravel Mailbox lets a Laravel application react to incoming email the same way it reacts to incoming HTTP requests. Instead of only sending mail, the package listens for inbound messages delivered through a webhook-driven provider and dispatches each one to a matching handler defined with the same {parameter} route-pattern syntax Laravel developers already use for HTTP routes.

Mailboxes can be defined to match on the sender (Mailbox::from), any recipient (Mailbox::to), CC/BCC addresses, or the subject line, with optional regular-expression constraints on captured parameters. A catchAll handler runs for every inbound message and a fallback handler runs only when nothing else matched, giving applications a predictable way to build features like support ticket creation, comment-by-email, or newsletter reply handling.

Delivery is provider-agnostic: built-in drivers translate webhook payloads from Mailgun, SendGrid, Postmark, and MailCare into a common InboundEmail Eloquent model (parsed with zbateson/mail-mime-parser), plus a log driver for local development. InboundEmail exposes typed accessors for subject, body, attachments, and headers, can reply in-thread via Laravel’s mailer, and can detect auto-replies to avoid bounce loops.

What You Get

• Laravel-route-style matching (Mailbox::from, to, cc, bcc, subject) with {parameter} capture syntax and regex constraints
• Pluggable provider drivers for Mailgun, SendGrid, Postmark, and MailCare, plus a local log driver for development
• A typed InboundEmail Eloquent model with subject, body, headers, attachments, and auto-reply detection
• catchAll and fallback handlers for unmatched or universal message handling
• Built-in reply/forward helpers that thread replies via In-Reply-To headers
• An artisan cleanup command plus a configurable retention window for stored inbound emails

Common Use Cases

• Turning support requests emailed to a catch-all address into tickets or database records
• Letting users reply to a notification email to comment on or update a resource in-app
• Parsing structured replies (e.g. {ticket_id}@support.example.com) to route email to the right handler
• Building a lightweight email-to-webhook bridge for services that only speak SMTP
• Logging and inspecting inbound email locally during development before wiring a real provider

Under The Hood

Architecture The MailboxServiceProvider registers two singletons: a Router (bound to the mailbox facade accessor) that owns a RouteCollection of user-defined mailbox rules, and a MailboxManager extending Laravel’s Manager class to instantiate the configured provider driver. Each driver (Mailgun, SendGrid, Postmark, MailCare, Log) implements DriverInterface::register(), wiring a provider-specific HTTP endpoint (guarded by an aliased laravel-mailbox basic-auth middleware) to a matching Controller and FormRequest that convert the raw webhook payload into a common InboundEmail Eloquent model, then hand it to Router::callMailboxes(). Inside the router, each Route compiles its {param} pattern into a regex (via the HandlesParameters/HandlesRegularExpressions concerns) and is matched against the relevant email field; matching routes run in sequence, with catchAll and fallback routes layered on top. The InboundEmail model is the shared contract between every driver and the routing layer, so changing its public surface would ripple through every controller and route matcher. It’s a small, cleanly layered adapter-plus-router design rather than a monolith.

Tech Stack Built for PHP ^8.1 against Laravel’s Illuminate components (container, database, log, routing, support) spanning versions 10 through 13, so it tracks current Laravel releases closely. Inbound MIME parsing is delegated to zbateson/mail-mime-parser (v2-v4 supported) and reply-quote stripping to willdurand/email-reply-parser; outbound replies use Symfony Mime headers directly. The package ships as a standard Composer/Packagist library with a Laravel auto-discovery service provider and facade, no separate build step, and is style-checked via StyleCI.

Code Quality The test suite (nine files under tests/) covers route matching for every match type (from/to/cc/bcc/subject), parameter extraction, regex constraints, the console cleanup command, and provider controllers (Mailgun, Postmark), written with modern PHPUnit attribute syntax (#[Test], #[DataProvider]) against orchestra/testbench. Public methods on InboundEmail and the routing classes carry explicit return-type declarations (: bool, : string, : array), and naming follows Laravel conventions closely, which keeps the API predictable for Laravel developers. Error handling is largely implicit — invalid or unparseable messages are filtered via an isValid() check rather than raising typed exceptions — and there’s a GitHub Actions workflow running the test suite on push.

What Makes It Unique The distinctive design choice is mapping Laravel’s HTTP-routing mental model onto inbound email: the same {parameter} capture syntax, regex where() constraints, and catch-all/fallback semantics developers use for web routes apply directly to matching senders, recipients, and subjects. Combined with a driver abstraction that normalizes several different inbound-email webhook formats (Mailgun, SendGrid, Postmark, MailCare) into one model, it turns email-driven features into ordinary Laravel application code rather than one-off webhook parsing per provider. The pattern itself is a straightforward application of familiar routing concepts rather than a novel algorithm, but the execution is well fitted to its niche.