Imapengine Laravel Laravel Package

Product Decisions This Supports

• Feature scoping: inbound email as a scoped sprint, not a quarter. The package supplies the full skeleton of a mailbox-ingestion feature — publishable config, a fluent Mailbox/Message API, an imap:watch Artisan command with IDLE and long-polling modes, and lifecycle events (MessageReceived, MailboxSynced, MailboxWatchAttemptsExceeded). That's enough to stand up a demo of shared-inbox triage, sales-lead capture, reply detection, invoice/document intake, or bounce processing this sprint and get a real go/no-go on the roadmap item instead of another round of speculation.
• Build vs. buy — with a deliberately small buy. The alternative isn't a commercial email platform; it's an engineer hand-rolling an adapter over raw IMAP. What we're actually buying is service-provider bindings, config publishing, facade/container resolution, a watch command, and event dispatch. The protocol work lives in the upstream directorytree/imapengine core. Framed that way, the decision is small enough to make in one meeting and cheap enough to reverse.
• A deployment-target decision disguised as a library choice. The load-bearing README claim is "without the PHP extension." Native ext-imap is missing or a provisioning tax on shared hosting, managed PHP platforms, and slim container images. Adopting this can retire an infrastructure blocker outright — and may let us avoid pricing a platform migration in quarters.
• Roadmap commitment: define what "real-time" means before engineering commits. imap:watch --method lets us choose IDLE (near-instant, one persistent connection per mailbox) or long-polling (simpler, latent, far lower connection pressure). That is a product sentence — "new mail appears in under five seconds" vs. "within two minutes" — and the architecture and capacity plan follow from it. Force that sentence to be written first.
• Use-case fit is narrow and knowable. Best fit: a long-lived mailbox we watch continuously inside a conventional Laravel app with a queue worker and a supervised process. Poor fit: serverless or short-request services, high-volume batch backfill, or anything where we don't own a daemon.
• Not a "solved inbox" decision. MIME parsing depth, attachment handling, credential storage/encryption, rate limiting, retry/backoff, dedupe keys, and connection pooling are all our build cost. The package is transport. Budgeting those as if included is how this line item doubles.

When to Consider This Package

Adopt when all of these hold:

• We're on Laravel 10–13 / PHP 8.1+ and the target environment runs a queue worker plus a supervised long-lived process.
• The requirement is genuinely inbound mail — capture, triage, reply detection, document intake — not outbound sending or marketing email.
• We want several named mailbox connections side by side (shared inboxes, per-tenant support addresses) rather than a single global account.
• ext-imap is unavailable or annoying in our runtime and we'd rather not own that provisioning problem.
• The target mailboxes are reachable with host/port/username/password — see the gate below.
• We can put a thin internal interface (EmailIngestor) in front of it on day one, so swapping implementations later is a contained change.

Hard gate before any date is committed: provider authentication. Basic-auth IMAP is retired for Exchange Online, and Google expects OAuth or app passwords. Token refresh, OAuth flows, and expiry handling are not evidenced in the supplied documentation. If our priority mailboxes need OAuth2 and the stack doesn't provide it, that one unknown invalidates the approach — test it in week one, not at integration time.

Look elsewhere when:

• Mailboxes require OAuth2/OIDC and app passwords aren't an option — a commercial email API with managed auth is the lower-risk buy.
• The deployment model is serverless or purely request-driven; the watch model has nowhere to live.
• The need is bulk historical sync, high-volume batch ingestion, or outbound/transactional sending.
• We can't accept effectively being the support tier: 38 stars, zero dependents, one maintainer org, MIT, no SLA, thin issue corpus. We would be among the earliest production users and must own provider quirks, connection troubleshooting, and parsing edge cases internally.
• The team can't commit an owner for the ingestion path — a quietly dead mailbox looks identical to a quiet one, and nobody notices until a customer does.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is a small MIT-licensed Laravel integration that lets us add inbound email to an existing app in a sprint rather than a quarter. It removes a runtime dependency (ext-imap) that has blocked us before, and it costs nothing but an engineer's time to evaluate — we can have a working demo against a real mailbox in two days. The decision in front of you is not a platform commitment; it's a scoped spike with a defined exit. The one thing we must settle first is whether our target mailboxes accept the authentication method the library supports — that's a week-one test with a clear answer either way.

For engineering — the honest summary: A thin, Laravel-native binding over a pure-PHP IMAP client. We get a service provider, publishable config, facade, imap:watch with IDLE or long-polling, and events we can map onto our existing watch → event → queued job → domain handler pattern. No new idiom to teach. Constraints: PHP 8.1+, Laravel 10–13, async queue driver for anything nontrivial, and an explicit core-library version pinned in composer.json. The risk surface is mostly upstream — protocol behavior, reconnect logic, MIME depth — so the evaluation must cover the core library too.

What we're explicitly not buying: OAuth flows, MIME/attachment edge cases, credential encryption, rate limiting, backoff, dedupe, or support. Name those as our build cost in the same breath as the adoption recommendation, and the pitch survives the moment someone asks "so IMAP is solved?"

Ask: two engineering days for a spike (one real mailbox, both watch modes, a deliberately severed connection to prove MailboxWatchAttemptsExceeded produces an actionable alert), a thin EmailIngestor interface as day-one exit insurance, and a Dovecot/GreenMail CI fixture before ingestion logic is written. Revisit build-vs-reuse after one mailbox runs in production — the interface makes that review cheap either way.