邮件 - Laravel 13.x 中文文档

简介

发送邮件不必复杂。Laravel 基于流行的 Symfony Mailer 组件提供了简洁的邮件 API。Laravel 和 Symfony Mailer 提供了通过 SMTP、Cloudflare、Mailgun、Postmark、Resend、Amazon SES 和 sendmail 发送邮件的驱动，让你可以快速通过本地或云服务发送邮件。

配置

Laravel 的邮件服务通过应用的 config/mail.php 配置文件配置。该文件中配置的每个邮件器都可以有自己的独立配置甚至独立的「传输」，允许你的应用使用不同的邮件服务来发送某些邮件。例如，你的应用可能使用 Postmark 发送事务邮件，同时使用 Amazon SES 发送批量邮件。

在 mail 配置文件中，你会找到一个 mailers 配置数组。该数组包含 Laravel 支持的每个主要邮件驱动/传输的示例配置，而 default 配置值决定了当应用需要发送邮件时默认使用哪个邮件器。

驱动/传输前提条件

基于 API 的驱动（如 Mailgun、Postmark 和 Resend）通常比通过 SMTP 服务器发送邮件更简单、更快速。我们建议尽可能使用这些驱动之一。

Cloudflare 驱动

要使用 Cloudflare 驱动，通过 Composer 安装 Symfony 的 HTTP 客户端：

composer require symfony/http-client

接下来，需要在应用的 config/mail.php 配置文件中做两处修改。首先，将默认邮件器设置为 cloudflare：

'default' => env('MAIL_MAILER', 'cloudflare'),

其次，将以下配置数组添加到 mailers 数组中：

'cloudflare' => [
    'transport' => 'cloudflare',
],

配置好默认邮件器后，将以下选项添加到 config/services.php 配置文件中：

'cloudflare' => [
    'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
    'key' => env('CLOUDFLARE_KEY'),
],

Mailgun 驱动

要使用 Mailgun 驱动，通过 Composer 安装 Symfony 的 Mailgun Mailer 传输：

composer require symfony/mailgun-mailer symfony/http-client

接下来，需要在应用的 config/mail.php 配置文件中做两处修改。首先，将默认邮件器设置为 mailgun：

'default' => env('MAIL_MAILER', 'mailgun'),

其次，将以下配置数组添加到 mailers 数组中：

'mailgun' => [
    'transport' => 'mailgun',
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

配置好默认邮件器后，将以下选项添加到 config/services.php 配置文件中：

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
    'scheme' => 'https',
],

如果你不使用美国 Mailgun 区域，可以在 services 配置文件中定义你所在区域的端点：

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
    'scheme' => 'https',
],

Postmark 驱动

要使用 Postmark 驱动，通过 Composer 安装 Symfony 的 Postmark Mailer 传输：

composer require symfony/postmark-mailer symfony/http-client

接下来，将应用 config/mail.php 配置文件中的 default 选项设置为 postmark。配置好默认邮件器后，确保 config/services.php 配置文件包含以下选项：

'postmark' => [
    'key' => env('POSTMARK_API_KEY'),
],

如果想为给定邮件器指定应使用的 Postmark 消息流，可以在邮件器配置数组中添加 message_stream_id 配置选项。该配置数组可以在应用的 config/mail.php 配置文件中找到：

'postmark' => [
    'transport' => 'postmark',
    'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

这样你还可以设置使用不同消息流的多个 Postmark 邮件器。

Resend 驱动

要使用 Resend 驱动，通过 Composer 安装 Resend 的 PHP SDK：

composer require resend/resend-php

接下来，将应用 config/mail.php 配置文件中的 default 选项设置为 resend。配置好默认邮件器后，确保 config/services.php 配置文件包含以下选项：

'resend' => [
    'key' => env('RESEND_API_KEY'),
],

SES 驱动

要使用 Amazon SES 驱动，必须先安装 Amazon AWS SDK for PHP。可以通过 Composer 包管理器安装：

composer require aws/aws-sdk-php

接下来，将 config/mail.php 配置文件中的 default 选项设置为 ses，并验证 config/services.php 配置文件包含以下选项：

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
],

要通过会话令牌使用 AWS 临时凭证，可以在应用的 SES 配置中添加 token 键：

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'token' => env('AWS_SESSION_TOKEN'),
],

要使用 SES 的订阅管理功能，可以在邮件消息的 headers 方法返回的数组中返回 X-Ses-List-Management-Options 头：

/**
 * 获取消息头。
 */
public function headers(): Headers
{
    return new Headers(
        text: [
            'X-Ses-List-Management-Options' => 'contactListName=MyContactList;topicName=MyTopic',
        ],
    );
}

