邮件

介绍
生成邮件类
编写邮件类
Markdown 邮件类
发送邮件
- 队列邮件
渲染邮件类
- 在浏览器中预览邮件类
本地化邮件类
测试邮件类
邮件与本地开发
事件
自定义传输
- 额外的 Symfony 传输

介绍

发送电子邮件不必复杂。Laravel 提供了一个由流行的 Symfony Mailer 组件支持的简洁、简单的电子邮件 API。Laravel 和 Symfony Mailer 提供了通过 SMTP、Mailgun、Postmark、Amazon SES 和 sendmail 发送电子邮件的驱动程序，使您可以快速开始通过您选择的本地或基于云的服务发送邮件。

配置

Laravel 的电子邮件服务可以通过应用程序的 config/mail.php 配置文件进行配置。此文件中配置的每个邮件程序都可以有其独特的配置，甚至可以有其独特的“传输”，允许您的应用程序使用不同的电子邮件服务发送某些电子邮件消息。例如，您的应用程序可能使用 Postmark 发送事务性电子邮件，而使用 Amazon SES 发送批量电子邮件。

在您的 mail 配置文件中，您会发现一个 mailers 配置数组。此数组包含 Laravel 支持的主要邮件驱动程序/传输的示例配置条目，而 default 配置值决定了当您的应用程序需要发送电子邮件消息时将使用哪个邮件程序。

驱动程序/传输先决条件

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

Mailgun 驱动程序

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

shell

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

接下来，将应用程序的 config/mail.php 配置文件中的 default 选项设置为 mailgun。在配置应用程序的默认邮件程序后，验证您的 config/services.php 配置文件包含以下选项：

php

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
],

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

php

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

Postmark 驱动程序

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

shell

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

接下来，将应用程序的 config/mail.php 配置文件中的 default 选项设置为 postmark。在配置应用程序的默认邮件程序后，验证您的 config/services.php 配置文件包含以下选项：

php

'postmark' => [
    'token' => env('POSTMARK_TOKEN'),
],

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

php

'postmark' => [
    'transport' => 'postmark',
    'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
],

这样，您还可以设置多个具有不同消息流的 Postmark 邮件程序。

SES 驱动程序

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

shell

composer require aws/aws-sdk-php

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

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 键：

php

'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'),
],

如果您想定义其他选项，以便 Laravel 在发送电子邮件时传递给 AWS SDK 的 SendEmail 方法，可以在 ses 配置中定义一个 options 数组：

php

'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 数组，该数组引用邮件驱动程序应按顺序选择进行传递的顺序：

php

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

    // ...
],

定义故障转移邮件程序后，您应通过在应用程序的 mail 配置文件中将其名称指定为 default 配置键的值来将其设置为应用程序使用的默认邮件程序：

php

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

生成邮件类

在构建 Laravel 应用程序时，应用程序发送的每种类型的电子邮件都表示为一个“邮件类”。这些类存储在 app/Mail 目录中。如果您在应用程序中没有看到此目录，请不要担心，因为当您使用 make:mail Artisan 命令创建第一个邮件类时，它将为您生成：

shell

php artisan make:mail OrderShipped

编写邮件类

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

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

配置发件人

使用信封

首先，让我们探索配置电子邮件的发件人。换句话说，电子邮件将从谁那里发送。有两种方法可以配置发件人。首先，您可以在消息的信封上指定“发件人”地址：

php

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

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

如果您愿意，还可以指定 replyTo 地址：

php

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 配置文件中指定一个全局“发件人”地址。如果邮件类中未指定其他“发件人”地址，则将使用此地址：

php

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

此外，您可以在 config/mail.php 配置文件中定义一个全局“reply_to”地址：

php

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

配置视图

在邮件类的 content 方法中，您可以定义 view，即在渲染电子邮件内容时应使用哪个模板。由于每封电子邮件通常使用 Blade 模板来渲染其内容，因此在构建电子邮件的 HTML 时，您可以充分利用 Blade 模板引擎的强大功能和便利性：

php

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

您可能希望创建一个 resources/views/emails 目录来存放所有电子邮件模板；但是，您可以自由地将它们放置在 resources/views 目录中的任何位置。

纯文本电子邮件

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

php

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

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

php

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

视图数据

通过公共属性

