使用 SendGrid Email 设置电子邮件验证

Logto 官方的 SendGrid 电子邮件服务连接器。

提示:

本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。

开始使用

SendGrid（即 Twilio SendGrid）是一个用于事务性和营销电子邮件的客户通信平台。我们可以使用其电子邮件发送功能来发送验证码。

注册 SendGrid 账户

在 SendGrid 官网 创建一个新账户。如果你已经有账户，可以跳过此步骤。

验证发件人

前往 SendGrid 控制台页面，并使用你的 SendGrid 账户登录。

发件人表示我们发送验证码邮件时所用的地址。为了通过 SendGrid 邮件服务器发送邮件，你需要至少验证一个发件人。

从 SendGrid 控制台页面 开始，在侧边栏进入 "Settings" -> "Sender Authentication"。

推荐使用域名认证（Domain Authentication），但不是强制要求。你可以点击 "Authenticate Your Domain" 卡片中的 "Get started"，并按照后续引导将发件人与 SendGrid 关联并验证。

点击面板中的 "Verify a Single Sender" 按钮后，你会看到一个需要填写关键信息的表单，用于创建发件人。按照引导填写所有字段，然后点击 "Create" 按钮。

单个发件人创建后，一封带有验证链接的邮件会发送到你的发件人邮箱。前往邮箱，找到验证邮件，并点击邮件中的链接完成单个发件人的验证。现在你可以使用刚刚验证的发件人通过 SendGrid 连接器发送邮件了。

创建 API 密钥

从 SendGrid 控制台页面 开始，在侧边栏进入 "Settings" -> "API Keys"。

在 API Keys 页面右上角点击 "Create API Key"。输入 API 密钥名称，并根据你的使用场景自定义 "API Key Permission"。在使用该 API 密钥发送邮件前，需为其分配全局 Full Access 或对 Mail Send 拥有全部权限的 Restricted Access。

完成 Create API Key 流程后，API 密钥会在屏幕上展示。你应将该 API 密钥妥善保存，因为这是唯一一次可以看到它的机会。

配置你的连接器

在 apiKey 字段填写在“创建 API 密钥”环节生成的 API Key。

在 fromEmail 和 fromName 字段填写发件人的 From Address 和 Nickname。你可以在 "Sender Management" 页面 找到发件人详情。fromName 为可选项，可以不填写。

你可以为不同场景添加多个 SendGrid 邮件连接器模板。以下是添加单个模板的示例：

• 填写 subject 字段，作为邮件标题。
• 在 content 字段填写任意字符串内容。不要忘记保留 {{code}} 占位符，用于随机验证码。
• usageType 字段根据不同场景填写 Register、SignIn、ForgotPassword、Generic。
• type 字段根据内容类型填写 text/plain 或 text/html。

为了支持完整的用户流程，usageType 为 Register、SignIn、ForgotPassword 和 Generic 的模板都是必需的。

以下是 SendGrid 连接器模板 JSON 示例。

[
  {
    "subject": "<register-template-subject>",
    "content": "<Logto: Your verification code is {{code}}. (register template)>",
    "usageType": "Register",
    "type": "text/plain",
  },
  {
    "subject": "<sign-in-template-subject>",
    "content": "<Logto: Your verification code is {{code}}. (sign-in template)>",
    "usageType": "SignIn",
    "type": "text/plain",
  },
  {
    "subject": "<forgot-password-template-subject>",
    "content": "<Logto: Your verification code is {{code}}. (forgot-password template)>",
    "usageType": "ForgotPassword",
    "type": "text/plain",
  },
  {
    "subject": "<generic-template-subject>",
    "content": "<Logto: Your verification code is {{code}}. (generic template)>",
    "usageType": "Generic",
    "type": "text/plain",
  },
]

测试 SendGrid 邮件连接器

你可以输入一个邮箱地址并点击“发送”，在“保存并完成”前测试设置是否生效。

就是这样。别忘了 在注册和登录中启用连接器。

配置类型

名称	类型
apiKey	string
fromEmail	string
fromName	string (可选)
templates	Template[]

模板属性	类型	枚举值
subject	string	N/A
content	string	N/A
usageType	enum string	'Register' / 'SignIn' / 'ForgotPassword' / 'Generic'
type	enum string	'text/plain' / 'text/html'