如果想定义 Laravel 在发送邮件时应传递给 AWS SDK SendEmail 方法的额外选项，可以在 ses 配置中定义 options 数组：

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'options' => [
        'ConfigurationSetName' => 'MyConfigurationSet',
        'EmailTags' => [
            ['Name' => 'foo', 'Value' => 'bar'],
        ],
    ],
],

故障转移配置

有时，你配置的用于发送应用邮件的外部服务可能宕机。在这些情况下，定义一个或多个备份邮件投递配置会很有用，以便在主投递驱动不可用时使用。

为此，应在应用的 mail 配置文件中定义一个使用 failover 传输的邮件器。failover 邮件器的配置数组应包含一个 mailers 数组，引用配置的邮件器应按何种顺序被选择用于投递：

'mailers' => [
    'failover' => [
        'transport' => 'failover',
        'mailers' => [
            'postmark',
            'mailgun',
            'sendmail',
        ],
        'retry_after' => 60,
    ],

    // ...
],

配置好使用 failover 传输的邮件器后，需要在应用的 .env 文件中将故障转移邮件器设置为默认邮件器才能使用故障转移功能：

MAIL_MAILER=failover

轮询配置

roundrobin 传输允许你将邮件工作负载分配到多个邮件器上。首先，在应用的 mail 配置文件中定义一个使用 roundrobin 传输的邮件器。roundrobin 邮件器的配置数组应包含一个 mailers 数组，引用哪些配置的邮件器应用于投递：

'mailers' => [
    'roundrobin' => [
        'transport' => 'roundrobin',
        'mailers' => [
            'ses',
            'postmark',
        ],
        'retry_after' => 60,
    ],

    // ...
],

定义好轮询邮件器后，应通过在应用的 mail 配置文件中将 default 配置键的值设置为其名称，将其设置为应用的默认邮件器：

'default' => env('MAIL_MAILER', 'roundrobin'),

轮询传输从配置的邮件器列表中随机选择一个邮件器，然后为后续每封邮件切换到下一个可用的邮件器。与帮助实现*高可用性的 failover 传输不同，roundrobin 传输提供负载均衡*。

生成邮件类

构建 Laravel 应用时，应用发送的每种类型的邮件都表示为一个「邮件类」。这些类存储在 app/Mail 目录中。如果应用中没有这个目录不必担心，使用 make:mail Artisan 命令创建第一个邮件类时会自动生成：

php artisan make:mail OrderShipped

编写邮件类

生成邮件类后，打开它来探索其内容。邮件类配置在几个方法中完成，包括 envelope、content 和 attachments 方法。

envelope() 方法返回一个 Illuminate\Mail\Mailables\Envelope 对象，定义邮件的主题，有时还定义收件人。content() 方法返回一个 Illuminate\Mail\Mailables\Content 对象，定义用于生成邮件内容的 Blade 模板。

配置发件人

使用 Envelope

首先，让我们探索如何配置邮件的发件人。换句话说，邮件的「发件人」地址。有两种方式配置发件人。第一种是在消息的信封上指定「from」地址：

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

/**
 * 获取消息信封。
 */
public function envelope(): Envelope
{
    return new Envelope(
        from: new Address('jeffrey@example.com', 'Jeffrey Way'),
        subject: 'Order Shipped',
    );
}

如果需要，还可以指定 replyTo 地址：

return new Envelope(
    from: new Address('jeffrey@example.com', 'Jeffrey Way'),
    replyTo: [
        new Address('taylor@example.com', 'Taylor Otwell'),
    ],
    subject: 'Order Shipped',
);

使用全局 from 地址

然而，如果你的应用所有邮件都使用相同的「from」地址，在每个邮件类中都添加它会很麻烦。你可以在 config/mail.php 配置文件中指定全局「from」地址。如果邮件类中没有指定其他「from」地址，将使用此地址：

'from' => [
    'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
    'name' => env('MAIL_FROM_NAME', 'Example'),
],

此外，还可以在 config/mail.php 配置文件中定义全局「reply_to」地址：

'reply_to' => [
    'address' => 'example@example.com',
    'name' => 'App Name',
],

配置视图

在邮件类的 content() 方法中，可以定义 view，即渲染邮件内容时应使用哪个模板。由于每封邮件通常使用 Blade 模板来渲染内容，在构建邮件 HTML 时你可以充分利用 Blade 模板引擎的全部功能：

