README

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 10.x+ (Illuminate ^10–^13 per composer.json).

Install

composer require touqeershafi/laravel-inbound-email

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

Publish configuration (recommended)

php artisan vendor:publish --tag=inbound-email-config

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:

POST {prefix}/{provider}

Examples (default prefix):

Multi-tenant / SaaS

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

POST {prefix}/{orgAlias}/{provider}

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

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 Touqeershafi\LaravelInboundEmail\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():

$inbound = \Touqeershafi\LaravelInboundEmail\InboundMessage::fromArray($this->message);

Dispatch behavior

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

Example job

use Illuminate\Bus\Queueable;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Touqeershafi\LaravelInboundEmail\Contracts\ProcessesInboundEmail;
use Touqeershafi\LaravelInboundEmail\InboundMessage;

final class HandleInboundEmail implements ProcessesInboundEmail
{
    use Dispatchable;
    use InteractsWithQueue;
    use Queueable;
    use SerializesModels;

    /**
     * @param  array<string, mixed>  $message
     */
    public function __construct(
        public array $message,
        public string $orgAlias = '',
    ) {}

    public function handle(): void
    {
        $inbound = InboundMessage::fromArray($this->message);

        // When using organization_in_route, resolve the tenant from $this->orgAlias.
        // Use $inbound->provider, ->subject, ->text, ->metadata, etc.
    }
}

Registering your job class

Environment or published config:

INBOUND_EMAIL_JOB=App\Jobs\HandleInboundEmail

Runtime (e.g. AppServiceProvider):

$this->app->boot(function (): void {
    config(['inbound-email.job' => \App\Jobs\HandleInboundEmail::class]);
});

Development

composer test      # PHPUnit
composer analyse   # PHPStan
composer format    # Laravel Pint