Sendgrid Laravel Driver Laravel Package

Getting Started

This release adds send-time events to the mail pipeline, which is what makes SwiftMailer plugin support practical. The short version: you can now hook into the moment a message is handed to the transport and mutate it or observe it via a standard plugin.

1. composer require <vendor>/<package>:^2.0 — note that 2.0.1 is a patch on top of a major, so read the 2.0 upgrade notes before bumping an existing install.
2. Publish and inspect the config if the package ships one (php artisan vendor:publish), and check whether the mailer is registered as a custom mailer in config/mail.php or swapped in via a service provider.
3. Register a plugin in a service provider's boot() method rather than in a controller or model — plugin registration is global per-transport and should happen once.

Where to look first:

• The event classes dispatched around sending (typically a pre-send and post-send pair). Read their constructors — they usually expose the Swift_Message (or transport-agnostic message) and the mailer instance.
• The service provider that wires the transport, to confirm whether plugins are registered per-mailer or globally.
• The 2.0 changelog/upgrade guide, since the event-firing behaviour is new in this line and 2.0 may have moved or renamed the registration API.

First use case: staging mail redirection. Register a plugin in AppServiceProvider that rewrites To/Cc/Bcc to a single internal address when app()->environment() !== 'production'. This is the classic reason people reach for send-time hooks, and it exercises the whole path end to end.

Implementation Patterns

Environment-conditional plugins. Keep the registration in a dedicated service provider and gate per environment. Plugins that log or redirect should not be active in production unless you have explicitly decided they should.

// AppServiceProvider::boot()
if (! app()->isProduction()) {
    Mail::getSwiftMailer()->registerPlugin(new RedirectAllMailPlugin(config('mail.redirect_to')));
}

Observer pattern for auditing. Attach a listener to the package's send event and write to an email_log table. Because the event fires at send time, you capture the actual final message — after any other plugin has rewritten recipients — which is exactly what you want for compliance records. Prefer this over a MessageSending listener only if you specifically need the Swift layer; otherwise Laravel's native MessageSending/MessageSent events are simpler and survive a future mailer swap.

Middleware-style plugins. Chain small, single-purpose plugins (rewrite recipients → sign with DKIM → throttle → append footer) rather than one god-plugin. Order matters and is determined by registration order, so make that order explicit and commented.

Queued mail. Send-time events fire inside the queue worker, not in the request that queued the job. If a plugin reads request-scoped state (current user, tenant, locale), that state must be serialized into the mailable or plugin constructor. Test this explicitly — it is the most common source of "works locally, wrong in production" bugs with this class of package.

Testing. Use Event::fake() to assert the send event was dispatched without actually hitting the transport, and instantiate plugins directly in unit tests to test the recipient-rewriting logic in isolation. For end-to-end, point the mailer at log or array and assert on the resulting message.

Multi-mailer setups. If your app uses more than one mailer (e.g. smtp for transactional, ses for marketing), check whether plugins registered via the default mailer leak into the others. Register per-transport if the package supports it; otherwise be aware the hook is global.

Gotchas and Tips

• SwiftMailer is gone from Laravel 9+. Laravel replaced SwiftMailer with Symfony Mailer in 9.0. If this package's plugin support depends on Swift_* classes, confirm it either provides a compatibility shim or that you are pinned to Laravel 8.x. This is the single biggest risk with 2.0.1 and should be verified before adoption — check composer.json constraints and run one real send through a test mailer.
• Events fire per message, not per batch. Looping over 500 recipients means 500 dispatches. Budget for listener overhead in bulk sends, and avoid doing I/O (DB writes, HTTP calls) inside the pre-send listener where you can defer it.
• Stateful plugins in long-running workers. Queue workers, Laravel Octane, and Horizon reuse process memory. A plugin that accumulates messages, counters, or per-request config will carry that state into the next job. Reset in the post-send hook or keep plugins immutable.
• Double-send hazard. A pre-send plugin that calls send() again (common when "redirecting" by re-sending) will recurse. Mutate the message in place instead.
• Registration timing. Registering a plugin after the transport has been resolved may silently no-op, especially if the mailer is a singleton resolved early in the container. Do it in boot() and, if you see no effect, dump the mailer's plugin array to confirm.
• Debugging. Log inside the event listener before and after mutation — a plugin that throws will often surface as a generic transport exception with the plugin's stack frame buried. Temporarily registering a single passthrough plugin that dumps message headers is the fastest way to see which stage is failing.
• Config caching. php artisan config:cache will freeze any environment-conditional plugin configuration. Ensure plugin enablement is evaluated at runtime, not baked into a cached config array.
• Extension point to watch. If the package exposes a registerPlugin() on the mailer or a Mail::extend-style hook, prefer that over reaching into internals — 2.x patch releases are most likely to touch the event dispatch internals that plugin consumers depend on.