/**
 * 获取消息内容定义。
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
    );
}

信息

你可能希望创建一个 resources/views/mail 目录来存放所有邮件模板；不过，你可以自由地将它们放在 resources/views 目录中的任何位置。

纯文本邮件

如果想定义邮件的纯文本版本，可以在创建消息的 Content 定义时指定纯文本模板。与 view 参数一样，text 参数应该是用于渲染邮件内容的模板名。你可以自由定义消息的 HTML 和纯文本版本：

/**
 * 获取消息内容定义。
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
        text: 'mail.orders.shipped-text'
    );
}

为清晰起见，html 参数可用作 view 参数的别名：

return new Content(
    html: 'mail.orders.shipped',
    text: 'mail.orders.shipped-text'
);

视图数据

通过公共属性

通常，你会想向视图传递一些数据，用于渲染邮件的 HTML。有两种方式可以让数据在视图中可用。第一种，邮件类上定义的任何公共属性都会自动在视图中可用。例如，可以将数据传递到邮件类的构造函数中，并将数据设置为类上定义的公共属性：

<?php

namespace App\Mail;

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

class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * 创建新消息实例。
     */
    public function __construct(
        public Order $order,
    ) {}

    /**
     * 获取消息内容定义。
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
        );
    }
}

一旦数据被设置为公共属性，它将自动在视图中可用，你可以像在 Blade 模板中访问其他数据一样访问它：

<div>
    Price: {{ $order->price }}
</div>

通过 with 参数

如果想在数据发送到模板之前自定义邮件数据的格式，可以通过 Content 定义的 with 参数手动将数据传递给视图。通常，你仍会通过邮件类的构造函数传递数据；但应将数据设置为 protected 或 private 属性，这样数据就不会自动在模板中可用：

<?php

namespace App\Mail;

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

class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * 创建新消息实例。
     */
    public function __construct(
        protected Order $order,
    ) {}

    /**
     * 获取消息内容定义。
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
            with: [
                'orderName' => $this->order->name,
                'orderPrice' => $this->order->price,
            ],
        );
    }
}

一旦数据通过 with 参数传递，它将自动在视图中可用，你可以像在 Blade 模板中访问其他数据一样访问它：

<div>
    Price: {{ $orderPrice }}
</div>

附件

要向邮件添加附件，需要将附件添加到消息的 attachments() 方法返回的数组中。首先，可以通过 Attachment 类提供的 fromPath() 方法提供文件路径来添加附件：

use Illuminate\Mail\Mailables\Attachment;

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file'),
    ];
}

添加附件时，还可以使用 as() 和 withMime() 方法指定附件的显示名称和/或 MIME 类型：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

从磁盘附加文件

如果已将文件存储在某个文件系统磁盘上，可以使用 fromStorage() 附件方法将其附加到邮件：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

当然，也可以指定附件的名称和 MIME 类型：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

如果需要指定非默认磁盘的存储磁盘，可以使用 fromStorageDisk() 方法：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorageDisk('s3', '/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf'),
    ];
}

原始数据附件

fromData() 附件方法可用于将原始字节字符串作为附件附加。例如，如果在内存中生成了 PDF 并想将其附加到邮件而不写入磁盘，就可以使用此方法。fromData() 方法接受一个解析原始数据字节的闭包以及附件应分配的名称：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromData(fn () => $this->pdf, 'Report.pdf')
            ->withMime('application/pdf'),
    ];
}

内嵌附件

将内嵌图片嵌入邮件通常很麻烦；但 Laravel 提供了一种便捷的方式来将图片附加到邮件中。要嵌入内嵌图片，在邮件模板中的 $message 变量上使用 embed() 方法。Laravel 会自动将 $message 变量提供给所有邮件模板，因此无需手动传递：

<body>
    Here is an image:

    <img src="{{ $message->embed($pathToImage) }}">
</body>

注意

$message 变量在纯文本消息模板中不可用，因为纯文本消息不使用内嵌附件。

嵌入原始数据附件

如果已有原始图片数据字符串并希望嵌入邮件模板，可以在 $message 变量上调用 embedData() 方法。调用 embedData() 方法时，需要提供应分配给嵌入图片的文件名：

<body>
    Here is an image from raw data:

    <img src="{{ $message->embedData($data, 'example-image.jpg') }}">
</body>

可附加对象

虽然通过简单的字符串路径附加文件到消息通常足够了，但在许多情况下，应用中可附加的实体由类表示。例如，如果应用正在将照片附加到消息，应用可能还有一个表示该照片的 Photo 模型。在这种情况下，直接将 Photo 模型传递给 attach 方法岂不是很方便？可附加对象正是为此而生。

首先，在将被附加到消息的对象上实现 Illuminate\Contracts\Mail\Attachable 接口。该接口要求类定义 toMailAttachment() 方法，返回 Illuminate\Mail\Attachment 实例：

<?php

namespace App\Models;

use Illuminate\Contracts\Mail\Attachable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Mail\Attachment;

class Photo extends Model implements Attachable
{
    /**
     * 获取模型的可附加表示。
     */
    public function toMailAttachment(): Attachment
    {
        return Attachment::fromPath('/path/to/file');
    }
}

