Choosing Between Blade, Markdown, and Plain Text Mailables

In Laravel, a mailable is a PHP class that defines an email’s content and delivery details. You choose how Laravel renders the mailable: as HTML, plain text, or both. HTML uses markup to format content; plain text contains words without HTML markup.

Choose a Blade view, a template written in Laravel’s templating language, for direct control over HTML. Choose Markdown when Laravel’s email components suit your message; Laravel renders it as HTML and plain text. For text-only content, or when you write a separate text version, use a plain-text template. These options apply to Laravel 13.x. If you use another release, check its documentation. Laravel’s mail documentation describes the available content options and rendering behavior.

Use Blade for direct HTML control

Blade is Laravel’s templating language. Laravel renders a Blade view as the email’s HTML content, where you can place dynamic values and template logic. Laravel also accepts html: as an alias for view:.

public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
    );
}

Choose a Blade view when you need direct control over the HTML layout and content. If you also want a text version, name a separate template with text::

public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
        text: 'mail.orders.shipped-text',
    );
}

Laravel renders the two templates as separate HTML and text representations. The mailable implementation shows how Laravel handles those configured views. Writing both templates gives you control over each version’s wording and structure.

Use Markdown for component-based emails

A Markdown mailable lets you write the message with Markdown syntax and Laravel’s mail components. These components provide ready-made structures for elements such as buttons and tables. Laravel renders the message into HTML and also generates a text representation.

public function content(): Content
{
    return new Content(
        markdown: 'mail.orders.shipped',
        with: ['url' => $this->orderUrl],
    );
}

Choose Markdown when its components suit the message and you want Laravel to generate both representations from one authored message. Laravel also supports publishing the mail components for customization. The published components include separate HTML and text versions. You can also customize the HTML theme’s CSS. Review the rendered versions after customization to confirm they convey the same information. The Laravel mail documentation covers Markdown mail and its customization options.

Use a text template for text-only mail or separate wording

The text: option points to a template Laravel renders as plain-text content. That template can stand alone or accompany a Blade HTML view.

public function content(): Content
{
    return new Content(
        text: 'mail.orders.shipped-text',
    );
}

Choose text-only content when the message should be delivered as text without an HTML representation. Pair text: with view: when you want to author the HTML and text versions independently. In Laravel, “plain text” describes the rendered output; the content still comes from a named template.

Match the mode to the email

The Laravel Content API lists the content options behind these choices. Choose Markdown to avoid writing separate templates when its components fit your message. Use Blade for custom HTML, and add a text template when you want to write the text version yourself.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com