qubus / mail

v6.0.0 2026-09-12 22:10 UTC

Requires

• php: >=8.4
• qubus/config: ^4
• qubus/exception: ^4
• symfony/mailer: ^7.3 || ^8.0

Requires (Dev)

• qubus/qubus-coding-standard: ^2

Suggests

• symfony/http-client: Required by HTTP/API-based provider transports.
• symfony/postmark-mailer: Example provider bridge; install the bridge for the provider you use.

MIT

• Joshua Parker

• mail
• mailer
• smtp
• sendmail
• symfony-mailer

Published on Packagist.org on 2026-09-12 22:11 UTC

README

A fluent, immutable wrapper around Symfony Mailer.

Requirements

• PHP 8.4+

Installation

composer require qubus/mail

Usage

use Qubus\Config\Collection;
use Qubus\Mail\QubusMailer;

$config = Collection::factory(['path' => __DIR__ . '/config']);
$mailer = new QubusMailer($config);

$mailer
    ->withFrom('[e-mail]', 'Framework')
    ->withTo(['[e-mail]', '[e-mail]' => 'A Person'])
    ->withSubject('Email Message')
    ->withBody('This is a <strong>simple</strong> email message.')
    ->withHtml(true)
    ->send();

Templates use {{KEY}} placeholders. A sibling .txt file is automatically used as the plain-text alternative when present.

$mailer
    ->withSmtp()
    ->withFrom('[e-mail]')
    ->withTo('[e-mail]')
    ->withSubject('Email Message')
    ->withBody(
        ['MESSAGE' => 'This is a <strong>simple</strong> email message.'],
        ['template_name' => resource_path('email.html')],
    )
    ->withAttachment(storage_path('file.pdf'))
    ->send();

When mailer.debug is true, send() writes the RFC 822 message to mailer.emlfile instead of connecting to a transport.

Transports

The wrapper accepts Symfony Mailer DSNs without translating them. Configure a default DSN and optional named transports in config/mailer.php:

return [
    'dsn' => $_ENV['MAILER_DSN'] ?? 'smtp://localhost',
    'transports' => [
        'transactional' => $_ENV['MAILER_TRANSACTIONAL_DSN'],
        'marketing' => $_ENV['MAILER_MARKETING_DSN'],
    ],
];

Use the default, select a named transport, or provide a DSN for one message:

$mailer->withTransport()->send();                // mailer.dsn
$mailer->withTransport('transactional')->send(); // mailer.transports.transactional
$mailer->withDsn('postmark+api://KEY@default')->send();

Provider DSNs work after installing the corresponding Symfony bridge, for example composer require symfony/postmark-mailer. API transports may also require symfony/http-client. Symfony-native failover(...) and roundrobin(...) DSNs can be used directly. Credentials containing reserved URI characters must be URL-encoded.

More Info

• Documentation