Mandrill Bundle Laravel Package

Getting Started

First, a compatibility check — this is a Symfony bundle, not a Laravel package. The repository is slot/MandrillBundle republished under hipaway-travel, and it depends on Symfony's bundle/kernel infrastructure. Laravel does not have AppKernel, config/bundles.php, or bundle service definitions, so you cannot composer require this into a Laravel app and expect it to auto-wire. For a Laravel codebase, treat this package as a reference implementation rather than a dependency.

If you are maintaining a legacy Symfony app that already uses it:

1. Install and inspect the actual package name/namespace. The fork metadata may not match the original Slot\MandrillBundle namespace or slot_mandrill config key. Run composer show hipaway-travel/mandrill-bundle and read composer.json + Resources/config/services.xml before writing any code. Confirm the Symfony version constraint; a 2021-era bundle will typically target Symfony 3/4/5, not current Symfony.
2. Register the bundle in config/bundles.php (Symfony Flex) or AppKernel::registerBundles() (legacy).
3. Configure the API key under the bundle's config key (historically slot_mandrill: api_key: "%mandrill_api_key%"). Pull it from env, never commit it.
4. Find the service ID first. The bundle exposes a Mandrill service (historically mandrill) plus a Message object. Check services.xml for the exact ID before injecting. That service is your first integration point.
5. First use case: transactional email. Build a Message, set from/to/subject/html/text, and hand it to the service's send() method. Do this in a console command or test controller before wiring it into application flows.

For a new Laravel project, skip the bundle and use the official mandrill/mandrill PHP SDK, Mandrill's SMTP credentials via Laravel's Mail facade, or a small custom Laravel mail transport. The bundle buys you nothing in Laravel except an incompatible dependency graph.

Implementation Patterns

Legacy Symfony usage

• Inject the service, don't instantiate the client. Constructor-inject the bundle's Mandrill service into your own mailer/notifier service. This keeps your code testable and lets you swap the implementation later.
• Wrap the bundle in an application-level notifier. Do not scatter $mandrill->send(...) calls across controllers. Create a TransactionalMailer or Notifier service that accepts your domain objects, builds the Message, sets merge vars/tags, and calls Mandrill once. This is the single most important pattern because it isolates the dead-end dependency.
• Use Mandrill templates, not inline HTML, for anything user-facing. Set the template name and global/recipient merge vars through the Message object. Keep template slugs in config so marketing can change copy without deploys.
• Send asynchronously. Mandrill API calls are network calls. In Symfony, dispatch a message to a queue/worker rather than sending inline in a request. In Laravel terms: a queued Job wrapping the API call, with retries and a dead-letter path.
• Catch and classify failures. The SDK throws on transport/API errors. Distinguish invalid recipients (reject_reason), auth failures, and rate limiting. Do not let a bounced transactional email take down a checkout flow — log, alert, and continue where appropriate.
• Handle webhooks outside the bundle. Mandrill's delivery/bounce/open webhooks are plain HTTP POSTs. Implement a controller/route that verifies the Mandrill signature, persists events, and returns 200 quickly. The bundle does not solve this for you.

Laravel-oriented patterns

• Custom mail transport if you must stay on Mail::send(): implement a Laravel transport that calls the Mandrill API, register it via Mail::extend() or a service provider, and configure mail.mailers.mandrill. This preserves Laravel's Mailable API while using Mandrill's API features.
• Or use SMTP. Mandrill exposes SMTP credentials; configuring MAIL_MAILER=smtp with smtp.mandrillapp.com is the lowest-effort path and works with Laravel Mail, notifications, and queues out of the box. You lose API-only features (templates with merge vars, tags, scheduling) until you add the API for those specific cases.
• Facade/adapter boundary. Define a Mailer interface in your app (sendWelcome(User $user), sendReceipt(Order $order)) and implement it with Mandrill. This is the difference between a one-week integration and a one-week migration later.

Gotchas and Tips

• This is effectively unmaintained. Last release January 2021, 64 stars, zero dependents. No Laravel support, no PHP 8.2+ guarantees, and likely stale Symfony constraints. Budget for a replacement path from day one.
• Do not assume the fork's namespace. Forks frequently rename Slot\MandrillBundle to something like HipawayTravel\MandrillBundle while leaving docs stale. Read composer.json autoload and services.xml; never copy-paste the original README's class names.
• Config key mismatch is the classic failure. A wrong slot_mandrill/fork-specific key silently leaves the API key empty until the first send throws. Validate the key at boot (a small compiler pass or config check) rather than at send time.
• Mandrill API keys are account-wide. Use subaccounts or separate keys per environment, and never reuse production keys in staging — test sends affect reputation and webhooks.
• Rate limits and reject_reason. Mandrill returns per-recipient rejections inside a successful HTTP response. A 200 does not mean delivered. Inspect the response array and log rejected recipients.
• Webhook authenticity. Verify the X-Mandrill-Signature header using your webhook key and the exact raw request body. Framework body parsing that mutates the payload will break signature verification.
• Testing. Mock the service interface, not the Mandrill HTTP client, so tests don't depend on the bundle's internals. For integration tests, use a fake transport and assert on the built Message (from, to, template, merge vars).
• Extension points are limited. The bundle is thin; if you need behavior changes, decorate the service or replace its definition in your app's service config rather than forking. Forking an abandoned bundle creates a permanent maintenance liability.
• Migration plan. Isolate all calls behind one adapter. Then you can move to symfony/mailer + a Mandrill bridge, the official SDK, or another provider (Postmark/SES) without touching business logic. Given the package's score and staleness, plan the exit before you plan the integration.