通常，您会希望将一些数据传递给视图，以便在渲染电子邮件的 HTML 时使用。有两种方法可以将数据提供给视图。首先，定义在邮件类上的任何公共属性将自动提供给视图。因此，例如，您可以将数据传递到邮件类的构造函数中，并将该数据设置为类上定义的公共属性：

php

<?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;

    /**
     * 订单实例。
     *
     * @var \App\Models\Order
     */
    public $order;

    /**
     * 创建新消息实例。
     *
     * @param  \App\Models\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }

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

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

php

<div>
    价格: {{ $order->price }}
</div>

通过 `with` 参数

如果您想在将电子邮件的数据发送到模板之前自定义其格式，可以通过 Content 定义的 with 参数手动将数据传递给视图。通常，您仍然会通过邮件类的构造函数传递数据；但是，您应该将此数据设置为 protected 或 private 属性，以便数据不会自动提供给模板：

php

<?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;

    /**
     * 订单实例。
     *
     * @var \App\Models\Order
     */
    protected $order;

    /**
     * 创建新消息实例。
     *
     * @param  \App\Models\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }

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

一旦数据传递给 with 方法，它将自动在视图中可用，因此您可以像访问 Blade 模板中的任何其他数据一样访问它：

php

<div>
    价格: {{ $orderPrice }}
</div>

附件

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

php

use Illuminate\Mail\Mailables\Attachment;

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

在将文件附加到消息时，您还可以使用 as 和 withMime 方法指定显示名称和/或 MIME 类型：

php

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

从磁盘附加文件

如果您在文件系统磁盘上存储了文件，可以使用 fromStorage 附件方法将其附加到电子邮件：

php

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

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

php

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

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

php

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

原始数据附件

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

php

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

内联附件

将内联图像嵌入电子邮件通常很麻烦；然而，Laravel 提供了一种方便的方法来将图像附加到电子邮件中。要嵌入内联图像，请在电子邮件模板中使用 $message 变量上的 embed 方法。Laravel 会自动将 $message 变量提供给所有电子邮件模板，因此您无需手动传递它：

blade

<body>
    这是一个图像：

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

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

嵌入原始数据附件

如果您已经有一个原始图像数据字符串，并希望将其嵌入到电子邮件模板中，可以在 $message 变量上调用 embedData 方法。在调用 embedData 方法时，您需要提供一个应分配给嵌入图像的文件名：

blade

<body>
    这是来自原始数据的图像：

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

可附加对象

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

要开始，请在将附加到消息的对象上实现 Illuminate\Contracts\Mail\Attachable 接口。此接口要求您的类定义一个 toMailAttachment 方法，该方法返回一个 Illuminate\Mail\Attachment 实例：

php

<?php

namespace App\Models;

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

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

一旦定义了可附加对象，您可以在构建电子邮件消息时从 attachments 方法返回该对象的实例：

php

/**
 * 获取消息的附件。
 *
 * @return array
 */
public function attachments()
{
    return [$this->photo];
}

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

php

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

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

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

php

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

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

php

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

头信息

有时您可能需要将其他头信息附加到传出的消息。例如，您可能需要设置自定义 Message-Id 或其他任意文本头信息。

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

php

use Illuminate\Mail\Mailables\Headers;

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

标签和元数据

一些第三方电子邮件提供商（如 Mailgun 和 Postmark）支持消息“标签”和“元数据”，可用于分组和跟踪应用程序发送的电子邮件。您可以通过 Envelope 定义将标签和元数据添加到电子邮件消息中：

php

use Illuminate\Mail\Mailables\Envelope;

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

如果您的应用程序使用 Mailgun 驱动程序，可以查阅 Mailgun 的文档以获取有关标签和元数据的更多信息。同样，Postmark 文档也可以查阅以获取有关其对标签和元数据支持的更多信息。

如果您的应用程序使用 Amazon SES 发送电子邮件，您应该使用 metadata 方法将 SES "tags" 附加到消息中。

自定义 Symfony 消息

Laravel 的邮件功能由 Symfony Mailer 提供支持。Laravel 允许您注册自定义回调，这些回调将在发送消息之前与 Symfony Message 实例一起调用。这使您有机会在消息发送之前对其进行深度自定义。为此，请在 Envelope 定义上定义一个 using 参数：

php

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

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

Markdown 邮件类

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

