Download the PHP package dcodegroup/laravel-logged-inbound-email without Composer

Laravel Inbound Email

Multi-provider inbound email webhooks for Laravel. Incoming HTTP requests are verified per provider, normalized into an InboundMessage DTO, and handled asynchronously via one queued job class you configure.

Supported providers: Mailgun, Postmark, SendGrid, Amazon SES (via SNS), Mailpit, Resend.

Requirements: PHP ^8.4, Laravel 12.x+ (Illuminate ^12–^13 per composer.json).

Install

The package registers its service provider automatically (extra.laravel.providers in Composer).

Publish configuration (recommended)

This copies config/inbound-email.php into your app. Until you publish, the package merges the same defaults from the vendor file.

Routes

Routes are registered under a configurable prefix (default webhooks/inbound). Middleware defaults to api (no session/CSRF). If you switch to web, add these paths to VerifyCsrfToken $except or use stateless verification.

Single-tenant (default)

organization_in_route is false. Pattern:

Examples (default prefix):

Multi-tenant / SaaS

Set INBOUND_EMAIL_ORG_IN_ROUTE=true or config(['inbound-email.organization_in_route' => true]). Pattern:

Example: POST https://your-app.test/webhooks/inbound/acme-corp/mailgun

• {orgAlias} — Your tenant slug (per organization). It must match the regex in organization_alias_pattern (default: slug-like ASCII; see config/inbound-email.php).
• The job receives $orgAlias as a separate constructor argument from the normalized message array (see Processing messages).

Switching modes: With multi-tenant routes enabled, old single-segment URLs such as POST /webhooks/inbound/mailgun are not registered. Point each provider’s webhook at the per-organization URL instead.

Prefix: INBOUND_EMAIL_ROUTE_PREFIX or config('inbound-email.route_prefix') (no leading/trailing slashes required in env; the package trims as needed).

Tenant column and relationship (opt-in)

By default the inbound_emails table has no tenant_id column at all. Set INBOUND_EMAIL_MULTI_TENANT_ENABLED=true (and INBOUND_EMAIL_TENANT_MODEL to your tenant model's FQCN) before running php artisan migrate in your app, and the migration adds a nullable, indexed tenant_id column, and InboundEmail::tenant() becomes available as a belongsTo relation to that model.

The package never populates tenant_id itself — your app sets it on the row after it exists.

This is a one-time, initial-setup flag. Flipping it after the table has already been migrated does not retroactively add or drop the column; write your own follow-up migration if you enable multi-tenancy later. Calling tenant() while the flag is off returns null rather than a relation instance.

Email-based tenant discovery

An alternative to organization_in_route for setups where the webhook route isn't controllable (e.g. a fixed provider URL): identify the tenant from the recipient address itself. The package's default technique is plus-addressing, {tenant_identifier}+{process}@domain.

Set INBOUND_EMAIL_EMAIL_BASED_TENANCY_ENABLED=true or config(['inbound-email.email_based_tenancy_enabled' => true]). Unlike organization_in_route, this is not mutually exclusive — both strategies can be enabled at the same time. When both produce a tenant identifier and they disagree, the route-derived value wins (plus-addressing is a fallback, not an override).

The resolved identifier is stored on InboundEmail::organization_alias, same as route-based discovery.

To use your own scheme instead of plus-addressing, set INBOUND_EMAIL_TENANT_RESOLVER (or config(['inbound-email.tenant_resolver' => ...])) to the FQCN of a class implementing Dcodegroup\LaravelLoggedInboundEmail\Contracts\EmailBasedTenantResolver:

The class is resolved via the container, so it may declare its own constructor dependencies.

Configuration overview

Provider secrets and options (set only what you use):

Full keys and comments live in the published config/inbound-email.php.

Processing messages

The webhook controller verifies the request, builds an InboundMessage, and dispatches your job class from config('inbound-email.job'). There is no extra wrapper job.

Job requirements

1. Implement Dcodegroup\LaravelLoggedInboundEmail\Contracts\ProcessesInboundEmail (extends ShouldQueue).
2. Use Illuminate\Foundation\Bus\Dispatchable (and typically Queueable, InteractsWithQueue, SerializesModels).
3. array $message — Serialized InboundMessage (InboundMessage::toArray() shape).
4. Multi-tenant only: second constructor parameter string $orgAlias — value of {orgAlias} from the URL. When organization_in_route is false, the package dispatches with only $message, so a one-argument constructor remains valid for single-tenant setups.

Rebuild the DTO in handle():

Dispatch behavior

Queue connection and queue name from config are applied to the pending dispatch when set.

Example job

Registering your job class

Environment or published config:

Runtime (e.g. AppServiceProvider):

Development