Rendering HTML and Plain Text Emails in Laravel

A Laravel mailable, the class that defines an email, can send a message as HTML, plain text, or both. HTML uses tags to organize and style a message. Plain text shows the message without HTML tags. In the mailable’s content configuration, you choose which versions Laravel creates.

For a custom email, you can use Blade, Laravel’s templating system, to create an HTML template and a separate plain-text template. Laravel can also create both formats from a Markdown mailable. Choose an approach based on whether the message needs visual styling, whether readers need a text version, and how many templates you want to maintain.

Choose Blade views or a Markdown mailable

A Blade template lets you control the HTML email’s layout and appearance. In the mailable’s content() method, set view to the HTML template and text to a separate template for the plain-text version:

use Illuminate\Mail\Mailables\Content;

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

Laravel also accepts html as an alias for view. Since you maintain a separate plain-text template, repeat the essential information there, including each important link’s destination; plain text cannot show a styled button. Laravel’s mailable content documentation shows this approach with two templates.

If you want to maintain one source template, use a Markdown mailable. Laravel renders its Markdown template into responsive HTML and creates a plain-text version. You can also supply a text view instead of using the generated text, as Laravel’s mailable implementation shows. Markdown means you maintain fewer templates. Separate Blade views give you direct control over each version.

What the recipient’s email client receives

An email with both formats can carry them as alternatives, or different versions of the same message. The MIME standard, which defines how email packages content, describes multipart/alternative as a way to package these versions. It places the richest version last so receiving software can choose the last format it can display. Laravel’s rendering settings alone do not show the exact MIME structure used by every mail transport or provider. The MIME standard explains how these alternatives work.

Laravel creates the email content from the templates. The mail transport, the service that sends the email, handles delivery, and the recipient’s email client displays it. To verify the final message’s structure or behavior, check the delivery path you configured.

When to use each format

Use HTML when visual structure helps readers, such as styled sections, a table, or a prominent call to action. Use plain text when the message reads naturally from start to finish or when you need a text-only version. Plain text has no HTML tags for styling or layout.

If a designed HTML email needs a plain-text version, create both with separate Blade templates or use a Markdown mailable to generate the text version. Include the message’s key details and usable links in the text. The MIME standard treats the formats as different ways to convey the same information, so include in each version any information readers need from the other.

A mailable’s render() method returns the finished HTML as a string. Laravel’s mail documentation describes tests that check HTML and plain-text content. If you provide both versions, test each one. A correct HTML template does not guarantee that the text version is useful.

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