Groundmail with Laravel

Use the Laravel package for a first-class Mail transport (MAIL_MAILER=groundmail), plus a service container binding and Facade on top of the PHP SDK.

1. Install the package

composer require groundmail/laravel

This also installs groundmail/groundmail (HTTP client) and groundmail/symfony-mailer (Symfony Mailer transport used by Laravel’s mailer).

2. Configure env

Publish package config (optional):

php artisan vendor:publish --tag=groundmail-config

Add to .env:

GROUNDMAIL_API_KEY=gm_your_key_here
MAIL_MAILER=groundmail
# optional override:
# GROUNDMAIL_BASE_URL=https://api.groundmail.dev

3. Register the mailer

In config/mail.php, add a mailer that uses the groundmail transport:

'mailers' => [
    // ...
    'groundmail' => [
        'transport' => 'groundmail',
    ],
],

With MAIL_MAILER=groundmail, every Mailable, Notification, and queued mail routes through Groundmail. No send-call rewrites.

4. Send with Mailables (recommended)

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeMail;

Mail::to($user)->send(new WelcomeMail($user));

Tags, idempotency, and schedule

Set Groundmail headers on the Symfony message (for example in a Mailable headers() method or withSymfonyMessage):

use Illuminate\Mail\Mailables\Headers;
use Groundmail\Laravel\Transport\MessageMapper;

public function headers(): Headers
{
    return new Headers(
        text: [
            MessageMapper::HEADER_TAG => 'campaign=welcome',
            MessageMapper::HEADER_IDEMPOTENCY => 'welcome-'.$this->user->id,
            // MessageMapper::HEADER_SCHEDULED_AT => '2030-01-01T00:00:00Z',
        ],
    );
}

X-Groundmail-Tag uses name=value. Repeat the header for multiple tags. Custom non-reserved headers are forwarded to the API headers field.

5. Send via the Facade (API client)

When you need the REST client directly (batch, domains, webhooks):

use Groundmail\Laravel\Facades\Groundmail;

$result = Groundmail::client()->emails->send([
    'from' => 'ops@yourdomain.com',
    'to' => 'user@example.com',
    'subject' => 'Your receipt',
    'html' => '<p>Thanks for your purchase.</p>',
]);

Or resolve the client from the container:

use Groundmail\Client;

public function __construct(private Client $groundmail)
{
}

$this->groundmail->emails->send([...]);

Plain PHP without Laravel

If you don't need the service provider, Mail transport, or Facade, use the PHP SDK directly:

composer require groundmail/groundmail

See PHP SDK.

Source

Package source lives in Groundmail/groundmail-laravel (Packagist requires composer.json at repo root).