Support associating Eloquent models with Notification classes (not just Mailables)

[ChrisReid]

Summary

Support associating Eloquent models when sending notifications (not just Mailables), using a first-class API.

---

Problem

The package has a great AssociatesModels trait for Mailables, but in notification flows (Notification::toMail() returning MailMessage) the DX is unclear and currently requires workarounds.

In practice, teams often send core business emails via notifications and want those mails linked to domain models (e.g. Sale, Claim, Estimate) so they can view delivery/open/click status in UI tooling.

---

Current Behavior

• Model association works well with Mailable + AssociatesModels.
• Notification path (MailMessage) has no obvious package-native equivalent.

---

Proposal

Add a package-native notification message class, e.g.:

Backstage\Mails\Messages\AssociatedMailMessage
    extends Illuminate\Notifications\Messages\MailMessage

New fluent method:

associateModels(Model|array $models): static

Internally, this should reuse the existing association header strategy (X-Mails-Associated-Models) so StoreMailRelations continues to work unchanged.

---

Example Usage

use Backstage\Mails\Messages\AssociatedMailMessage;

public function toMail(object $notifiable): AssociatedMailMessage
{
    return (new AssociatedMailMessage)
        ->subject('Your Vehicle Care Plan')
        ->line('Thanks for your purchase...')
        ->associateModels([
            $this->sale,
            $this->customer,
        ]);
}

---

Why This Approach

• Clean DX for notification-first apps
• No hacks or event registries required
• Backward compatible
• Minimal surface area and easy to document
• Preserves existing package architecture

---

Suggested Tests

Add an integration test covering the full notification flow:

1. Send a notification that returns AssociatedMailMessage and calls associateModels([...])
2. Assert a mails record is created
3. Assert a mailables pivot record is created linking the model(s) to the mail

This validates:

notification → header → relation storage

end-to-end.

---

Extra

Happy to open a PR with:

• AssociatedMailMessage
• Tests
• README docs update (notification example under “Relate emails to Eloquent models”)

[markvaneijk]

Great idea, I implemented it in v3.0.14 (#88)