郵件寄送

Laravel 的郵件功能是什麼

Laravel 的郵件功能建立在 Symfony Mailer 之上，支援 SMTP、Mailgun、Postmark、Resend、Amazon SES、sendmail 等驅動。

以往 Laravel 使用的 SwiftMailer 已被廢棄。Laravel 9 以後改用 Symfony Mailer。

郵件設定於 config/mail.php 管理。可透過 .env 切換使用的驅動。

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

建立 Mailable 類別

在 Laravel 中，每封應用程式寄出的信會以「Mailable」類別表達。可用 make:mail Artisan 指令建立。

php artisan make:mail OrderShipped

產生的類別會放到 app/Mail/ 目錄。

Mailable 設定

產生的 Mailable 類別會有 envelope()、content()、attachments() 3 個方法。

<?php

namespace App\Mail;

use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;

    public function __construct(
        public Order $order,
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: '訂單已出貨',
        );
    }

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

    public function attachments(): array
    {
        return [];
    }
}

設定寄件者

於 envelope() 指定寄件者。

use Illuminate\Mail\Mailables\Address;
use Illuminate\Mail\Mailables\Envelope;

public function envelope(): Envelope
{
    return new Envelope(
        from: new Address('[email protected]', 'Shop Support'),
        subject: '訂單已出貨',
    );
}

若在 config/mail.php 設定全域寄件者，個別 Mailable 就可省略。

'from' => [
    'address' => env('MAIL_FROM_ADDRESS', '[email protected]'),
    'name' => env('MAIL_FROM_NAME', 'Example'),
],

設定郵件內容

在 content() 指定 Blade 樣板。建構子中設定為 public 屬性的資料會自動可在樣板中使用。

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

建立對應的 Blade 樣板（resources/views/mail/orders/shipped.blade.php）：

<!DOCTYPE html>
<html>
<body>
    <h1>您的訂單已出貨</h1>
    <p>訂單編號：{{ $order->id }}</p>
    <p>總金額：¥{{ number_format($order->total) }}</p>
    <p>感謝您的訂購。</p>
</body>
</html>

也可以透過 with 明確傳入資料。此時屬性可設為 protected 或 private。

public function __construct(
    protected Order $order,
) {}

public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
        with: [
            'orderId' => $this->order->id,
            'total' => $this->order->total,
        ],
    );
}

寄送郵件

用 Mail Facade 的 to() 指定收件者，send() 寄送。

<?php

namespace App\Http\Controllers;

use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;

class OrderShipmentController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);

        Mail::to($request->user())->send(new OrderShipped($order));

        return redirect('/orders');
    }
}

可指定 CC / BCC。

Mail::to($request->user())
    ->cc($ccUsers)
    ->bcc($bccUsers)
    ->send(new OrderShipped($order));

用特定 mailer 寄送可使用 mailer()：

Mail::mailer('postmark')
    ->to($request->user())
    ->send(new OrderShipped($order));

使用佇列寄送郵件

郵件寄送會影響回應時間，建議透過佇列在背景寄送。

Mail::to($request->user())->queue(new OrderShipped($order));

使用佇列前需先設定佇列並啟動 worker。

也可以延遲寄送：

Mail::to($request->user())
    ->later(now()->plus(minutes: 10), new OrderShipped($order));

在 Mailable 類別實作 ShouldQueue，即使呼叫 send() 也一定會進入佇列。

use Illuminate\Contracts\Queue\ShouldQueue;

class OrderShipped extends Mailable implements ShouldQueue
{
    // ...
}

用 PHP 屬性指定佇列連線與佇列名稱

可用 PHP 屬性直接於 Mailable 上指定佇列連線與名稱，取代 on()->queue() 方法鏈，以類別層級宣告式設定。

use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Queue;

#[Connection('sqs')]
#[Queue('emails')]
class OrderShipped extends Mailable implements ShouldQueue
{
    // ...
}

如此一來，可在類別定義上明確表示此 Mailable 永遠會送到 SQS 連線的 emails 佇列。

建立 Markdown Mail

使用 Markdown 格式的郵件，可運用 Laravel 提供的漂亮響應式 HTML 樣板。

產生 Markdown Mailable

以 --markdown 選項產生 Mailable。

php artisan make:mail OrderShipped --markdown=mail.orders.shipped

於 content() 使用 markdown 參數：

use Illuminate\Mail\Mailables\Content;

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

撰寫 Markdown 樣板

以 Laravel 提供的 Blade 元件撰寫內容。

<x-mail::message>
# 您的訂單已出貨

我們通知您訂單已出貨。

<x-mail::button :url="$url">
查看訂單
</x-mail::button>

感謝您的支持。<br>
{{ config('app.name') }}
</x-mail::message>

可用的元件：

元件	說明
`<x-mail::button>`	按鈕連結（`color` 可指定 `primary`、`success`、`error`）
`<x-mail::panel>`	醒目面板
`<x-mail::table>`	Markdown 格式的表格

Markdown 郵件會同時自動產生純文字版本。即便使用不支援 HTML 的信箱也能讀取。

郵件預覽

從路由回傳 Mailable 實例即可在瀏覽器預覽。適合開發期確認。

// routes/web.php
Route::get('/mailable', function () {
    $order = App\Models\Order::first();
    return new App\Mail\OrderShipped($order);
});

本機開發時的郵件

為避免在本機不小心寄送到正式環境的信箱，可以使用 Mailpit 等工具。

# .env (Mailpit)
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

Laragon 或 Laravel Herd 皆預設內含 Mailpit。

使用 log 驅動時，郵件內容會記錄到日誌檔。若只是想確認寄信這是最方便的方式。

MAIL_MAILER=log

總結

想要做的事	方法
建立 Mailable	`php artisan make:mail ClassName`
設定寄件者	`envelope()` 的 `from` 參數
使用 Blade 樣板	`content()` 的 `view` 參數
使用 Markdown 樣板	`content()` 的 `markdown` 參數
寄送郵件	`Mail::to()->send()`
用佇列寄送	`Mail::to()->queue()`
延遲寄送	`Mail::to()->later()`

架構

資料庫

Eloquent

安全性

事件

郵件與通知

付款

非同步處理

即時通訊

排程

快取與最佳化

國際化

檔案與儲存

偵錯與監控

主控台與 CLI

效能

前端

AI 開發

開發環境

Laravel 的郵件功能是什麼

建立 Mailable 類別

Mailable 設定

設定寄件者

設定郵件內容

寄送郵件

使用佇列寄送郵件

用 PHP 屬性指定佇列連線與佇列名稱

建立 Markdown Mail

產生 Markdown Mailable

撰寫 Markdown 樣板

郵件預覽

本機開發時的郵件

總結

​Laravel 的郵件功能是什麼

​建立 Mailable 類別

​Mailable 設定

​設定寄件者

​設定郵件內容

​寄送郵件

​使用佇列寄送郵件

​用 PHP 屬性指定佇列連線與佇列名稱

​建立 Markdown Mail

​產生 Markdown Mailable

​撰寫 Markdown 樣板

​郵件預覽

​本機開發時的郵件

​總結

Laravel 的郵件功能是什麼

建立 Mailable 類別

Mailable 設定

設定寄件者

設定郵件內容

寄送郵件

使用佇列寄送郵件

用 PHP 屬性指定佇列連線與佇列名稱

建立 Markdown Mail

產生 Markdown Mailable

撰寫 Markdown 樣板

郵件預覽

本機開發時的郵件

總結