[12.x] Add mergeMetadata method to the Mailable class #56376

kevinb1989 · 2025-07-22T14:52:24Z

Email providers such as Sendgrid and Mailjet allow us to design email templates with placeholders in their dashboards. So we don't have to design the blade files for our emails. We only need to send an API request containing the template ID and data to be put on the placeholders.

I don't think Laravel has officially supported sending emails this way with mailables. The best approach that we can think of is to save the request payload to the metadata of a mailable. Then in a transport, we can extract the payload from the metadata (at this point headers) and send an API request.

It would be a bit nicer to use that mergeMetadata method instead of calling the metadata method multiple times.

use App\Models\Order;

class Receipt extends Mailable
{
    public string $templateId = 'external_template_id';

    function __construct(public Order $order)
    {}

    public function build()
    {
        $this->view('dummy_blade_file_to_bypass_the_mailer')
            ->mergeMetadata([
                'template_id' => $this->templateId,
                'customer_name' => $this->order->customer->name;
                'order_id' => $this->order->id,
                'total' => $this->order->total,
            ]);
    }
}

Then in our custom transport:

use Symfony\Component\Mailer\Transport\AbstractTransport;

class MailjetTransport extends AbstractTransport
{
    function __construct(protected MailjetClient $client)
    {}

    protected function doSend(SentMessage $message): void
    {
        $this
            ->client
            ->send($this->payload($message));
    }

    protected function payload(SentMessage $message): array
    {
        return collect($message->getHeaders())
            ->filter(fn ($header) => Str::startsWith($header, 'X-Metadata'))
            ->map(fn ($header) => Str::chopStart($header, 'X-Metadata'))
            ->toArray();
    }
}

