本文描述了如何构建邮件内容，包括使用布局和局部文件，以及发送这些内容的方法。基本的 Twig 标签和表达式在邮件内容中受支持。Markdown 语法也受支持，详见关于在 Markdown 中使用 HTML的章节。
邮件消息可以在 October CMS 中使用邮件视图或邮件模板发送。邮件视图由应用程序或插件在文件系统的 /views 目录中提供。而邮件模板则通过后端面板经由 Settings → Mail Templates 进行管理。
可选地，邮件视图可以在 插件注册文件 中使用 registerMailTemplates 方法注册。这会自动播种一个邮件模板，允许它们使用后端面板进行自定义。
您可以通过后端面板的 设置 → 邮件模板 来创建存储在数据库中的邮件模板。赋予模板的 代码 是一个唯一标识符，一旦创建就不能更改。
例如，如果您使用代码my-template创建了一个模板您可以使用以下 PHP 代码发送它：
Mail::send('my-template', $data, function($message) {
// ...
});如果邮件模板在系统中不存在，此代码将尝试在文件系统中查找具有相同代码的邮件视图。
:::
邮件布局可以通过选择 设置 → 邮件模板 并点击 布局 选项卡来创建。它们的功能与 CMS 布局类似，包含邮件消息的骨架。邮件视图和模板支持使用邮件布局。
默认情况下，October CMS 附带两个默认邮件布局。
| Layout | Code | Description |
|---|---|---|
| Default | default | Used for public facing, frontend mail. |
| System | system | Used for internal, backend mail. |
邮件视图位于文件系统，所使用的代码代表着视图文件的路径。例如，使用代码 author.plugin::mail.message 发送邮件将会使用以下文件中的内容。
├── plugins
| └── author ← "author" 片段
| └── myplugin ← "插件" 片段
| └── views
| └── mail ← "邮件" 片段
| └── message.htm ← "消息" 片段
邮件视图文件中的内容最多可以包含 3 个部分：**配置**, **纯文本**, 和 **HTML 标记**。各部分之间使用 == 序列分隔。例如：
subject = "Your product has been added to October CMS project"Hi {{ name }},
Good news! User {{ user }} just added your product "{{ product }}" to a project.
This message was sent using no formatting (plain text)<p>Hi {{ name }},</p>
<p>
<strong>Good news!</strong>
User {{ user }} just added your product "{{ product }}" to a project.
</p>
<p>This email was sent using formatting (HTML)</p>纯文本部分是可选的，一个视图可以只包含配置和HTML标记部分。标记语法也作为一种替代语法受支持。
layout = "default"
subject = "Your product has been added to October CMS project"Hi {{ name }},
**Good news!** User {{ user }} just added your product "{{ product }}" to a project.配置部分设置邮件视图属性.
支持以下配置属性.
| Property | Description |
|---|---|
| subject | the mail message subject, required. |
| layout | the mail layout code or view, optional. Default value is default. |
该代码值在后端面板中将与邮件视图路径相同。例如，
author.plugin:mail.message。
邮件视图可以注册为在后端面板中创建的默认模板。模板通过覆盖 插件注册文件 的 registerMailTemplates 方法来注册。模板可以实现部分和布局，类似于 CMS 主题，它们分别通过 registerMailLayouts 和 registerMailPartials 注册。
public function registerMailTemplates()
{
return [
// ...Templates defined here
];
}
public function registerMailLayouts()
{
return [
// ...Layouts defined here
];
}
public function registerMailPartials()
{
return [
// ...Partials defined here
];
}在后端面板中，当生成的模板首次保存时，定制内容将在为指定代码发送邮件时被使用。在这种情况下，注册的邮件视图可被视为默认视图或备用视图。
注册数组中的templates键用于将视图注册为邮件模板。该方法应该返回一个数组，其中键是模板代码，值是视图路径的名称。模板代码用于引用该模板。
public function registerMailTemplates()
{
return [
'rainlab.user:activate' => 'rainlab.user::mail.activate',
'rainlab.user:restore' => 'rainlab.user::mail.restore',
];
}发送消息使用模板代码，例如。
Mail::send('rainlab.user:activate', ...);registerMailLayouts 方法重写用于注册布局，每个布局都需要一个唯一的 code 来标识它，以及内容的默认视图文件。
public function registerMailLayouts()
{
return [
'marketing' => 'acme.blog::layouts.marketing',
'notification' => 'acme.blog::layouts.notification',
];
}布局现在可以在模板中引用使用 code 值。
layout = "marketing"Page contents...类似于布局，邮件局部视图可以通过 registerMailPartials 方法覆盖进行注册，并且每个局部视图都需要一个唯一的 code 来标识它，以及内容的默认视图文件。
public function registerMailPartials()
{
return [
'tracking' => 'acme.blog::partials.tracking',
'promotion' => 'acme.blog::partials.promotion',
];
}该局部现在可以在模板中引用，使用 {% partial %} 标签和 code 值。
{% partial 'tracking' %}要引用基于文件的布局，您可以将视图代码传递给 layout 属性。例如，此邮件视图引用了布局 acme.blog::mail.custom-layout。
layout = "acme.blog::mail.custom-layout"
subject = "Your product has been added to October CMS project"
==
...使用上述代码，它将尝试从路径 plugins/acme/blog/views/mail/custom-layout.htm 加载布局内容，并且这些内容是一个示例。
<html>
<body>
<h1>HTML Contents</h1>
<div>
{{ content|raw }}
</div>
</body>
</html>基于文件的布局内容无法在管理面板中编辑。
您可以使用 View::share 方法注册所有邮件模板全局可用的变量。
View::share('site_name', 'October CMS');这段代码可以在 插件注册文件 的 register 或 boot 方法中调用。 使用上述示例，变量 {{ site_name }} 将在所有邮件模板中可用。
要发送邮件，请在 Mail 门面上使用 send 方法，它接受三个参数。第一个参数是一个唯一的邮件代码，用于定位邮件视图或邮件模板。第二个参数是您希望传递给视图的数据数组。第三个参数是一个 Closure 回调，它接收一个消息实例，允许您自定义邮件消息的收件人、主题和其他方面。
// These variables are available inside the message as Twig
$vars = ['name' => 'Joe', 'user' => 'Mary'];
Mail::send('acme.blog:message', $vars, function($message) {
$message->to('admin@domain.tld', 'Admin Person');
$message->subject('This is a reminder');
});由于我们在上面的示例中传递了一个包含 name 键的数组，我们可以在电子邮件视图中显示该值，使用以下 Twig 标记。
{{ name }}您应避免在消息中传递一个
message变量，此变量始终会被传递并允许内联嵌入附件。
October CMS 也包含一个名为 sendTo 的替代方法，能够简化邮件发送。
// Send to address using no name
Mail::sendTo('admin@domain.tld', 'acme.blog:message', $params);
// Send using an object's properties
Mail::sendTo($user, 'acme.blog:message', $params);
// Send to multiple addresses
Mail::sendTo(['admin@domain.tld' => 'Admin Person'], 'acme.blog:message', $params);
// Alternatively send a raw message without parameters
Mail::rawTo('admin@domain.tld', 'Hello friend');sendTo 中的第一个参数用于收件人可接受不同类型的值。
| Type | Description |
|---|---|
| String | a single recipient address, with no name defined. |
| Array | multiple recipients where the array key is the address and the value is the name. |
| Object | a single recipient object, where the email property is used for the address and the name is optionally used for the name. |
| Collection | a collection of recipient objects, as above. |
sendTo 的完整签名如下所示。
Mail::sendTo($recipient, $message, $params, $callback, $options);$recipient 的定义如上。$message 是模板名称或用于原始发送的消息内容。$params 在模板内部可用的变量数组。$callback 会带有一个参数被调用，消息构建器，正如 send 方法所描述的 (可选，默认为 null)。如果不是可调用值，则作为下一个 options 参数的替代品。$options 自定义发送选项以数组形式传递 (可选)以下自定义发送 $options 受支持。
| Option | Description |
|---|---|
| queue | specifies whether to queue the message or send it directly, optional. Default: false. |
| bcc | specifies whether to add recipients as Bcc or regular To addresses. Default: false. |
如前所述，传递给 send 方法的第三个参数是一个 Closure，允许您在电子邮件消息本身上指定各种选项。使用此 Closure，您可以指定消息的其他属性，例如抄送、密送等：
Mail::send('acme.blog:welcome', $vars, function($message) {
$message->from('us@example.tld', 'October');
$message->to('foo@example.tld')->cc('bar@example.tld');
});这是 $message 消息构建器实例上可用方法的列表。
$message->from($address, $name = null);
$message->sender($address, $name = null);
$message->to($address, $name = null);
$message->cc($address, $name = null);
$message->bcc($address, $name = null);
$message->replyTo($address, $name = null);
$message->subject($subject);
$message->priority($level);
$message->attach($pathToFile, array $options = []);
// Attach a file from a raw $data string...
$message->attachData($data, $name, array $options = []);默认情况下，提供给 send 方法的视图被假定包含一个邮件视图，您可以在其中指定除了 HTML 视图之外要发送的纯文本视图。
Mail::send('acme.blog:message', $data, $callback);或者，如果您只需要发送纯文本电子邮件，您可以使用数组中的 text 键来指定：
Mail::send(['text' => 'acme.blog:text'], $data, $callback);你可以使用 raw 方法，如果你希望直接通过电子邮件发送原始字符串。此内容将由 Markdown 解析。
Mail::raw('Text to e-mail', function ($message) {
//
});此外，此字符串将由 Twig 解析，如果您希望将变量传递给此环境，请改用 send 方法，并将内容作为 raw 键传入。
Mail::send(['raw' => 'Text to email'], $vars, function ($message) {
//
});如果您传递的数组包含 text 或 html 键，这将是一个明确的发送邮件请求。不使用布局或 Markdown 解析。
Mail::raw([
'text' => 'This is plain text',
'html' => '<strong>This is HTML</strong>'
], function ($message) {
//
});要向电子邮件添加附件，请使用传递给你的闭包的 $message 对象上的 attach 方法。attach 方法接受文件的完整路径作为其第一个参数：
Mail::send('acme.blog:welcome', $data, function ($message) {
//
$message->attach($pathToFile);
});当您将文件附加到消息时，您还可以通过将 array 作为第二个参数传递给 attach 方法来指定显示名称和/或MIME类型：
$message->attach($pathToFile, ['as' => $display, 'mime' => $mime]);在您的电子邮件中嵌入内联图像通常很麻烦；然而，有一种便捷的方式可以将图像附加到您的电子邮件并检索相应的CID。要嵌入内联图像，请在您的电子邮件视图中，在 message 变量上使用 embed 方法。请记住，message 变量在您的所有邮件视图中都可用：
<body>
Here is an image:
<img src="{{ message.embed(pathToFile) }}">
</body>如果您计划使用排队邮件，请确保文件路径是绝对的。为此，您只需使用应用过滤器：
<body>
Here is an image:
{% set pathToFile = 'storage/app/media/path/to/file.jpg'|app %}
<img src="{{ message.embed(pathToFile) }}">
</body>如果您已有一个希望嵌入电子邮件的原始数据字符串，您可以在 message 变量上使用 embedData 方法：
<body>
Here is an image from raw data:
<img src="{{ message.embedData(data, name) }}">
</body>由于发送邮件消息可能会显著延长应用程序的响应时间，许多开发人员选择将消息排队以在后台发送。这通过使用内置的统一队列 API即可轻松实现。要将邮件消息排队，请使用 Mail facade 上的 queue 方法：
Mail::queue('acme.blog:welcome', $data, function ($message) {
//
});此方法将自动处理将作业推送到队列中以在后台发送邮件消息。当然，您需要先配置你的队列才能使用此功能。
如果您希望延迟队列中电子邮件消息的投递，您可以使用 later 方法。要开始，只需将您希望延迟发送消息的秒数作为第一个参数传递给该方法即可。
Mail::later(5, 'acme.blog:welcome', $data, function ($message) {
//
});如果您希望指定一个特定的队列用于推送消息，您可以使用 queueOn 和 laterOn 方法来完成：
Mail::queueOn('queue-name', 'acme.blog:welcome', $data, function ($message) {
//
});
Mail::laterOn('queue-name', 5, 'acme.blog:welcome', $data, function ($message) {
//
});