zhylon / maillab-client
Laravel mail transport and API client for Zhylon Maillab.
Requires
- php: ^8.4
- illuminate/contracts: ^13.0
- illuminate/http: ^13.0
- illuminate/mail: ^13.0
- illuminate/support: ^13.0
- symfony/mailer: ^7.4 || ^8.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.30
- opis/json-schema: ^2.6
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0
- symfony/yaml: ^7.4 || ^8.0
- zhylon/api-resources: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Send Laravel mails through the HTTP API of Zhylon Maillab instead of SMTP, and read messages, their status and inboxes from your app:
- Mail transport — a
maillabmail driver, used like the Postmark driver that ships with Laravel. Supports cc/bcc, reply-to, HTML and text bodies, attachments, inline images, custom headers, tags and metadata. - API client —
Maillab::messages()andMaillab::inboxes()to list, read and send messages.
The transport uses the client internally, and the client uses Laravel's Http client. No other HTTP client is
installed.
Note
The Maillab API is not final yet. Paths and field names may still change until v1.0.0.
Requirements
- PHP 8.4+
- Laravel 13.x
See the Support Policy for which versions we support and when we drop them.
Installation
composer require zhylon/maillab-client
The service provider and the Maillab facade are registered automatically.
Laravel Boost
The package ships Laravel Boost guidelines, so AI agents in your app send mails and
use the client the way this package expects. Run php artisan boost:install (or boost:update) after installing the
package.
Configuration
Add your token to .env:
MAILLAB_TOKEN=your-maillab-token
That's all for the client. Optional settings and their defaults:
MAILLAB_ENDPOINT=https://maillab.zhylon.net/api/v4 MAILLAB_TIMEOUT=10
To change the config file, publish it:
php artisan vendor:publish --tag=maillab-client-config
// config/maillab.php return [ 'token' => env('MAILLAB_TOKEN'), 'endpoint' => env('MAILLAB_ENDPOINT', 'https://maillab.zhylon.net/api/v4'), 'timeout' => env('MAILLAB_TIMEOUT', 10), ];
The endpoint contains the API version. A trailing slash is ignored, http:// is allowed (for local instances).
Mail driver
Add a mailer to config/mail.php:
'mailers' => [ // ... 'maillab' => [ 'transport' => 'maillab', // optional per mailer, overrides the global values from config/maillab.php: // 'token' => env('MAILLAB_TOKEN'), // 'endpoint' => env('MAILLAB_ENDPOINT'), // 'timeout' => 10, ], ],
and make it the default mailer in .env:
MAIL_MAILER=maillab MAIL_FROM_ADDRESS=hello@example.com MAIL_FROM_NAME="${APP_NAME}"
A mailer that sets its own token, endpoint or timeout gets its own client. Values that are null or not set
fall back to config/maillab.php. This lets you send through two Maillab projects from one app:
'maillab-newsletter' => [ 'transport' => 'maillab', 'token' => env('MAILLAB_NEWSLETTER_TOKEN'), ],
Local development
Maillab can run locally. Point the endpoint to your instance:
MAIL_MAILER=maillab MAILLAB_TOKEN=local-token MAILLAB_ENDPOINT=http://maillab.test/api/v4
Live and test mails
Whether a mail is delivered or only caught is decided by the token on the Maillab side. There is no separate sandbox API: live and test mode use the same endpoints, and the token decides whether a mail is delivered or caught. The package needs no extra flag — use the matching token per environment.
Usage
Sending mails
Use Laravel's mail API as usual:
use App\Mail\OrderShipped; use Illuminate\Support\Facades\Mail; Mail::to($user)->send(new OrderShipped($order)); // with a specific mailer Mail::mailer('maillab')->to($user)->send(new OrderShipped($order));
Tags and metadata from the mailable's envelope are sent to Maillab as tags and metadata:
use Illuminate\Mail\Mailables\Envelope; public function envelope(): Envelope { return new Envelope( subject: 'Your order has shipped', tags: ['shipment'], metadata: ['order_id' => (string) $this->order->id], ); }
Attachments, inline images ($message->embed()) and custom headers (headers()) are sent as well.
Message ID
Maillab returns an id for each sent mail. It is set as message id of the sent message (getMessageId()) and as
X-Maillab-Message-ID header, so you can look the mail up later. The RFC Message-ID of the mail (generated by
Symfony or set by your app) is not changed and is sent to Maillab as Message-ID header:
$sent = Mail::to($user)->send(new OrderShipped($order)); $id = $sent?->getMessageId(); // or from the header, e.g. in a listener for Illuminate\Mail\Events\MessageSent $id = $event->sent->getOriginalMessage()->getHeaders()->get('X-Maillab-Message-ID')?->getBodyAsString();
API client
Use the facade or inject Zhylon\MaillabClient\Client\MaillabClient.
Maillab answers in the zhylon/api-resources format
({ "data": { "id", "type", "attributes", "links", "meta" } }, lists with pagination links/meta, errors as
{ "errors": [ … ] }). The client unwraps it into readonly DTOs, you never parse the JSON yourself.
Messages
use Zhylon\MaillabClient\Facades\Maillab; use Zhylon\MaillabClient\Data\MessageStatus; // all queued messages $messages = Maillab::messages()->list(status: 'queued'); // filter by status and inbox, the enum works as well $messages = Maillab::messages()->list(status: MessageStatus::Bounced, inbox: 'inbox-id'); foreach ($messages as $message) { $message->id; // string, `data.id` $message->status; // ?string, e.g. "queued", "sent", "bounced" $message->subject; // ?string $message->createdAt; // ?string, ISO-8601 $message->statusEnum(); // ?MessageStatus, null for states unknown to this package $message->get('to'); // any attribute of the resource $message->selfLink(); // ?string, `links.self.href` $message->meta; // array, the resource meta } // a single message, e.g. by the id from the X-Maillab-Message-ID header $message = Maillab::messages()->get($id); if ($message->is(MessageStatus::Bounced)) { // ... }
You can also send a message directly. The payload keys are defined in Zhylon\MaillabClient\Client\Api:
$message = Maillab::messages()->send([ 'from' => 'hello@example.com', 'to' => ['jane@example.com'], 'subject' => 'Hello', 'text_body' => 'Hello Jane', ]);
Pagination
list() and inboxes()->messages() return a Zhylon\MaillabClient\Data\Page. It is iterable and countable, and
works for length-aware and cursor pagination:
$page = Maillab::messages()->list(status: 'bounced'); $page->items; // list<Message> $page->total(); // ?int, length-aware only $page->currentPage(); // ?int, length-aware only $page->lastPage(); // ?int, length-aware only $page->perPage(); // ?int $page->nextCursor(); // ?string, cursor only $page->link('next'); // ?string $page->meta; // the top-level meta, incl. anything else the server adds // walk through all pages while ($page !== null) { foreach ($page as $message) { // ... } $page = $page->nextPage(); // null on the last page }
nextPage() repeats the request with the same filters and query, plus page (length-aware) or cursor (cursor
pagination). It never follows the next URL of the response, so the token is only sent to your configured endpoint.
Further query parameters can be passed with list(query: ['per_page' => 50]).
Inboxes
List the inboxes and the messages of an inbox:
foreach (Maillab::inboxes()->list() as $inbox) { $inbox->id; $inbox->name; $messages = Maillab::inboxes()->messages($inbox->id); }
Dependency injection
use Zhylon\MaillabClient\Data\Page; use Zhylon\MaillabClient\Data\Message; use Zhylon\MaillabClient\Client\MaillabClient; final class BounceChecker { public function __construct(private MaillabClient $maillab) {} /** * @return Page<Message> */ public function bounced(): Page { return $this->maillab->messages()->list(status: 'bounced'); } }
Errors
The client throws:
| Exception | When |
|---|---|
Zhylon\MaillabClient\Exceptions\AuthenticationException |
HTTP 401/403, or no token configured |
Zhylon\MaillabClient\Exceptions\NotFoundException |
HTTP 404, e.g. an unknown message id |
Zhylon\MaillabClient\Exceptions\ValidationException |
HTTP 422, errors() returns the field errors |
Zhylon\MaillabClient\Exceptions\MaillabException |
any other error, incl. connection errors (base class of all above) |
status(), body() (raw response), response(), apiErrors() (the entries of errors[] as
Zhylon\MaillabClient\Data\ApiError with status, code, title, detail and pointer) and apiMessage()
(the detail of the first error) give you the details.
ValidationException::errors() groups the messages by the request field their source.pointer points to, in dot
notation like Laravel's validation errors:
use Zhylon\MaillabClient\Exceptions\ValidationException; try { Maillab::messages()->send(['from' => 'hello@example.com', 'to' => []]); } catch (ValidationException $e) { $e->errors(); // ['to' => ['The to field is required.']] }
When sending mails, the transport throws a Symfony\Component\Mailer\Exception\TransportException, just like the
other Laravel mail drivers. Its message contains the raw API response, getPrevious() returns the exception above.
API specification
docs/maillab-api.openapi.yaml (OpenAPI 3.1) describes exactly what this package
sends to and expects from Maillab, docs/maillab-api.md gives an overview. The test suite
validates every request and faked response against it.
Security
- Keep the token secret. Store it in
.env, never in the config file or the repository. It is passed to the client as#[SensitiveParameter], so it does not show up in stack traces. - Exception messages contain the raw API response. They don't contain the token, but they may contain recipient addresses. Keep that in mind when you forward exceptions to an error tracker.
- Use
https://outside local development.http://is allowed so you can test against a local instance. - Laravel Octane: supported. The client keeps no request state, only the values from the config.
Testing
composer test # Pest (incl. architecture tests) composer test-coverage # Pest with coverage, requires 100 % composer analyse # PHPStan (Larastan, level 8) composer lint # Pint --test + PHPStan composer format # Pint
The tests use Http::fake() and never send a real request.
In your own app, fake the HTTP calls the same way:
use Illuminate\Support\Facades\Http; Http::fake([ '*/messages' => Http::response([ 'data' => [ 'id' => 'msg_123', 'type' => 'message', 'attributes' => ['status' => 'queued'], ], ]), ]);
Support Policy
We only support PHP and Laravel versions that are in active support upstream. Versions that only receive security fixes are not supported.
- When a PHP or Laravel version leaves active support, we drop it from
composer.jsonand the CI matrix in the next minor release and mention it in the changelog. - New PHP and Laravel versions are added as soon as they are stable and the tests pass.
Currently supported:
| Package | PHP | Laravel |
|---|---|---|
| 1.x | 8.4, 8.5 | 13.x |
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities — in short: use GitHub's private vulnerability reporting or mail security@zhylon.net, not the issue tracker.
Credits
License
The MIT License (MIT). See LICENSE for more information.