This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [laravel/framework](https://laravel.com) ([source](https://github.com/laravel/framework)) | `12.20.0` -> `12.21.0` | [![age](https://developer.mend.io/api/mc/badges/age/packagist/laravel%2fframework/12.21.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://developer.mend.io/api/mc/badges/adoption/packagist/laravel%2fframework/12.21.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://developer.mend.io/api/mc/badges/compatibility/packagist/laravel%2fframework/12.20.0/12.21.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://developer.mend.io/api/mc/badges/confidence/packagist/laravel%2fframework/12.20.0/12.21.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>laravel/framework (laravel/framework)</summary> ### [`v12.21.0`](https://github.com/laravel/framework/blob/HEAD/CHANGELOG.md#v12210---2025-07-22) [Compare Source](laravel/framework@v12.20.0...v12.21.0) - fix(vite): [#55793](laravel/framework#55793) add explicit as-script to link tag for script modul… by [@midsonlajeanty](https://github.com/midsonlajeanty) in laravel/framework#55794 - \[12.x] Allow globally disabling Factory parent relationships via `Factory::dontExpandRelationshipsByDefault()` by [@cosmastech](https://github.com/cosmastech) in laravel/framework#56154 - \[12.x] Adds checking if a value is between two columns by [@DarkGhostHunter](https://github.com/DarkGhostHunter) in laravel/framework#56119 - \[12.x] Ensure database connection is always restored by [@xurshudyan](https://github.com/xurshudyan) in laravel/framework#56258 - \[12.x] Fix handling of `Htmlable` objects in `Js::convertDataToJavaScriptExpression()` by [@jj15asmr](https://github.com/jj15asmr) in laravel/framework#56253 - Reduce meaningless intermediate variables. by [@LjjGit](https://github.com/LjjGit) in laravel/framework#56265 - \[12.x] Improve typehints for `AbstractCursorPaginator@through()` by [@cosmastech](https://github.com/cosmastech) in laravel/framework#56267 - Use `Date` facade instead of `time()` for `password_confirmed_at` check by [@dylanbr](https://github.com/dylanbr) in laravel/framework#56270 - \[12.x] fix: Collection::transform() and Paginator::through() return types by [@calebdw](https://github.com/calebdw) in laravel/framework#56273 - \[12.x] Merge 11.x into 12.x by [@u01jmg3](https://github.com/u01jmg3) in laravel/framework#56289 - \[12.x] Reduce meaningless intermediate variables by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in laravel/framework#56288 - \[12.x] Refactor build Method to Use Null Coalescing Assignment for Default C… by [@Ashot1995](https://github.com/Ashot1995) in laravel/framework#56283 - \[12.x] minor code formatting improvements by [@browner12](https://github.com/browner12) in laravel/framework#56296 - \[12.x] Use more specific route binding exception message for child routes by [@jessekoerhuis](https://github.com/jessekoerhuis) in laravel/framework#56298 - \[12.x] Fix Possible Undefined Variables by [@calfc](https://github.com/calfc) in laravel/framework#56292 - \[12.x] Fix: Ensure scheduler `dailyAt()` method parses minutes and ignores seconds when seconds are provided by [@amirhshokri](https://github.com/amirhshokri) in laravel/framework#56308 - \[12.x] Allows for strict boolean validation by [@peterfox](https://github.com/peterfox) in laravel/framework#56313 - Improve `SeedCommand` console output by [@Jehong-Ahn](https://github.com/Jehong-Ahn) in laravel/framework#56310 - \[12.x] Add unified enum support across framework docs by [@amirhshokri](https://github.com/amirhshokri) in laravel/framework#56271 - \[12.x] Allows for strict numeric validation by [@peterfox](https://github.com/peterfox) in laravel/framework#56328 - \[12.x] Update PHPDoc annotations in `Validation` by [@mrvipchien](https://github.com/mrvipchien) in laravel/framework#56321 - \[12.x] Add operator class support for PostgreSQL GiST spatial indexes by [@joteejotee](https://github.com/joteejotee) in laravel/framework#56324 - Fix multipart array value parsing in HTTP client ([#55732](laravel/framework#55732)) by [@joteejotee](https://github.com/joteejotee) in laravel/framework#56302 - Fixes bug with ShouldBeUniqueUntilProcessing locks getting stuck due to Middleware by [@TWithers](https://github.com/TWithers) in laravel/framework#56318 - \[12.x] add prompts based expectations to PendingCommand by [@BinaryKitten](https://github.com/BinaryKitten) in laravel/framework#56260 - \[12.x] Add Singleton and Scoped attributes to Container by [@riasvdv](https://github.com/riasvdv) in laravel/framework#56334 - Fix unsetting model castable attribute when cast to object ([#56335](laravel/framework#56335)) by [@guram-vashakidze](https://github.com/guram-vashakidze) in laravel/framework#56343 - \[12.x] Fix/memory improvement by [@CharrafiMed](https://github.com/CharrafiMed) in laravel/framework#56345 - \[12.x] Add hasMailer method to the mailable class by [@kevinb1989](https://github.com/kevinb1989) in laravel/framework#56340 - \[12.x] Consistent use of `mb_split()` to split strings into words by [@shaedrich](https://github.com/shaedrich) in laravel/framework#56338 - \[12.x] Add toStringable to Uri by [@Kyrch](https://github.com/Kyrch) in laravel/framework#56359 - \[12.x] Fix PHPStan Integrations by [@crynobone](https://github.com/crynobone) in laravel/framework#56369 - Add 'isEmpty' and 'isNotEmpty' to Fluent by [@cworreschk](https://github.com/cworreschk) in laravel/framework#56370 - \[12.x] Add mergeMetadata method to the Mailable class by [@kevinb1989](https://github.com/kevinb1989) in laravel/framework#56376 - Add 'dontReportUsing' to filter exceptions to be reported by [@pelmered](https://github.com/pelmered) in laravel/framework#56361 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://code.itinerare.net/itinerare/Mundialis/pulls/282 Co-authored-by: Amadeus[bot] <renovate@itinerare.net> Co-committed-by: Amadeus[bot] <renovate@itinerare.net>

kevinb1989 and others added 3 commits July 22, 2025 23:43

Add mergeMetadata method to the Mailable class.

0937a0a

Update the test case for the mergeMetadata method.

ad755c9

formatting

ecea34d

taylorotwell merged commit 7c90894 into laravel:12.x Jul 22, 2025
60 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[12.x] Add mergeMetadata method to the Mailable class #56376

[12.x] Add mergeMetadata method to the Mailable class #56376

kevinb1989 commented Jul 22, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

[12.x] Add mergeMetadata method to the Mailable class #56376

[12.x] Add mergeMetadata method to the Mailable class #56376

Conversation

kevinb1989 commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevinb1989 commented Jul 22, 2025 •

edited

Loading