生成 Markdown 邮件类

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

shell

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

然后，在邮件类的 content 方法中配置邮件类 Content 定义时，使用 markdown 参数而不是 view 参数：

php

use Illuminate\Mail\Mailables\Content;

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

编写 Markdown 消息

Markdown 邮件类使用 Blade 组件和 Markdown 语法的组合，使您能够轻松构建邮件消息，同时利用 Laravel 的预构建电子邮件 UI 组件：

blade

<x-mail::message>
# 订单已发货

您的订单已发货！

<x-mail::button :url="$url">
查看订单
</x-mail::button>

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

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

按钮组件

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

blade

<x-mail::button :url="$url" color="success">
查看订单
</x-mail::button>

面板组件

面板组件在背景颜色与消息其余部分略有不同的面板中渲染给定的文本块。这使您能够引起对给定文本块的注意：

blade

<x-mail::panel>
这是面板内容。
</x-mail::panel>

表格组件

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

blade

<x-mail::table>
| Laravel       | 表格         | 示例  |
| ------------- |:-------------:| --------:|
| 列 2 是      | 居中      | $10      |
| 列 3 是      | 右对齐 | $20      |
</x-mail::table>

自定义组件

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

shell

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 facade 上使用 to 方法。to 方法接受电子邮件地址、用户实例或用户集合。如果您传递一个对象或对象集合，邮件程序将自动使用其 email 和 name 属性来确定电子邮件的收件人，因此请确保这些属性在您的对象上可用。一旦指定了收件人，可以将邮件类实例传递给 send 方法：

php

<?php

namespace App\Http\Controllers;

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

