Actuator Mailer Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no Laravel service provider, facade, or config file here. If you're coming from Laravel, treat this as a reference implementation for "health check my mail transport" rather than something you composer require into an app/. It only makes sense inside a Symfony application that already runs symsensor/actuator-bundle.

Minimal setup in that context:

1. composer require symsensor/actuator-mailer-bundle — v1.1.0 is the version you want, since it's the first with Symfony 7 support.
2. Register SymSensor\ActuatorMailerBundle\ActuatorMailerBundle in config/bundles.php (Flex usually handles this).
3. Ensure symsensor/actuator-bundle is installed and its health endpoint is exposed (typically /actuator/health).
4. Configure a standard framework.mailer DSN (MAILER_DSN) so the bundle has a transport to inspect.
5. Hit the actuator health endpoint and confirm a mailer key appears in the checks payload.

Where to look first: the bundle's DependencyInjection/ and any HealthCheck service class in the repo — that's where the actual check logic lives, and it's short. The README on GitHub is thin (0 stars, 0 dependents), so the source is the documentation.

First real use case: wiring the mailer into your deployment's readiness probe so you find out before a user does that your SMTP credentials were rotated or your provider is rate-limiting you.

Implementation Patterns

Aggregated health endpoint (the intended pattern). The bundle registers a check with ActuatorBundle; ActuatorBundle does the aggregation. You don't call the mailer check directly — you consume the combined /actuator/health JSON and alert on the mailer sub-status. This is the pattern to build on: keep mailer health as one signal among many (DB, cache, disk) so your dashboard has a single source of truth.

Kubernetes / ECS probes. Point readiness probes at the actuator endpoint. If you have a separate liveness probe, keep mailer out of it — a flaky SMTP host should not restart your pods. Split the checks (ActuatorBundle supports grouped checks in most versions) so mailer lands in readiness and not liveness.

Smoke tests in CI/CD. After a deploy, curl -f https://app.example.com/actuator/health and assert mailer.status === "up". Cheap, catches misconfigured env vars that unit tests never will.

Multi-transport awareness. If your Symfony app defines several mailers (transactional + marketing via different transports), verify the bundle iterates all of them or only the default. If it only checks the default mailer.mailer service, add your own check for the secondary transports — don't assume coverage.

Monitoring glue. Scrape the actuator endpoint from Prometheus (or your APM agent) and alert on mailer transitioning up → down. Because this is a boolean/gauge, it's trivial to map to a Grafana panel next to your queue and DB health.

Laravel parallel (if you're porting the idea): the equivalent is spatie/laravel-health with a custom Check that resolves MailManager, grabs the default mailer, and attempts a connection (or Mail::fake()-adjacent transport validation). Keep the same shape: one check class, registered in a health service provider, aggregated at /up or a dedicated endpoint.

Gotchas and Tips

• v1.1.0 is a compatibility bump, nothing more. The entire changelog is "Implement Symfony7.0 compatibility." No new features, no new config, no behavior changes. If you were already on v1.0.0 + Symfony 6, upgrading changes nothing observable — but it does unblock Symfony 7 apps, which is the whole reason to care about this release. Re-run bin/console debug:container after upgrading on SF7 to confirm the check still registers; a bundle can be "compatible" per composer.json and still fail to wire a service.
• Still a low-traffic, single-maintainer package. Symfony 7 support landing is a good sign the maintainer is alive, but the release cadence is slow (v1.0.0 shipped December 2023, and this is the first release since) and there are no dependents to shake out bugs before you hit them. Pin the version, read the source (it's small), and be prepared to fork. Symfony 8 will arrive and you may be waiting again.
• Health checks with side effects. The dangerous implementation is one that sends a real email. Look at the check class before enabling it in production — if it dispatches a message, you'll burn through provider quotas and inflate your bill on every probe interval. A safe check opens a TCP/TLS connection or calls a ping, nothing more.
• Timeouts. A TCP connect to a dead SMTP host can hang for 30+ seconds. If the check has no explicit timeout, your /actuator/health request will hang too, and your orchestrator will kill the pod for the wrong reason. Wrap or configure a timeout (usually via the transport's timeout DSN option, e.g. smtp://...?timeout=5).
• Leaking DSNs. Health endpoints are frequently public-facing. Confirm the mailer check returns up/down and an error class, not the DSN, hostname, or credentials. Error messages from TransportException can include the host — sanitize before exposing.
• Don't conflate "configured" with "healthy." Many of these bundles only validate that a transport object exists, which passes even with a bogus password. Test it deliberately: break MAILER_DSN in staging and confirm the check actually goes red.
• Registration quirks. Symfony Flex auto-registration depends on the type: symfony-bundle field in composer.json. Older/low-traffic bundles sometimes ship without it — if the bundle doesn't appear in config/bundles.php, add it manually and run bin/console debug:container --tag=actuator.health_check (tag name may vary) to confirm the check is wired.
• Extension point. If the built-in check doesn't cover your transport, ActuatorBundle lets you register your own HealthCheckInterface implementation with the same tag. That's the escape hatch — you don't have to fork this package to add a check; just implement the interface and tag it.
• Laravel devs: don't force it. There's no adapter and no reason to build one — the Symfony 7 bump is irrelevant to you. Use spatie/laravel-health, a php artisan health check, or a simple scheduler job that pings the SMTP port. The concept (mail transparency as a health signal) transfers; the code doesn't.