Dev.to WebDev 🛠 Dev 👁 0 📖 2 min read

Receive inbound email in Laravel with a webhook

Receive inbound email in Laravel with a webhook ReceiveHQ accepts SMTP on your domain (MX → mx.receivehq.com) and POSTs parsed mail to an HTTPS URL. This example is a Laravel route that reads the default Postmark JSON

Receive inbound email in Laravel with a webhook

ReceiveHQ accepts SMTP on your domain (MX → mx.receivehq.com) and POSTs parsed mail to an HTTPS URL. This example is a Laravel route that reads the default Postmark JSON format and checks optional Basic auth.

1. ReceiveHQ setup

  1. Sign up at receivehq.com (magic link).
  2. Create a tenant, add an inbound domain, and point MX at mx.receivehq.com.
  3. Create a webhook endpoint: https://yourapp.com/inbound/receivehq, format Postmark (JSON) (payloadFormat id postmark), and optional Basic auth on the endpoint (console, or basicAuthUser / basicAuthPass on the MCP create tools).
  4. Send a test and open the delivery in the console.

ReceiveHQ will send POST with Content-Type: application/json, User-Agent: receivehq-inbound/1.0, and, if you configured it, Authorization: Basic <base64(user:pass)>. It does not send Postmark HMAC headers.

2. Route and controller

Exclude the route from CSRF verification (it is a machine POST, not a form). In modern Laravel, put the URI in validateCsrfTokens / the CSRF except list, or define the route in a file that does not use the web CSRF middleware.

routes/api.php (already CSRF-free in a typical app):

use App\Http\Controllers\InboundMailController;

Route::post('/inbound/receivehq', [InboundMailController::class, 'store']);
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;

class InboundMailController extends Controller
{
    public function store(Request $request): Response
    {
        $user = (string) config('services.receivehq.user');
        $pass = (string) config('services.receivehq.password');

        if ($user !== '' || $pass !== '') {
            $ok = hash_equals($user, (string) $request->getUser())
                && hash_equals($pass, (string) $request->getPassword());
            if (! $ok) {
                return response('Unauthorized', 401);
            }
        }

        $from = $request->input('From');       // bare email address
        $subject = $request->input('Subject');
        $text = $request->input('TextBody');
        $messageId = $request->input('MessageID');
        $attachments = $request->input('Attachments', []);

        // Store or dispatch a job using $messageId as an idempotency key.
        Log::info('inbound mail', [
            'message_id' => $messageId,
            'from' => $from,
            'subject' => $subject,
            'attachment_count' => is_array($attachments) ? count($attachments) : 0,
        ]);

        return response()->noContent(); // 204, a 2xx success
    }
}

config/services.php:

'receivehq' => [
    'user' => env('RECEIVEHQ_BASIC_USER'),
    'password' => env('RECEIVEHQ_BASIC_PASSWORD'),
],

A 2xx acknowledges the delivery. 406 permanently drops it (no retries). Any other code, including 401 on a bad secret, is retried with backoff (1m → 5m → 30m → 1h → 2h), up to the endpoint's maxAttempts setting. Return 2xx as soon as the message is accepted, then queue slower work (saving large RawEmail or attachments).

Each attachment object has Name, Content (base64), ContentType, ContentLength, and ContentID. From is the bare address; use FromFull.Name or FromName for the display name.

Further reading

If you want inbound mail in Laravel without running a mail server, ReceiveHQ will POST Postmark-format JSON to a route like this one.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.