Search by

zhylon / maillab-client

TobyMaxham

Laravel mail transport and API client for Zhylon Maillab.

v0.0.1 2026-11-17 18:30 UTC

This package is auto-updated.

Last update: 2026-11-17 18:33:50 UTC


README

Zhylon Maillab Client

Latest Version on Packagist Tests PHP Version Laravel Version MIT Licensed Total Downloads

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 maillab mail 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() and Maillab::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.json and 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.