定义可附加对象后，在构建邮件消息时可以从 attachments() 方法返回该对象的实例：

/**
 * 获取消息附件。
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [$this->photo];
}

当然，附件数据可能存储在 Amazon S3 等远程文件存储服务上。因此，Laravel 还允许你从应用的文件系统磁盘上存储的数据生成附件实例：

// 从默认磁盘上的文件创建附件...
return Attachment::fromStorage($this->path);

// 从特定磁盘上的文件创建附件...
return Attachment::fromStorageDisk('backblaze', $this->path);

此外，还可以通过内存中的数据创建附件实例。为此，向 fromData() 方法提供一个闭包。闭包应返回表示附件的原始数据：

return Attachment::fromData(fn () => $this->content, 'Photo Name');

Laravel 还提供了可用于自定义附件的其他方法。例如，可以使用 as() 和 withMime() 方法自定义文件名和 MIME 类型：

return Attachment::fromPath('/path/to/file')
    ->as('Photo Name')
    ->withMime('image/jpeg');

邮件头

有时你可能需要为发出的消息添加额外的邮件头。例如，可能需要设置自定义 Message-Id 或其他任意文本头。

为此，在邮件类上定义 headers() 方法。该方法应返回 Illuminate\Mail\Mailables\Headers 实例。该类接受 messageId、references 和 text 参数。当然，只需提供特定消息所需的参数：

use Illuminate\Mail\Mailables\Headers;

/**
 * 获取消息头。
 */
public function headers(): Headers
{
    return new Headers(
        messageId: 'custom-message-id@example.com',
        references: ['previous-message@example.com'],
        text: [
            'X-Custom-Header' => 'Custom Value',
        ],
    );
}

标签和元数据

一些第三方邮件提供商（如 Mailgun 和 Postmark）支持消息「标签」和「元数据」，可用于分组和跟踪应用发送的邮件。可以通过 Envelope 定义向邮件消息添加标签和元数据：

use Illuminate\Mail\Mailables\Envelope;

/**
 * 获取消息信封。
 *
 * @return \Illuminate\Mail\Mailables\Envelope
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        tags: ['shipment'],
        metadata: [
            'order_id' => $this->order->id,
        ],
    );
}

如果你的应用使用 Mailgun 驱动，可以查阅 Mailgun 文档了解更多关于标签和元数据的信息。同样，也可以查阅 Postmark 文档了解更多关于其标签和元数据支持的信息。

如果你的应用使用 Amazon SES 发送邮件，应使用 metadata 方法向消息附加 SES「标签」。

自定义 Symfony Message

Laravel 的邮件功能由 Symfony Mailer 驱动。Laravel 允许你注册自定义回调，在发送消息前用 Symfony Message 实例调用。这让你有机会在消息发送前深度自定义消息。为此，在 Envelope 定义上定义 using 参数：

use Illuminate\Mail\Mailables\Envelope;
use Symfony\Component\Mime\Email;

/**
 * 获取消息信封。
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        using: [
            function (Email $message) {
                // ...
            },
        ]
    );
}

Markdown 邮件

Markdown 邮件消息允许你在邮件类中利用邮件通知的预构建模板和组件。由于消息使用 Markdown 编写，Laravel 能够为消息渲染美观、响应式的 HTML 模板，同时自动生成纯文本对应版本。

生成 Markdown 邮件

要生成带有对应 Markdown 模板的邮件类，可以使用 make:mail Artisan 命令的 --markdown 选项：

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

然后，在 content() 方法中配置邮件 Content 定义时，使用 markdown 参数代替 view 参数：

use Illuminate\Mail\Mailables\Content;

/**
 * 获取消息内容定义。
 */
public function content(): Content
{
    return new Content(
        markdown: 'mail.orders.shipped',
        with: [
            'url' => $this->orderUrl,
        ],
    );
}

编写 Markdown 邮件

Markdown 邮件使用 Blade 组件和 Markdown 语法的组合，让你在利用 Laravel 预构建邮件 UI 组件的同时轻松构建邮件消息：

<x-mail::message>
# Order Shipped

Your order has been shipped!

<x-mail::button :url="$url">
View Order
</x-mail::button>

Thanks,<br>
{{ config('app.name') }}
</x-mail::message>

信息

编写 Markdown 邮件时不要使用过多缩进。根据 Markdown 标准，Markdown 解析器会将缩进内容渲染为代码块。

按钮组件

按钮组件渲染一个居中的按钮链接。该组件接受两个参数：url 和可选的 color。支持的颜色有 primary、success 和 error。可以在消息中添加任意数量的按钮组件：

<x-mail::button :url="$url" color="success">
View Order
</x-mail::button>

面板组件

面板组件将给定文本块渲染在背景色与消息其余部分略有不同的面板中。这让你可以吸引对特定文本块的注意：

