Protocol Launcher 系列：Mail Assistant 轻松发送 HTML 邮件

在介绍了 Due 的联动后，今天，我们将介绍如何通过 Protocol Launcher 与 Mail Assistant 联动，让邮件发送变得更加简单。

作为开发者或内容创作者，你可能经常遇到这些场景：

• 在网页中提供一个"发送邮件"按钮，让用户快速联系你。
• 在内部平台点击链接，直接唤起邮件客户端并预填充收件人和内容。
• 生成 HTML 格式的邮件内容，并通过 Mail Assistant 发送精美的邮件。

现在，通过 Protocol Launcher ，你可以摆脱手动拼接复杂的 mail-assistant:// 协议链接，以类型安全的方式提升邮件发送效率。

---

Mail Assistant 与深度链接

Mail Assistant 是一款 Mac 辅助应用，可通过系统 Mail 应用发送 HTML 邮件。它提供了强大的深度链接支持，允许从网页或第三方应用直接触发邮件撰写和发送操作。

然而，手动拼接这些链接通常需要处理复杂的参数编码（如收件人地址、HTML 内容需要正确编码），且缺乏类型提示，极易出错。

---

核心能力：一键撰写与发送邮件

Protocol Launcher 为 Mail Assistant 专门提供了 protocol-launcher/mail-assistant 模块，支持以下核心功能：

1. 完整收件人支持：支持 TO、CC、BCC 字段，可指定多个收件人。
2. HTML 邮件内容：支持发送 HTML 格式的邮件内容，让邮件更加精美。
3. x-callback-url 支持：支持成功、取消、错误回调，方便集成到复杂工作流。
4. 自动处理协议逻辑：内部自动处理参数编码规则，确保链接 100% 可用。

---

快速上手

首先，确保你的项目中已安装：

npm install protocol-launcher

在代码中你可以根据场景选择两种导入方式：

• 按需加载（通过子路径导入），支持 Tree Shaking，体积更小；
• 全量导入（从根包导入），写法更简单，但会引入所有已支持应用的逻辑。

// ✅ 推荐：按需加载 Mail Assistant 模块
import { sendMail } from 'protocol-launcher/mail-assistant'

// 也可以从根包导入，但会包含所有应用模块
// import { mailAssistant } from 'protocol-launcher'

场景一：快速发送邮件 (sendMail)

这是最常用的功能。你可以引导用户直接撰写并发送邮件：

import { sendMail } from 'protocol-launcher/mail-assistant'

const url = sendMail({
  to: 'john@example.com',
  cc: 'jane@example.com',
  subject: 'Meeting Notes',
  body: '<h1>Meeting Notes</h1><p>Here are the notes...</p>',
  html: true,
})

场景二：支持多个收件人

你可以指定多个收件人，使用逗号分隔：

import { sendMail } from 'protocol-launcher/mail-assistant'

const url = sendMail({
  to: 'John Doe <john@example.com>, Jane Smith <jane@example.com>',
  subject: 'Hello',
  body: 'Hi there!',
})

场景三：完整的邮件参数

使用所有可用参数，包括 BCC、发件人和回调 URL：

import { sendMail } from 'protocol-launcher/mail-assistant'

const url = sendMail({
  to: 'john@example.com',
  cc: 'jane@example.com',
  bcc: 'secret@example.com',
  from: 'me@example.com',
  subject: 'Complete Email',
  body: '<h1>HTML Content</h1>',
  html: true,
  xSuccess: 'https://example.com/success',
  xCancel: 'https://example.com/cancel',
  xError: 'https://example.com/error',
})

---

参数说明

sendMail 函数接受以下参数：

参数	类型	必填	说明
to	string	否	收件人列表，逗号分隔，支持 "姓名 <邮箱>" 格式
cc	string	否	抄送收件人列表，格式同 to
bcc	string	否	密送收件人列表，格式同 to
subject	string	否	邮件主题
body	string	否	邮件正文内容
from	string	否	发件人地址，需匹配 Mail.app 中配置的地址
html	boolean	否	是否为 HTML 格式，默认为 false
xSuccess	string	否	成功回调 URL（x-callback-url 标准）
xCancel	string	否	取消回调 URL（x-callback-url 标准）
xError	string	否	错误回调 URL（x-callback-url 标准）

---

为什么选择 Protocol Launcher？

1. 自动编码与 Unicode 支持 ：Mail Assistant 的协议对参数编码有严格要求。库内部会自动处理所有的转义逻辑，确保生成的 URL 在唤起应用时绝不乱码。
2. 类型安全与参数提示：TypeScript 的智能补全会确保你提供了正确的参数，并提醒你所有可用选项。
3. 一致的用户体验：通过封装复杂的协议逻辑，你可以专注于业务功能的实现，而不用担心不同操作系统下协议触发的细微差异。
4. 极致的按需加载 (Tree Shaking) ：采用了模块化设计，支持按需加载以最小化包体积：
   • 推荐方式 ：使用子路径导入（如 import { sendMail } from 'protocol-launcher/mail-assistant'），这样构建工具只会打包相关的代码。
   • 全量方式 ：也可以从根包导入（如 import { mailAssistant } from 'protocol-launcher'），建议生产环境始终使用按需加载。
5. x-callback-url 标准支持：完整支持 x-callback-url 标准，方便集成到自动化工作流中。

---

结语

通过 Protocol Launcher，你可以极大降低用户发送邮件的门槛。无论是在个人博客的联系页面，还是企业内部的邮件通知系统，它都是连接 Web 与本地邮件客户端最优雅的桥梁。

---

🔗 相关链接

• Protocol Launcher 官网：https://protocol-launcher.huayi-data.com/
• Mail Assistant 模块文档：Mail Assistant | Protocol Launcher