README

Thin Laravel integration for the official Mailosaur PHP SDK. This package registers a singleton MailosaurClient configured from your app’s config/ENV, and exposes it via a simple wrapper class and a facade so you can call the Mailosaur API anywhere in your app.

The PHP usage patterns below are based on the Mailosaur docs: Mailosaur PHP – Find an email.

Requirements

• PHP ^8.3
• Laravel ^10 || ^11 || ^12

Installation

composer require chrisreedio/laravel-mailosaur

Publish the config file:

php artisan vendor:publish --tag="laravel-mailosaur-config"

Set your environment variables (recommended):

MAILOSAUR_API_KEY=your_api_key
MAILOSAUR_SERVER_ID=your_server_id
# Optional (defaults to "${MAILOSAUR_SERVER_ID}.mailosaur.net")
MAILOSAUR_EMAIL_DOMAIN=your-domain.mailosaur.net

The published config config/mailosaur.php reads from these ENV keys:

return [
    'api_key' => env('MAILOSAUR_API_KEY'),
    'server_id' => env('MAILOSAUR_SERVER_ID'),
    'domain' => env('MAILOSAUR_EMAIL_DOMAIN', env('MAILOSAUR_SERVER_ID').'.mailosaur.net'),
];

How it works

• The service provider creates a singleton instance of MailosaurClient using config('mailosaur.api_key').
• It wraps the client in ChrisReedIO\Mailosaur\Mailosaur, which also exposes your serverId and domain from config.
• A facade alias Mailosaur is registered for convenience.

Usage

You can access the same singleton three ways. Choose what fits your style:

1. Facade (convenient):

use ChrisReedIO\Mailosaur\Facades\Mailosaur; // or use the alias: use Mailosaur;

$client = Mailosaur::client();
$messages = Mailosaur::messages();
$serverId = Mailosaur::serverId();
$domain = Mailosaur::domain();

1. Dependency Injection:

use ChrisReedIO\Mailosaur\Mailosaur;

public function __construct(private Mailosaur $mailosaur) {}

public function __invoke()
{
    $client = $this->mailosaur->client();
}

1. Container helper:

$mailosaur = app(\ChrisReedIO\Mailosaur\Mailosaur::class);

Convenience methods (no server ID needed)

These helpers use your configured MAILOSAUR_SERVER_ID automatically:

// Find a single message matching criteria
Mailosaur::getMessage(SearchCriteria $criteria, int $timeout = 10000, ?DateTime $receivedAfter = null, ?string $dir = null): \Mailosaur\Models\Message

// Search for messages
Mailosaur::searchMessages(SearchCriteria $criteria, int $page = 0, int $itemsPerPage = 50, ?int $timeout = null, ?DateTime $receivedAfter = null, bool $errorOnTimeout = true, ?string $dir = null): \Mailosaur\Models\MessageListResult

// List all messages
Mailosaur::allMessages(int $page = 0, int $itemsPerPage = 50, ?DateTime $receivedAfter = null, ?string $dir = null): \Mailosaur\Models\MessageListResult

// Delete all messages on the configured server
Mailosaur::deleteAllMessages(): void

// Create a message to a verified email address
Mailosaur::createMessage(\Mailosaur\Models\MessageCreateOptions $options): \Mailosaur\Models\Message

// Generate a random email address for the configured server
Mailosaur::generateEmailAddress(): string

Examples using convenience methods

use ChrisReedIO\Mailosaur\Facades\Mailosaur;
use Mailosaur\Models\SearchCriteria;

// Get a single matching message
$criteria = new SearchCriteria();
$criteria->sentTo = 'anything@' . Mailosaur::domain();
$message = Mailosaur::getMessage($criteria);

// Search with timeout and receivedAfter
$testStart = new \DateTime();
$result = Mailosaur::searchMessages($criteria, itemsPerPage: 10, timeout: 10_000, receivedAfter: $testStart);

// List and delete all
$list = Mailosaur::allMessages(itemsPerPage: 10);
Mailosaur::deleteAllMessages();

// Generate a random address on the configured server
$address = Mailosaur::generateEmailAddress();

Common examples

Find an email (wait for the next matching message)

use ChrisReedIO\Mailosaur\Facades\Mailosaur;
use Mailosaur\Models\SearchCriteria;

$criteria = new SearchCriteria();
$criteria->sentTo = 'anything@' . Mailosaur::domain();

// Using raw SDK (requires serverId)
$message = Mailosaur::messages()->get(Mailosaur::serverId(), $criteria);
// Or with convenience method (no serverId needed)
// $message = Mailosaur::getMessage($criteria);

// e.g. assert subject
// expect($message->subject)->toBe('My example email');

Wait with custom timeout and only include messages received after test start

use ChrisReedIO\Mailosaur\Facades\Mailosaur;
use Mailosaur\Models\SearchCriteria;

$testStart = new \DateTime();

$criteria = new SearchCriteria();
$criteria->sentTo = 'anything@' . Mailosaur::domain();

// timeout in ms, receivedAfter as DateTime
$message = Mailosaur::getMessage(
    criteria: $criteria,
    timeout: 10_000,
    receivedAfter: $testStart
);

Generate a random email address for the server

use ChrisReedIO\Mailosaur\Facades\Mailosaur;

$emailAddress = Mailosaur::generateEmailAddress();
// e.g. "bgwqj@SERVER_ID.mailosaur.net"

Delete all messages on the server

use ChrisReedIO\Mailosaur\Facades\Mailosaur;

Mailosaur::deleteAllMessages();

For many more operations (attachments, forwarding, replying, etc.), see the official Mailosaur PHP docs: Mailosaur PHP – Find an email.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Chris Reed
• All Contributors

License

The MIT License (MIT). Please see License File for more information.