<x-mail::panel>
This is the panel content.
</x-mail::panel>

表格组件

表格组件允许你将 Markdown 表格转换为 HTML 表格。该组件接受 Markdown 表格作为其内容。支持使用默认 Markdown 表格对齐语法进行列对齐：

<x-mail::table>
| Laravel       | Table         | Example       |
| ------------- | :-----------: | ------------: |
| Col 2 is      | Centered      | $10           |
| Col 3 is      | Right-Aligned | $20           |
</x-mail::table>

自定义组件

你可以将所有 Markdown 邮件组件导出到自己的应用中进行自定义。要导出组件，使用 vendor:publish Artisan 命令发布 laravel-mail 资产标签：

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

此命令将 Markdown 邮件组件发布到 resources/views/vendor/mail 目录。mail 目录将包含 html 和 text 目录，每个目录分别包含每个可用组件的对应表示。你可以自由自定义这些组件。

自定义 CSS

导出组件后，resources/views/vendor/mail/html/themes 目录将包含一个 default.css 文件。你可以自定义此文件中的 CSS，你的样式将自动转换为 Markdown 邮件消息 HTML 表示中的内联 CSS 样式。

如果想为 Laravel 的 Markdown 组件构建全新的主题，可以在 html/themes 目录中放置一个 CSS 文件。命名并保存 CSS 文件后，更新应用 config/mail.php 配置文件中的 theme 选项以匹配新主题的名称。

要为单个邮件类自定义主题，可以将邮件类的 $theme 属性设置为发送该邮件时应使用的主题名称。

发送邮件

要发送消息，使用 Mail 门面的 to() 方法。to() 方法接受电子邮件地址、用户实例或用户集合。如果传递对象或对象集合，邮件器将自动使用其 email 和 name 属性来确定邮件的收件人，因此请确保这些属性在对象上可用。指定收件人后，可以将邮件类实例传递给 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');
    }
}

发送消息时不限于只指定「to」收件人。可以通过链式调用相应方法来设置「to」、「cc」和「bcc」收件人：

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

遍历收件人

有时，你可能需要通过遍历收件人/电子邮件地址数组来向收件人列表发送邮件。但由于 to() 方法会将电子邮件地址追加到邮件的收件人列表中，每次循环迭代都会向之前的每个收件人发送另一封邮件。因此，应始终为每个收件人重新创建邮件实例：

foreach (['taylor@example.com', 'dries@example.com'] as $recipient) {
    Mail::to($recipient)->send(new OrderShipped($order));
}

通过特定邮件器发送邮件

默认情况下，Laravel 会使用应用 mail 配置文件中配置为 default 的邮件器发送邮件。但可以使用 mailer() 方法通过特定邮件器配置发送消息：

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

队列发送

队列发送邮件消息

由于发送邮件可能对应用的响应时间产生负面影响，许多开发者选择将邮件消息放入队列进行后台发送。Laravel 使用其内置的统一队列 API让这变得简单。要队列发送邮件消息，在指定消息收件人后使用 Mail 门面的 queue() 方法：

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue(new OrderShipped($order));

此方法会自动将任务推入队列，使消息在后台发送。使用此功能前需要配置队列。

延迟消息队列

如果想延迟投递队列邮件消息，可以使用 later() 方法。later() 方法的第一个参数接受一个 DateTime 实例，指示消息应在何时发送：

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

推送到特定队列

由于所有通过 make:mail 命令生成的邮件类都使用 Illuminate\Bus\Queueable trait，可以在任何邮件类实例上调用 onQueue() 和 onConnection() 方法，指定消息的连接和队列名称：

$message = (new OrderShipped($order))
    ->onConnection('sqs')
    ->onQueue('emails');

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue($message);

或者，可以在邮件类上使用 Connection 和 Queue 属性指定连接和队列：

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

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

默认队列

如果有邮件类始终希望被队列发送，可以在类上实现 ShouldQueue 契约。这样，即使发送邮件时调用 send() 方法，邮件仍会被队列处理，因为它实现了该契约：

use Illuminate\Contracts\Queue\ShouldQueue;

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

队列邮件与数据库事务

当队列邮件在数据库事务内分派时，它们可能在数据库事务提交之前就被队列处理。发生这种情况时，在数据库事务期间对模型或数据库记录所做的任何更新可能尚未反映在数据库中。此外，在事务内创建的任何模型或数据库记录可能不存在于数据库中。如果你的邮件依赖于这些模型，发送队列邮件的任务被处理时可能会发生意外错误。

如果队列连接的 after_commit 配置选项设置为 false，仍可以通过在发送邮件消息时调用 afterCommit() 方法来指示特定队列邮件应在所有打开的数据库事务提交后再分派：

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

