Migrate from Mailgun to Groundmail in Laravel

Swap the package

composer remove symfony/mailgun-mailer
composer require groundmail/laravel

Before: Mailgun (Laravel)

# .env
MAIL_MAILER=mailgun
MAILGUN_DOMAIN=mg.acme.com
MAILGUN_SECRET=…
MAILGUN_ENDPOINT=api.mailgun.net
MAIL_FROM_ADDRESS=no-reply@acme.com

// config/services.php
'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
    'scheme' => 'https',
],

After: Groundmail (Laravel)

# .env
MAIL_MAILER=groundmail
GROUNDMAIL_API_KEY=gm_…
MAIL_FROM_ADDRESS=no-reply@acme.com

// config/mail.php, under 'mailers'
'groundmail' => [
    'transport' => 'groundmail',
],

// Your Mailables, notifications and queued mail don't change:
Mail::to($user)->send(new ResetPasswordMail($user));

Verify a Groundmail webhook (Laravel controller)

use Illuminate\Http\Request;

class GroundmailWebhookController
{
    public function __invoke(Request $request)
    {
        $ok = $this->verifyGroundmailSignature(
            $request->getContent(),
            (string) $request->header('Groundmail-Signature'),
            config('services.groundmail.webhook_secret'), // env('GROUNDMAIL_WEBHOOK_SECRET')
        );
        abort_unless($ok, 401);

        $event = $request->json()->all(); // ['type' => 'email.delivered', 'data' => [...]]

        return response()->noContent();
    }

    private function verifyGroundmailSignature(string $rawBody, string $header, string $secret): bool
    {
        $parts = [];
        foreach (explode(',', $header) as $part) {
            [$key, $value] = array_pad(explode('=', $part, 2), 2, '');
            $parts[$key] = $value;
        }
        $t = $parts['t'] ?? '';
        $v1 = $parts['v1'] ?? '';
        if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > 300) {
            return false;
        }

        return hash_equals(hash_hmac('sha256', $t . '.' . $rawBody, $secret), $v1);
    }
}

Import from Mailgun with the CLI

npm install -g groundmail-cli
groundmail login
export MAILGUN_API_KEY=…
groundmail migrate mailgun --dry-run   # preview, nothing written
groundmail migrate mailgun             # import