Laravel 12 : Emails Markdown - Guide Complet

laravel
php
tutorial
email
Author

Sylvain Pham

Published

December 29, 2025

Guide complet pour creer et envoyer des emails avec les Markdown Mailables de Laravel 12.

Vue d’ensemble

┌─────────────────────────────────────────────────────────────────────────────┐
│                        MARKDOWN MAILABLES                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   php artisan make:mail NomDuMail --markdown=emails.template                │
│                              │                                              │
│                              ▼                                              │
│        ┌─────────────────────────────────────────┐                          │
│        │  app/Mail/NomDuMail.php                 │                          │
│        │  resources/views/emails/template.blade  │                          │
│        └─────────────────────────────────────────┘                          │
│                              │                                              │
│                              ▼                                              │
│        ┌─────────────────────────────────────────┐                          │
│        │  Mail::to($user)->send(new NomDuMail()) │                          │
│        └─────────────────────────────────────────┘                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Creer un Mailable

php artisan make:mail WelcomeUser --markdown=emails.welcome

Cree automatiquement :

Fichier Role
app/Mail/WelcomeUser.php Classe Mailable
resources/views/emails/welcome.blade.php Template Markdown

Structure du Mailable (Laravel 12)

<?php

namespace App\Mail;

use App\Models\User;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;

class WelcomeUser extends Mailable
{
    public function __construct(
        public User $user
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Bienvenue!',
        );
    }

    public function content(): Content
    {
        return new Content(
            markdown: 'emails.welcome',
            with: [
                'user' => $this->user,
                'url' => 'https://example.com',
            ],
        );
    }
}

Composants Blade disponibles

Message wrapper (obligatoire)

Tout email Markdown doit etre enveloppe dans ce composant :

<x-mail::message>
Contenu du mail ici...
</x-mail::message>

Bouton CTA

{{-- Bouton par defaut (bleu) --}}
<x-mail::button :url="$url">
Cliquer ici
</x-mail::button>

{{-- Bouton vert --}}
<x-mail::button :url="$url" color="success">
Confirmer
</x-mail::button>

{{-- Bouton rouge --}}
<x-mail::button :url="$url" color="error">
Supprimer
</x-mail::button>

Panel (encadre avec bordure)

Pour mettre en valeur une information importante :

<x-mail::panel>
**Info importante:** Texte mis en valeur ici.
</x-mail::panel>

Table

<x-mail::table>
| Colonne 1 | Colonne 2 |
|:----------|:----------|
| Valeur 1  | Valeur 2  |
| Valeur 3  | Valeur 4  |
</x-mail::table>

Alignement des colonnes :

Syntaxe Alignement
:--- Gauche
:--: Centre
---: Droite

Envoyer un mail

use App\Mail\WelcomeUser;
use Illuminate\Support\Facades\Mail;

// Envoi simple
Mail::to($user->email)->send(new WelcomeUser($user));

// Avec cc/bcc
Mail::to($user)
    ->cc('autre@example.com')
    ->bcc('admin@example.com')
    ->send(new WelcomeUser($user));

// En queue (asynchrone - recommande)
Mail::to($user)->queue(new WelcomeUser($user));

Preview dans le navigateur

Tres utile pour le developpement - permet de voir le rendu sans envoyer de mail :

// routes/web.php
Route::get('/preview-email', function () {
    $user = User::first() ?? new User([
        'name' => 'Test User',
        'email' => 'test@example.com',
    ]);

    return new App\Mail\WelcomeUser($user);
});

Visiter : http://localhost/preview-email

Configuration SMTP

Mailtrap (dev/test)

MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=ton_username
MAIL_PASSWORD=ton_password
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"

Gmail

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=ton.email@gmail.com
MAIL_PASSWORD=app_password_16_chars
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="ton.email@gmail.com"
MAIL_FROM_NAME="${APP_NAME}"
Note

Pour Gmail, il faut creer un App Password sur https://myaccount.google.com/apppasswords

Resend

MAIL_MAILER=resend
RESEND_KEY=re_xxxxxxxxxxxx
MAIL_FROM_ADDRESS="noreply@ton-domaine.com"

Personnaliser le theme

php artisan vendor:publish --tag=laravel-mail

Fichiers publies dans resources/views/vendor/mail/ :

Fichier Role
html/themes/default.css Couleurs, fonts, espacements
html/layout.blade.php Structure HTML
html/header.blade.php Logo/header
html/footer.blade.php Footer

Template complet exemple

<x-mail::message>
# Bienvenue {{ $user->name }}!

Merci de vous etre inscrit sur notre plateforme.

<x-mail::button :url="$dashboardUrl">
Acceder au Dashboard
</x-mail::button>

<x-mail::panel>
**Astuce:** Completez votre profil pour debloquer toutes les fonctionnalites.
</x-mail::panel>

## Vos informations

<x-mail::table>
| Info   | Valeur             |
|:-------|:-------------------|
| Nom    | {{ $user->name }}  |
| Email  | {{ $user->email }} |
</x-mail::table>

Cordialement,<br>
L'equipe **{{ config('app.name') }}**
</x-mail::message>

Rendu final

Exemple de rendu d’un email Markdown Laravel

Commandes utiles

# Creer un mailable
php artisan make:mail NomDuMail --markdown=emails.nom

# Publier les templates pour personnalisation
php artisan vendor:publish --tag=laravel-mail

# Vider le cache des vues
php artisan view:clear

Workflow de developpement

┌─────────────────────────────────────────────────────────────────────────────┐
│                         WORKFLOW EMAIL                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. Creer ────► php artisan make:mail NomMail --markdown=emails.template    │
│                                                                             │
│  2. Editer ───► app/Mail/NomMail.php (envelope, content)                    │
│                 resources/views/emails/template.blade.php                   │
│                                                                             │
│  3. Preview ──► Route::get('/preview', fn() => new NomMail($data));         │
│                                                                             │
│  4. Test ─────► Mailtrap ou autre service SMTP de test                      │
│                                                                             │
│  5. Prod ─────► Resend, Mailgun, SES, etc.                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