Looking to hire Laravel developers? Try LaraJobs

inboundr-laravel maintained by inboundr

Description
Laravel integration for Inboundr: a verified webhook route that turns inbound email into events, and the API client from the container.
Author
Last update
2026/11/20 17:56 (dev-main)
License
Downloads
0

Comments
comments powered by Disqus

Inboundr

Inboundr for Laravel

Packagist license

Laravel integration for Inboundr: a webhook route that verifies each delivery and fires an event, and the API client from the container. Built on inboundr/inboundr.

Install

composer require inboundr/inboundr-laravel

Laravel 12 or 13, PHP 8.2+.

Add your keys to .env:

INBOUNDR_API_KEY=inb_123456789
INBOUNDR_WEBHOOK_SECRET=whsec_123456789

The webhook secret is the whsec_ value returned when you create the endpoint. The API key is only needed for calling the API.

Receive email

Register the route in routes/web.php:

Route::inboundrWebhook('/inbound');

Point your Inboundr endpoint at https://your-app.com/inbound. Every delivery is verified before anything runs; anything that fails gets a 400. The route skips CSRF protection, which a webhook can't pass.

Then listen for the event:

use Inboundr\Laravel\Events\InboundEmailReceived;

class HandleInboundEmail
{
    public function handle(InboundEmailReceived $event): void
    {
        $email = $event->email;

        logger()->info("{$email['from']}: {$email['subject']}");
    }
}

Laravel discovers listeners in app/Listeners automatically. Implement ShouldQueue to handle mail on a queue instead of in the request.

$event->email has id, threadId, from, to, cc, subject, text, html, attachments, verdicts and receivedAt.

Retries

Inboundr retries a delivery until it gets a 2xx. The route remembers each delivery id for a day and answers repeats with 204 without firing the event again. If a listener throws, the id is forgotten, so the retry is handled.

Missing body

Some hosts drop the request body. The delivery still carries a signed email id; the route verifies it, fetches the email through the API (this needs INBOUNDR_API_KEY) and fires the same event with $event->bodyWasMissing set to true.

Call the API

Type-hint the client anywhere the container resolves:

use Inboundr\Inboundr;

public function __construct(private Inboundr $inboundr) {}

$this->inboundr->emails->reply($emailId, ['text' => "Thanks, we're on it."]);

Or use the facade:

use Inboundr\Laravel\Facades\Inboundr;

$page = Inboundr::emails()->list(['direction' => 'inbound', 'limit' => 20]);

Every method of the PHP SDK is available.

Configuration

To change the defaults, publish the config file:

php artisan vendor:publish --tag=inboundr-config
Key Default
api_key INBOUNDR_API_KEY
base_url https://inboundr.net
timeout 30 Seconds.
webhook.secret INBOUNDR_WEBHOOK_SECRET
webhook.tolerance 300 Maximum signature age, in seconds.
webhook.dedupe true Skip deliveries already handled.
webhook.dedupe_ttl 86400 How long to remember a delivery id, in seconds.
webhook.cache_store default store Cache store for delivery ids.

Your own controller

To handle deliveries yourself, use the middleware on your route. It answers 400 to anything unverified and puts the event on the request:

use Inboundr\Laravel\Http\Middleware\VerifyInboundrWebhook;

Route::post('/inbound', InboundController::class)
    ->middleware(VerifyInboundrWebhook::class)
    ->withoutMiddleware(\Inboundr\Laravel\Routes::CSRF_MIDDLEWARE);

// In the controller:
$event = $request->attributes->get(VerifyInboundrWebhook::EVENT);

Route::inboundrWebhook() is a macro, which static analysis can't see. \Inboundr\Laravel\Routes::webhook('/inbound') does the same and is fully typed.

Contributing

See CONTRIBUTING.md.

License

MIT