或者，可以在邮件类的构造函数中调用 afterCommit() 方法：

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class OrderShipped extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels;

    /**
     * 创建新消息实例。
     */
    public function __construct()
    {
        $this->afterCommit();
    }
}

信息

要了解更多关于解决这些问题的信息，请查阅队列任务与数据库事务的文档。

队列邮件失败

当队列邮件失败时，如果已定义，将调用队列邮件类的 failed() 方法。导致队列邮件失败的 Throwable 实例将传递给 failed() 方法：

<?php

namespace App\Mail;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Throwable;

class OrderDelayed extends Mailable implements ShouldQueue
{
    use SerializesModels;

    /**
     * 处理队列邮件失败。
     */
    public function failed(Throwable $exception): void
    {
        // ...
    }
}

渲染邮件

有时你可能想在不发送邮件的情况下获取其 HTML 内容。为此，可以调用邮件类的 render() 方法。该方法将邮件的评估 HTML 内容作为字符串返回：

use App\Mail\InvoicePaid;
use App\Models\Invoice;

$invoice = Invoice::find(1);

return (new InvoicePaid($invoice))->render();

在浏览器中预览邮件

设计邮件模板时，像典型 Blade 模板一样在浏览器中快速预览渲染后的邮件非常方便。为此，Laravel 允许你直接从路由闭包或控制器返回任何邮件类。返回邮件类时，它将被渲染并显示在浏览器中，让你无需发送到实际电子邮件地址即可快速预览其设计：

Route::get('/mailable', function () {
    $invoice = App\Models\Invoice::find(1);

    return new App\Mail\InvoicePaid($invoice);
});

本地化邮件

Laravel 允许你以请求当前语言环境以外的语言环境发送邮件，如果邮件被队列发送，还会记住此语言环境。

为此，Mail 门面提供了 locale() 方法来设置所需语言。当邮件模板被评估时，应用将切换到此语言环境，评估完成后恢复到之前的语言环境：

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

用户首选语言环境

有时，应用会存储每个用户的首选语言环境。通过在一个或多个模型上实现 HasLocalePreference 契约，可以指示 Laravel 在发送邮件时使用此存储的语言环境：

use Illuminate\Contracts\Translation\HasLocalePreference;

class User extends Model implements HasLocalePreference
{
    /**
     * 获取用户首选语言环境。
     */
    public function preferredLocale(): string
    {
        return $this->locale;
    }
}

实现接口后，Laravel 在向模型发送邮件和通知时会自动使用首选语言环境。因此，使用此接口时无需调用 locale() 方法：

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

测试

测试邮件内容

Laravel 提供了多种方法来检查邮件类的结构。此外，Laravel 还提供了几种便捷方法来测试邮件是否包含你期望的内容：

use App\Mail\InvoicePaid;
use App\Models\User;

test('mailable content', function () {
    $user = User::factory()->create();

    $mailable = new InvoicePaid($user);

    $mailable->assertFrom('jeffrey@example.com');
    $mailable->assertTo('taylor@example.com');
    $mailable->assertHasCc('abigail@example.com');
    $mailable->assertHasBcc('victoria@example.com');
    $mailable->assertHasReplyTo('tyler@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');

    $mailable->assertSeeInHtml($user->email);
    $mailable->assertDontSeeInHtml('Invoice Not Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);

    $mailable->assertSeeInText($user->email);
    $mailable->assertDontSeeInText('Invoice Not Paid');
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);

    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
});

use App\Mail\InvoicePaid;
use App\Models\User;

public function test_mailable_content(): void
{
    $user = User::factory()->create();

    $mailable = new InvoicePaid($user);

    $mailable->assertFrom('jeffrey@example.com');
    $mailable->assertTo('taylor@example.com');
    $mailable->assertHasCc('abigail@example.com');
    $mailable->assertHasBcc('victoria@example.com');
    $mailable->assertHasReplyTo('tyler@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');

    $mailable->assertSeeInHtml($user->email);
    $mailable->assertDontSeeInHtml('Invoice Not Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);

    $mailable->assertSeeInText($user->email);
    $mailable->assertDontSeeInText('Invoice Not Paid');
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);

    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
}

如你所料，「HTML」断言用于检查邮件 HTML 版本是否包含给定字符串，而「text」断言用于检查邮件纯文本版本是否包含给定字符串。

测试邮件发送

我们建议将邮件内容的测试与断言给定邮件已「发送」给特定用户的测试分开。通常，邮件内容与你测试的代码无关，只需断言 Laravel 已被指示发送给定邮件即可。

可以使用 Mail 门面的 fake() 方法阻止邮件被发送。调用 fake() 方法后，可以断言邮件已被指示发送给用户，甚至检查邮件接收的数据：

<?php

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