class OrderShipmentController extends Controller
{
    /**
     * 发货给定订单。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function store(Request $request)
    {
        $order = Order::findOrFail($request->order_id);

        // 发货订单...

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

发送消息时，您不仅限于指定“to”收件人。您可以通过链接其各自的方法来设置“to”、“cc”和“bcc”收件人：

php

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

循环遍历收件人

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

php

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

通过特定邮件程序发送邮件

默认情况下，Laravel 将使用在应用程序的 mail 配置文件中配置为 default 的邮件程序发送电子邮件。然而，您可以使用 mailer 方法通过特定邮件程序配置发送消息：

php

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

队列邮件

队列邮件消息

由于发送电子邮件消息可能会对应用程序的响应时间产生负面影响，许多开发人员选择将电子邮件消息排队以进行后台发送。Laravel 使用其内置的统一队列 API 使这变得简单。要将邮件消息排队，请在指定消息的收件人后使用 Mail facade 上的 queue 方法：

php

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

此方法将自动处理将作业推送到队列中，以便消息在后台发送。您需要在使用此功能之前配置队列。

延迟消息队列

如果您希望延迟队列电子邮件消息的发送，可以使用 later 方法。作为其第一个参数，later 方法接受一个 DateTime 实例，指示消息应何时发送：

php

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

推送到特定队列

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

php

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

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

默认队列

如果您有希望始终排队的邮件类，可以在类上实现 ShouldQueue 合约。现在，即使在发送邮件时调用 send 方法，由于实现了合约，邮件类仍将排队：

php

use Illuminate\Contracts\Queue\ShouldQueue;

class OrderShipped extends Mailable implements ShouldQueue
{
    //
}

队列邮件类和数据库事务

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

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

php

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

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

php

<?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;

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

要了解有关解决这些问题的更多信息，请查看有关队列作业和数据库事务的文档。

渲染邮件类

有时您可能希望捕获邮件类的 HTML 内容而不发送它。为此，您可以调用邮件类的 render 方法。此方法将返回邮件类的评估 HTML 内容作为字符串：

php

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

$invoice = Invoice::find(1);

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

在浏览器中预览邮件类

在设计邮件类的模板时，可以方便地在浏览器中快速预览渲染的邮件类，就像典型的 Blade 模板一样。出于这个原因，Laravel 允许您直接从路由闭包或控制器返回任何邮件类。当返回邮件类时，它将在浏览器中渲染和显示，使您能够快速预览其设计，而无需将其发送到实际的电子邮件地址：

php

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

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

内联附件在浏览器中预览邮件类时不会渲染。要预览这些邮件类，您应该将它们发送到电子邮件测试应用程序，如 Mailpit 或 HELO。

本地化邮件类

Laravel 允许您以请求的当前语言环境以外的语言环境发送邮件类，并且即使邮件排队，也会记住此语言环境。

为此，Mail facade 提供了一个 locale 方法来设置所需的语言。应用程序将在评估邮件类的模板时切换到此语言环境，然后在评估完成后恢复到先前的语言环境：

php

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

用户首选语言环境

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

php

use Illuminate\Contracts\Translation\HasLocalePreference;

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

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

php

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

测试邮件类

Laravel 提供了多种方法来检查邮件类的结构。此外，Laravel 提供了几种方便的方法来测试邮件类是否包含您期望的内容。这些方法是：assertSeeInHtml、assertDontSeeInHtml、assertSeeInOrderInHtml、assertSeeInText、assertDontSeeInText、assertSeeInOrderInText、assertHasAttachment、assertHasAttachedData、assertHasAttachmentFromStorage 和 assertHasAttachmentFromStorageDisk。

正如您所期望的，“HTML” 断言断言邮件类的 HTML 版本包含给定字符串，而“文本” 断言断言邮件类的纯文本版本包含给定字符串：

php

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

public function test_mailable_content()
{
    $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->assertSeeInHtml('Invoice Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);

    $mailable->assertSeeInText($user->email);
    $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']);
}

测试邮件类发送

我们建议将邮件类的内容测试与断言给定邮件类已“发送”给特定用户的测试分开。要了解如何测试邮件类是否已发送，请查看有关 Mail fake 的文档。

邮件与本地开发

在开发发送电子邮件的应用程序时，您可能不希望实际将电子邮件发送到真实的电子邮件地址。Laravel 提供了几种方法来在本地开发期间“禁用”实际发送电子邮件。

日志驱动程序

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

HELO / Mailtrap / Mailpit

或者，您可以使用 HELO 或 Mailtrap 等服务和 smtp 驱动程序将电子邮件消息发送到“虚拟”邮箱，您可以在真实的电子邮件客户端中查看它们。这种方法的好处是可以在 Mailtrap 的消息查看器中实际检查最终电子邮件。

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

使用全局 `to` 地址

最后，您可以通过调用 Mail facade 提供的 alwaysTo 方法指定全局“to”地址。通常，此方法应在应用程序的服务提供者之一的 boot 方法中调用：

php

use Illuminate\Support\Facades\Mail;

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    if ($this->app->environment('local')) {
        Mail::alwaysTo('taylor@example.com');
    }
}

事件

在发送邮件消息的过程中，Laravel 会触发两个事件。在发送消息之前触发 MessageSending 事件，而在消息发送后触发 MessageSent 事件。请记住，这些事件是在邮件发送时触发的，而不是在邮件排队时触发的。您可以在 App\Providers\EventServiceProvider 服务提供者中注册此事件的事件监听器：

php

use App\Listeners\LogSendingMessage;
use App\Listeners\LogSentMessage;
use Illuminate\Mail\Events\MessageSending;
use Illuminate\Mail\Events\MessageSent;

/**
 * 应用程序的事件监听器映射。
 *
 * @var array
 */
protected $listen = [
    MessageSending::class => [
        LogSendingMessage::class,
    ],

    MessageSent::class => [
        LogSentMessage::class,
    ],
];

自定义传输

Laravel 包含多种邮件传输；然而，您可能希望编写自己的传输以通过 Laravel 不支持的其他服务传递电子邮件。要开始，请定义一个扩展 Symfony\Component\Mailer\Transport\AbstractTransport 类的类。然后，在传输上实现 doSend 和 __toString() 方法：

php

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

class MailchimpTransport extends AbstractTransport
{
    /**
     * Mailchimp API 客户端。
     *
     * @var \MailchimpTransactional\ApiClient
     */
    protected $client;

    /**
     * 创建新的 Mailchimp 传输实例。
     *
     * @param  \MailchimpTransactional\ApiClient  $client
     * @return void
     */
    public function __construct(ApiClient $client)
    {
        parent::__construct();
        
        $this->client = $client;
    }

