Mailer#

Note

Not part of core. Install it separately:

composer require kinetis/mailer

Mail sending via Symfony\Component\Mailer. A single DSN selects the transport — SMTP, or any of Symfony’s own API-based bridges (Sendgrid, Mailgun, Postmark, SES, …).

use Kinetis\Mailer\MailerFactory;
use Symfony\Component\Mime\Email;

$mailer = MailerFactory::fromConfig($config);

$email = new Email()
    ->from('noreply@example.com')
    ->to('user@example.com')
    ->subject('Welcome!')
    ->text('Thanks for signing up.');

$mailer->send($email);

The sender is set on each message with Email::from(). There is no default-sender key; MAILER_DSN and MAILER_TIMEOUT are the only keys the package reads.

Configuring#

MAILER_DSN=smtp://user:pass@smtp.example.com:587

Or, using an API-based transport instead — the scheme selects it:

MAILER_DSN=sendgrid+api://KEY@default
MAILER_TIMEOUT=30

MAILER_TIMEOUT is seconds, default 30. It bounds one API send twice over — as the idle timeout between bytes and as the total duration — and redirects are disabled, so the provider endpoint the DSN names is the only one contacted. Zero or a negative value is rejected when the mailer is built. SMTP ignores all three. Symfony’s SMTP socket instead inherits PHP’s default_socket_timeout for the connection and each blocking stream operation. One SMTP exchange performs several operations, so that setting is an inactivity bound, not a total deadline for the send.

Whichever scheme you use, composer require the matching Symfony bridge package too (symfony/sendgrid-mailer, symfony/mailgun-mailer, symfony/postmark-mailer, symfony/amazon-mailer, …) — kinetis/mailer has no dispatch logic of its own here; Symfony\Component\Mailer\Transport discovers whichever bridge classes are installed.

Important

Only the API-based transports are non-blocking. SMTP opens a raw socket directly (stream_socket_client()), with no Fiber-yield point — sending over SMTP blocks the worker for as long as the send takes. A blocking send also gives the worker no chance to renew the job’s reservation (see Queue), and neither a visibility timeout nor a shutdown grace period can be set high enough to guarantee an SMTP send finished inside it, so at-least-once handling must stay safe when a reservation expires or the process is killed. See Queueing mail below for the practical fix, whichever transport you choose.

Warning

A Symfony HTTP transport exception carries the provider’s own debug data, which can include the raw request headers — and therefore the API key that authenticated the send. Kinetis never reads that data; if your own exception handler does, do not log it.

Amazon SES#

Install symfony/amazon-mailer and use an ses+api:// or ses:// DSN. Credentials in the DSN, or a platform role (EC2 instance profile, ECS task role, or web identity), resolve without blocking: the credential requests go through the same non-blocking HTTP client as the send.

Static keys combined with AWS_ROLE_ARN are the exception. Symfony’s SES transport passes AsyncAws no credential provider, so AsyncAws builds its default chain, and that chain’s ConfigurationProvider has no injected HTTP client. It assumes the role through AsyncAws’s own blocking HTTP client at the first send and again at each credential expiry, and each call blocks the worker until STS answers. Prefer a platform role, or credentials that need no role assumption.

A credential chain that resolved nothing at the first send is remembered until the worker restarts: AsyncAws caches the empty result, so fixing the environment afterwards does not recover a running worker.

Named connections#

$transactional = MailerFactory::fromConfig($config, 'transactional');
MAILER_TRANSACTIONAL_DSN=sendgrid+api://KEY@default
MAILER_TRANSACTIONAL_TIMEOUT=10

Same convention as everywhere else in Kinetis (see Configuration): 'default' reads the plain MAILER_DSN/MAILER_TIMEOUT above, and any other name reads MAILER_{NAME}_DSN/MAILER_{NAME}_TIMEOUT instead.

Queueing mail#

Sending mail from inside a request means the client waits for it — and on SMTP that wait blocks the worker. kinetis/mailer needs to provide nothing for this: a queue job that constructor-injects MailerInterface already gets it, with no extra code in either package.

use Kinetis\Queue\Job;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\Email;

final readonly class SendWelcomeEmailJob implements Job
{
    public function __construct(
        public string $toEmail,
    ) {}

    public function handle(MailerInterface $mailer): void
    {
        $email = new Email()
            ->from('noreply@example.com')
            ->to($this->toEmail)
            ->subject('Welcome!')
            ->text('Thanks for signing up.');

        $mailer->send($email);
    }
}
$queue->push(new SendWelcomeEmailJob($user->email));

With MAILER_DSN set, MailerInterface is already bound — installing the package registers it — so any job’s handle() method can depend on it exactly like a repository or any other service, with nothing in bootstrap.php at all. The transport is built while the package registers, so a malformed DSN or a missing bridge package fails at boot rather than on the first job that sends. An application’s own bootstrap.php runs after that and still replaces the binding.

A slow SMTP send then occupies one queue worker’s Fiber for one job instead of the worker handling an HTTP request.

Testing#

MailerInterface is bound only when MAILER_DSN is set. A test that should send nothing can set 'MAILER_DSN' => 'null://null' in configOverrides() (see Testing), which installs Symfony’s NullTransport. To assert on what the code sent, replace the binding in registerTestDoubles() with a recording mailer:

use Kinetis\Config\Config;
use Kinetis\Container\AppScope;
use Symfony\Component\Mailer\Envelope;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\RawMessage;

final class RecordingMailer implements MailerInterface
{
    /** @var list<RawMessage> */
    public array $sent = [];

    public function send(RawMessage $message, ?Envelope $envelope = null): void
    {
        $this->sent[] = $message;
    }
}

protected function registerTestDoubles(AppScope $app, Config $config): void
{
    $app->instance(MailerInterface::class, new RecordingMailer());
}

Symfony Mailer ships no in-memory transport, so the recorder is the application’s own class.

See also#

  • HTTP Client — the non-blocking HTTP client every API-based transport runs through.

  • Queue — job queues, retries, and named connections in full.

  • Configuration — the named-connection convention used above.