test('orders can be shipped', function () {
    Mail::fake();

    // 执行订单发货...

    // 断言没有发送任何邮件...
    Mail::assertNothingSent();

    // 断言已发送邮件...
    Mail::assertSent(OrderShipped::class);

    // 断言邮件发送了两次...
    Mail::assertSent(OrderShipped::class, 2);

    // 断言邮件发送到某个电子邮件地址...
    Mail::assertSent(OrderShipped::class, 'example@laravel.com');

    // 断言邮件发送到多个电子邮件地址...
    Mail::assertSent(OrderShipped::class, ['example@laravel.com', '...']);

    // 断言未发送某邮件...
    Mail::assertNotSent(AnotherMailable::class);

    // 断言邮件发送了两次...
    Mail::assertSentTimes(OrderShipped::class, 2);

    // 断言总共发送了 3 封邮件...
    Mail::assertSentCount(3);
});

<?php

namespace Tests\Feature;

use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_orders_can_be_shipped(): void
    {
        Mail::fake();

        // 执行订单发货...

        // 断言没有发送任何邮件...
        Mail::assertNothingSent();

        // 断言已发送邮件...
        Mail::assertSent(OrderShipped::class);

        // 断言邮件发送了两次...
        Mail::assertSent(OrderShipped::class, 2);

        // 断言邮件发送到某个电子邮件地址...
        Mail::assertSent(OrderShipped::class, 'example@laravel.com');

        // 断言邮件发送到多个电子邮件地址...
        Mail::assertSent(OrderShipped::class, ['example@laravel.com', '...']);

        // 断言未发送某邮件...
        Mail::assertNotSent(AnotherMailable::class);

        // 断言邮件发送了两次...
        Mail::assertSentTimes(OrderShipped::class, 2);

        // 断言总共发送了 3 封邮件...
        Mail::assertSentCount(3);
    }
}

如果将邮件队列发送以在后台投递，应使用 assertQueued 方法代替 assertSent：

Mail::assertQueued(OrderShipped::class);
Mail::assertNotQueued(OrderShipped::class);
Mail::assertNothingQueued();
Mail::assertQueuedCount(3);

还可以使用 assertOutgoingCount 方法断言已发送或队列发送的邮件总数：

Mail::assertOutgoingCount(3);

可以向 assertSent、assertNotSent、assertQueued 或 assertNotQueued 方法传递闭包，以断言已发送通过给定「真值测试」的邮件。如果至少发送了一封通过给定真值测试的邮件，则断言成功：

Mail::assertSent(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

调用 Mail 门面的断言方法时，提供的闭包接受的邮件实例暴露了用于检查邮件的有用方法：

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($user) {
    return $mail->hasTo($user->email) &&
           $mail->hasCc('...') &&
           $mail->hasBcc('...') &&
           $mail->hasReplyTo('...') &&
           $mail->hasFrom('...') &&
           $mail->hasSubject('...') &&
           $mail->hasMetadata('order_id', $mail->order->id);
           $mail->usesMailer('ses');
});

邮件实例还包含几个有用的方法来检查邮件上的附件：

use Illuminate\Mail\Mailables\Attachment;

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromPath('/path/to/file')
            ->as('name.pdf')
            ->withMime('application/pdf')
    );
});

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromStorageDisk('s3', '/path/to/file')
    );
});

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($pdfData) {
    return $mail->hasAttachment(
        Attachment::fromData(fn () => $pdfData, 'name.pdf')
    );
});

你可能注意到有两种断言邮件未发送的方法：assertNotSent 和 assertNotQueued。有时你可能想断言没有邮件被发送或队列发送。为此，可以使用 assertNothingOutgoing 和 assertNotOutgoing 方法：

Mail::assertNothingOutgoing();