    /**
     * {@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 ($email) {
                return ['email' => $email->getAddress(), 'type' => 'to'];
            })->all(),
            'subject' => $email->getSubject(),
            'text' => $email->getTextBody(),
        ]]);
    }

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

定义自定义传输后，可以通过 Mail facade 提供的 extend 方法注册它。通常，这应该在应用程序的 AppServiceProvider 服务提供者的 boot 方法中完成。一个 $config 参数将传递给提供给 extend 方法的闭包。此参数将包含在应用程序的 config/mail.php 配置文件中为邮件程序定义的配置数组：

php

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

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    Mail::extend('mailchimp', function (array $config = []) {
        return new MailchimpTransport(/* ... */);
    });
}

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

php

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

额外的 Symfony 传输

Laravel 支持一些现有的 Symfony 维护的邮件传输，如 Mailgun 和 Postmark。然而，您可能希望通过支持额外的 Symfony 维护的传输来扩展 Laravel。您可以通过 Composer 安装必要的 Symfony 邮件程序并将传输注册到 Laravel。例如，您可以安装并注册“Sendinblue” Symfony 邮件程序：

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

安装 Sendinblue 邮件程序包后，可以将 Sendinblue API 凭据的条目添加到应用程序的 services 配置文件中：

php

'sendinblue' => [
    'key' => 'your-api-key',
],

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

php

use Illuminate\Support\Facades\Mail;
use Symfony\Component\Mailer\Bridge\Sendinblue\Transport\SendinblueTransportFactory;
use Symfony\Component\Mailer\Transport\Dsn;

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    Mail::extend('sendinblue', function () {
        return (new SendinblueTransportFactory)->create(
            new Dsn(
                'sendinblue+api',
                'default',
                config('services.sendinblue.key')
            )
        );
    });
}

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

php

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

邮件 ​

介绍 ​

配置 ​

驱动程序/传输先决条件 ​

Mailgun 驱动程序 ​

Postmark 驱动程序 ​

SES 驱动程序 ​

故障转移配置 ​

生成邮件类 ​

编写邮件类 ​

配置发件人 ​

使用信封 ​

使用全局 from 地址 ​

配置视图 ​

纯文本电子邮件 ​

视图数据 ​

通过公共属性 ​

通过 with 参数 ​

附件 ​

从磁盘附加文件 ​

原始数据附件 ​

内联附件 ​

嵌入原始数据附件 ​

可附加对象 ​

头信息 ​

标签和元数据 ​

自定义 Symfony 消息 ​

Markdown 邮件类 ​

生成 Markdown 邮件类 ​

编写 Markdown 消息 ​

按钮组件 ​

面板组件 ​

表格组件 ​

自定义组件 ​

自定义 CSS ​

发送邮件 ​

循环遍历收件人 ​

通过特定邮件程序发送邮件 ​

队列邮件 ​

队列邮件消息 ​

延迟消息队列 ​

推送到特定队列 ​

默认队列 ​

队列邮件类和数据库事务 ​

渲染邮件类 ​

在浏览器中预览邮件类 ​

本地化邮件类 ​

用户首选语言环境 ​

测试邮件类 ​

测试邮件类发送 ​

邮件与本地开发 ​

日志驱动程序 ​

HELO / Mailtrap / Mailpit ​

使用全局 to 地址 ​

事件 ​

自定义传输 ​

额外的 Symfony 传输 ​

邮件

介绍

配置

驱动程序/传输先决条件

Mailgun 驱动程序

Postmark 驱动程序

SES 驱动程序

故障转移配置

生成邮件类

编写邮件类

配置发件人

使用信封

使用全局 `from` 地址

配置视图

纯文本电子邮件

视图数据

通过公共属性

通过 `with` 参数

附件

从磁盘附加文件

原始数据附件

内联附件

嵌入原始数据附件

可附加对象

头信息

标签和元数据

自定义 Symfony 消息

Markdown 邮件类

生成 Markdown 邮件类

编写 Markdown 消息

按钮组件

面板组件

表格组件

自定义组件

自定义 CSS

发送邮件

循环遍历收件人

通过特定邮件程序发送邮件

队列邮件

队列邮件消息

延迟消息队列

推送到特定队列

默认队列

队列邮件类和数据库事务

渲染邮件类

在浏览器中预览邮件类

本地化邮件类

用户首选语言环境

测试邮件类

测试邮件类发送

邮件与本地开发

日志驱动程序

HELO / Mailtrap / Mailpit

使用全局 `to` 地址

事件

自定义传输

额外的 Symfony 传输