Winter CMS resources and help articles

Simple and to the point. Optimized by the community.

Override the mail content of the users mail

1
by AIC BV, last modified on July 17th, 2026

Written with AI for additional context

Rebrand vendor plugin mails without touching the plugin

Category: Mail / Events Works with: Winter CMS 1.1+ (any plugin that sends view-based mails, e.g. Winter.User)

The problem

Plugins like Winter.User send transactional mails (winter.user::mail.restore, winter.user::mail.activate) using their own bundled templates. They look generic, and you usually want them in your own branding, layout and tone of voice.

The usual options all have downsides:

  • Editing the vendor views — gone on the next composer update.
  • Overriding templates in the backend (Settings → Mail templates) — works, but the content now lives in the database instead of your git repository. No code review, no deploys, no history, and every environment (local, staging, production) has to be kept in sync by hand.
  • Forking the plugin — a maintenance burden for what is essentially a cosmetic change.

What you actually want: the vendor plugin keeps triggering its mails exactly as it does today, but the content comes from your own git-tracked templates in your own plugin.

The trick

Winter's own mail system renders view-based mails through the global mailer.beforeAddContent event — the System module listens to it to resolve and render the template, and Winter.Translate listens to it for localization. Because event listeners run in priority order and returning false halts propagation, you can register your own listener at a higher priority, swap the vendor view code for your own, add the content yourself, and return false so the default handlers never run — but only for the mails you map. Everything else falls through untouched.

In your plugin's boot() method:

Event::listen('mailer.beforeAddContent', function ($mailer, $message, $view, $data, $raw, $plain) {
    static $map = [
        'winter.user::mail.restore'  => 'acme.site::mail.restore',
        'winter.user::mail.activate' => 'acme.site::mail.activate',
    ];

    // Only the two view-based vendor mails we rebrand; leave raw mails and
    // everything else to the default handlers.
    if ($raw !== null || !is_string($view) || !isset($map[$view])) {
        return;
    }

    $code = $map[$view];

    MailManager::instance()->addContentToMailer($message, $code, $data);

    return false; // branded content added — skip the vendor template
}, 100);

Your own templates (acme.site::mail.restore, …) are registered the normal way via registerMailTemplates() in your Plugin.php and live as .htm files in your plugin — versioned, reviewable, deployable.

How it works

  1. Winter.User calls Mail::send('winter.user::mail.restore', …) as usual — nothing changes on the vendor side.
  2. The Mailer fires mailer.beforeAddContent before resolving the template content.
  3. Your listener runs first (priority 100 beats the default priority 0 of the System/Translate listeners).
  4. For unmapped views or raw mails it returns nothing, so propagation continues and the framework behaves exactly as stock.
  5. For a mapped view it renders your template into the message via MailManager::addContentToMailer() and returns false, halting the event — so the vendor template is never rendered.

Bonus: keep localization

If you run a multilingual site with Winter.Translate, you also bypass its localization handler — so resolve the locale-suffixed variant yourself before adding content:

$locale = !empty($data['_current_locale']) ? $data['_current_locale'] : App::getLocale();

// Prefer a locale-suffixed variant (restore-fr, activate-en, …), else the base.
$localized = EventRegistry::instance()->getLocalizedView($mailer->getViewFactory(), $code, $locale);

MailManager::instance()->addContentToMailer($message, $localized ?: $code, $data);

(EventRegistry here is Winter\Translate\Classes\EventRegistry — the same class Winter.Translate uses internally, so your naming convention for localized templates stays identical to the rest of your site.)

When to use this

  • You want vendor transactional mails in your own branding and you want those templates in version control rather than in the database.
  • You're rebranding a subset of mails and want everything else to keep stock behavior.
  • You can't or don't want to fork/patch the vendor plugin.

When not to use this

  • If database-managed templates are fine for your workflow, simply overriding the template content in Settings → Mail templates is less code.
  • If you need to change when or to whom a mail is sent (not just its content), look at the plugin's own events instead — this hook only controls content.

Gotchas

  • Guard against $raw mails and non-string views (Winter also supports ['html' => …, 'text' => …] view arrays) — the early return in the snippet handles this.
  • Keep the listener registration in boot(), not register(), so all mail infrastructure is available.
  • If another plugin also registers a high-priority listener on this event, priorities decide who wins — pick a number consciously

Discussion

0 comments

We use cookies to measure the performance of this website. Do you want to accept these cookies?