Mail::assertNotOutgoing(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

邮件与本地开发

开发发送邮件的应用时，你可能不想实际将邮件发送到真实的电子邮件地址。Laravel 提供了几种在本地开发期间「禁用」实际邮件发送的方式。

日志驱动

log 邮件驱动不会发送邮件，而是将所有邮件消息写入日志文件以供检查。通常，此驱动仅在本地开发期间使用。有关按环境配置应用的更多信息，请查阅配置文档。

HELO / Mailtrap / Mailpit

或者，你可以使用 HELO 或 Mailtrap 等服务和 smtp 驱动将邮件消息发送到「虚拟」邮箱，在真实的邮件客户端中查看它们。这种方式的好处是可以让你在 Mailtrap 的消息查看器中实际检查最终邮件。

如果使用 Laravel Sail，可以使用 Mailpit 预览消息。Sail 运行时，可以通过 http://localhost:8025 访问 Mailpit 界面。

使用全局 to 地址

最后，可以通过调用 Mail 门面提供的 alwaysTo() 方法指定全局「to」地址。通常，此方法应从应用某个服务提供者的 boot() 方法中调用：

use Illuminate\Support\Facades\Mail;

/**
 * 引导应用服务。
 */
public function boot(): void
{
    if ($this->app->environment('local')) {
        Mail::alwaysTo('taylor@example.com');
    }
}

使用 alwaysTo() 方法时，邮件消息上的任何额外「cc」或「bcc」地址都将被移除。

事件

Laravel 在发送邮件消息时分派两个事件。MessageSending 事件在消息发送前分派，MessageSent 事件在消息发送后分派。请记住，这些事件在邮件被发送时分派，而不是在队列发送时分派。你可以在应用中为这些事件创建事件监听器：

use Illuminate\Mail\Events\MessageSending;
// use Illuminate\Mail\Events\MessageSent;

class LogMessage
{
    /**
     * 处理事件。
     */
    public function handle(MessageSending $event): void
    {
        // ...
    }
}

自定义传输

Laravel 包含多种邮件传输；不过，你可能想编写自己的传输来通过 Laravel 开箱不支持的其他服务投递邮件。首先，定义一个继承 Symfony\Component\Mailer\Transport\AbstractTransport 类的类。然后，在传输上实现 doSend() 和 __toString() 方法：

<?php

namespace App\Mail;

use MailchimpTransactional\ApiClient;
use Symfony\Component\Mailer\SentMessage;
use Symfony\Component\Mailer\Transport\AbstractTransport;
use Symfony\Component\Mime\Address;
use Symfony\Component\Mime\MessageConverter;

class MailchimpTransport extends AbstractTransport
{
    /**
     * 创建新的 Mailchimp 传输实例。
     */
    public function __construct(
        protected ApiClient $client,
    ) {
        parent::__construct();
    }

    /**
     * {@inheritDoc}
     */
    protected function doSend(SentMessage $message): void
    {
        $email = MessageConverter::toEmail($message->getOriginalMessage());

        $this->client->messages->send(['message' => [
            'from_email' => $email->getFrom(),
            'to' => collect($email->getTo())->map(function (Address $email) {
                return ['email' => $email->getAddress(), 'type' => 'to'];
            })->all(),
            'subject' => $email->getSubject(),
            'text' => $email->getTextBody(),
        ]]);
    }

    /**
     * 获取传输的字符串表示。
     */
    public function __toString(): string
    {
        return 'mailchimp';
    }
}

定义自定义传输后，可以通过 Mail 门面提供的 extend() 方法注册它。通常，这应在应用 AppServiceProvider 的 boot() 方法中完成。$config 参数将传递给 extend() 方法提供的闭包。此参数包含应用 config/mail.php 配置文件中为邮件器定义的配置数组：

use App\Mail\MailchimpTransport;
use Illuminate\Support\Facades\Mail;
use MailchimpTransactional\ApiClient;

/**
 * 引导应用服务。
 */
public function boot(): void
{
    Mail::extend('mailchimp', function (array $config = []) {
        $client = new ApiClient;

        $client->setApiKey($config['key']);

        return new MailchimpTransport($client);
    });
}

定义并注册自定义传输后，可以在应用的 config/mail.php 配置文件中创建使用新传输的邮件器定义：

'mailchimp' => [
    'transport' => 'mailchimp',
    'key' => env('MAILCHIMP_API_KEY'),
    // ...
],

额外的 Symfony 传输

Laravel 包含对一些 Symfony 维护的邮件传输（如 Mailgun 和 Postmark）的支持。但你可能希望扩展 Laravel 以支持其他 Symfony 维护的传输。可以通过 Composer 安装必要的 Symfony 邮件器并注册传输来实现。例如，可以安装并注册「Brevo」（前称「Sendinblue」）Symfony 邮件器：

composer require symfony/brevo-mailer symfony/http-client

安装 Brevo 邮件器包后，可以在应用的 services 配置文件中添加 Brevo API 凭证条目：

'brevo' => [
    'key' => env('BREVO_API_KEY'),
],

接下来，可以使用 Mail 门面的 extend() 方法将传输注册到 Laravel。通常，这应在服务提供者的 boot() 方法中完成：

use Illuminate\Support\Facades\Mail;
use Symfony\Component\Mailer\Bridge\Brevo\Transport\BrevoTransportFactory;
use Symfony\Component\Mailer\Transport\Dsn;

/**
 * 引导应用服务。
 */
public function boot(): void
{
    Mail::extend('brevo', function () {
        return (new BrevoTransportFactory)->create(
            new Dsn(
                'brevo+api',
                'default',
                config('services.brevo.key')
            )
        );
    });
}

注册传输后，可以在应用的 config/mail.php 配置文件中创建使用新传输的邮件器定义：

'brevo' => [
    'transport' => 'brevo',
    // ...
],