docs(connector): smtp readme zh-CN (#1514)

2025-01-20 21:32:31 -05:00 · 2022-07-12 15:57:26 +08:00 · 2022-07-12 15:57:26 +08:00 · a78427e470
commit a78427e470
parent b4c202275b
2 changed files with 187 additions and 15 deletions
--- a/packages/connector-smtp/README.md
+++ b/packages/connector-smtp/README.md
@ -1,5 +1,32 @@
 # SMTP connector

+The official Logto connector for SMTP.
+
+SMTP Logto 官方连接器 [中文文档](#smtp-连接器)
+
+**Table of contents**
+
+- [SMTP connector](#smtp-connector)
+  - [Get started](#get-started)
+  - [Set up SMTP connector](#set-up-smtp-connector)
+    - [Set up for Gmail use](#set-up-for-gmail-use)
+    - [Integrate with SendGrid SMTP API](#integrate-with-sendgrid-smtp-api)
+    - [Configure with Aliyun direct mail account](#configure-with-aliyun-direct-mail-account)
+    - [Test SMTP connector](#test-smtp-connector)
+    - [Config types](#config-types)
+  - [References](#references)
+- [SMTP 连接器](#smtp-连接器)
+  - [开始上手](#开始上手)
+  - [设置 SMTP 连接器](#设置-smtp-连接器)
+    - [SMTP 连接器对接 Gmail 的配置](#smtp-连接器对接-gmail-的配置)
+    - [集成 SendGrid SMTP API](#集成-sendgrid-smtp-api)
+    - [针对阿里云邮件帐号的配置](#针对阿里云邮件帐号的配置)
+    - [测试 SMTP 连接器](#测试-smtp-连接器)
+    - [配置类型](#配置类型)
+  - [参考](#参考)
+
+## Get started
+
 The SMTP (Simple Mail Transfer Protocol) is an internet standard communication protocol for electronic mail transmission. Mail servers and other message transfer agents use SMTP to send and receive messages.

 ## Set up SMTP connector
@ -20,10 +47,10 @@ A [Gmail official post](https://support.google.com/a/answer/176600) shows how to

 By following the post, your connector JSON should be like this:

-```json
+```jsonc
 {
    "host": "smtp.gmail.com",
-    "port": <port-number>,
+    "port": 587, // your SMTP port
    "username": "<your-gmail-address>",
    "password": "<password-to-previous-gmail-address>",
    "fromEmail": "<your-gmail-address>",
@ -42,16 +69,16 @@ By following the post, your connector JSON should be like this:

 Initially, we assume that you already have a SendGrid account. If not, create a new account at the [SendGrid website](https://app.sendgrid.com/).

-You can find a step-by-step guide on [Integrating with the SMTP API](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api).
+You can find a step-by-step guide on ["Integrating with the SMTP API"](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api).

-Developers can access _Verified senders' details_ on the [_Sender Management_ page](https://mc.sendgrid.com/senders).
+Developers can access _sender_ details on the ["Sender Management"](https://mc.sendgrid.com/senders).

 After going through the guide, your connector JSON should look like this:

-```json
+```jsonc
 {
    "host": "smtp.sendgrid.net",
-    "port": 587,
+    "port": 587, // your SMTP port
    "username": "apiKey",
    "password": "<api-key-with-at-least-mail-permission>",
    "fromEmail": "<email-address-of-a-verified-sender>",
@ -74,14 +101,14 @@ Follow the [Send emails using SMTP guide](https://www.alibabacloud.com/help/en/d

 You can go to [SMTP service address page](https://www.alibabacloud.com/help/en/directmail/latest/smtp-service-address) to choose a proper SMTP service address host and port number.

-To check _Sender Addresses_, you can find the entrance on the left-side navigation pane on [DirectMail console](https://dm.console.aliyun.com/). You should see `Sender address` and `SMTP Password` here.
+To check "Sender Addresses", you can find the entrance on the left-side navigation pane on [DirectMail console](https://dm.console.aliyun.com/). You should see `Sender address` and `SMTP Password` here.

 After going through the guide, your connector JSON should look like this:

-```json
+```jsonc
 {
    "host": "<SMTP-service-address>",
-    "port": <port-number>,
+    "port": 1234, // your SMTP port
    "username": "<email-address-of-chosen-sender-address>",
    "password": "<api-key-with-at-least-mail-permission>",
    "fromEmail": "<email-address-of-a-verified-sender-should-be-the-same-as-`username`>",
@ -99,9 +126,16 @@ After going through the guide, your connector JSON should look like this:
 > ℹ️ **Note**
 >
 > Only one sample template is provided in the previous cases to keep things simple. You should add more templates for other use cases.
-> You should change values wrapped with "<" and ">" according to your SendGrid or Aliyun account settings and choose to keep other fields w/o "<" and ">".
+> You should change values wrapped with "<" and ">" according to your Gmail, SendGrid or Aliyun account settings and choose to keep other fields w/o "<" and ">".
+> Add `{{code}}` as a placeholder in templates' content to show random passcode in sending emails.

-#### Config types
+### Test SMTP connector
+
+You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
+
+That's it. Don't forget to [Enable connector in sign-in experience](https://docs.logto.io/docs/tutorials/get-started/enable-passcode-sign-in/#enable-connector-in-sign-in-experience).
+
+### Config types

 | Name      | Type       |
 |-----------|------------|
@ -125,3 +159,141 @@ After going through the guide, your connector JSON should look like this:
 - [SendGrid - Integrating with the SMTP API](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api)
 - [Aliyun Direct Mail - Send emails using SMTP](https://www.alibabacloud.com/help/en/directmail/latest/send-emails-using-smtp)
 - [Aliyun Direct Mail - SMTP Reference](https://www.alibabacloud.com/help/en/directmail/latest/smtp-reference)
+
+# SMTP 连接器
+
+## 开始上手
+
+SMTP（简单邮件传输协议）是一种在网络中传输电子邮件的标准通信协议。邮件服务器和其他信息传输代理用 SMTP 来收发邮件。
+
+## 设置 SMTP 连接器
+
+SMTP 是一个所有邮件服务提供商通用的传输协议。
+
+我们提供了 SMTP 连接器用于以下几种邮件服务提供商的使用指南，帮助你有更好的理解：
+
+- _Gmail_ 是世界上最受欢迎的邮件服务商
+- _阿里云邮件_ 和 _SendGrid_（Logto 提供了对接这两个服务商的连接器，因此你们也许会对这两个服务商比较熟悉并有一个基本概念）
+
+希望在浏览了以下几个案例之后，你能够处理大部分其他邮件服务的配置 :rocket:
+
+### SMTP 连接器对接 Gmail 的配置
+
+你可以使用已有的 Gmail 邮箱或者通过 [Gmail](https://mail.google.com/) 创建一个新的账号。
+
+前往这篇 [Gmail 官方帮助文档](https://support.google.com/a/answer/176600)，查看如何得到 SMTP 连接器调用 Gmail 服务所 **必须的** 属性。
+
+根据文档的描述，并结合 Logto 的实现，你的 SMTP 连接器配置 JSON 应该如下：
+
+```jsonc
+{
+    "host": "smtp.gmail.com",
+    "port": 587, // your SMTP port
+    "username": "<your-gmail-address>",
+    "password": "<password-to-previous-gmail-address>",
+    "fromEmail": "<your-gmail-address>",
+    "templates": [
+        {
+            "subject": "<register-template-subject>",
+            "content": "<Logto: Your passcode is {{code}}. (regitser template)>",
+            "usageType": "Register",
+            "contentType": "text/plain"
+        }
+    ]
+}
+```
+
+### 集成 SendGrid SMTP API
+
+我们假设你已经有了 SendGrid 账号，否则就在 [SendGrid](https://app.sendgrid.com/) 创建新账号。
+
+在 [集成 SendGrid SMTP API](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api) 可以找到详尽的集成指南。
+
+开发者可以前往 [_Sender Management_](https://mc.sendgrid.com/senders) 以访问相应的 _sender_ 详情。
+
+跟随配置指南，你的连接器配置 JSON 应该如下：
+
+```jsonc
+{
+    "host": "smtp.sendgrid.net",
+    "port": 587, // your SMTP port
+    "username": "apiKey",
+    "password": "<api-key-with-at-least-mail-permission>",
+    "fromEmail": "<email-address-of-a-verified-sender>",
+    "templates": [
+        {
+            "subject": "<register-template-subject>",
+            "content": "<Logto: Your passcode is {{code}}. (regitser template)>",
+            "usageType": "Register",
+            "contentType": "text/plain"
+        }
+    ]
+}
+```
+
+### 针对阿里云邮件帐号的配置
+
+登录 [阿里云](https://cn.aliyun.com/) 并创建新账号。
+
+跟随 [使用 SMTP 发送邮件](https://www.alibabacloud.com/help/zh/directmail/latest/send-emails-using-smtp)，完成里面的各个步骤以获取需要的配置和信息。
+
+前往 [SMTP 服务地址](https://www.alibabacloud.com/help/zh/directmail/latest/smtp-service-address) 并选择合适的 SMTP 服务地址与端口号。
+
+在 [阿里云工作台](https://dm.console.aliyun.com/) 侧边栏中找到「发信地址」，在这里你可以找到 `Sender address` 和 `SMTP Password`。
+
+跟随配置指南，你的连接器配置 JSON 应该如下：
+
+```jsonc
+{
+    "host": "<SMTP-service-address>",
+    "port": 1234, // your SMTP port
+    "username": "<email-address-of-chosen-sender-address>",
+    "password": "<api-key-with-at-least-mail-permission>",
+    "fromEmail": "<email-address-of-a-verified-sender-should-be-the-same-as-`username`>",
+    "templates": [
+        {
+            "subject": "<register-template-subject>",
+            "content": "<Logto: Your passcode is {{code}}. (regitser template)>",
+            "usageType": "Register",
+            "contentType": "text/plain"
+        }
+    ]
+}
+```
+
+> ℹ️ **注意**
+>
+> 简单起见，前面提及的所有例子都只给出了一个模板样例。如果要满足其他更多场景的使用，你需要自己添加更多模板。
+> 用尖括号 "<" 和 ">" 包起来的值需要根据 Google，SendGrid 或阿里云账号来重新填写，其他的设置可以按需进行调整。
+> 在模板的内容中加上 `{{code}}` 的占位符以在所发送邮件正文的相同位置插入随机验证码。
+
+### 测试 SMTP 连接器
+
+你可以在「保存并完成」之前输入一个手机号码并点按「发送」来测试配置是否可以正常工作。
+
+大功告成！快去 [启用短信或邮件验证码登录](https://docs.logto.io/zh-cn/docs/tutorials/get-started/enable-passcode-sign-in/#%E5%9C%A8%E7%99%BB%E5%BD%95%E4%BD%93%E9%AA%8C%E4%B8%AD%E5%90%AF%E7%94%A8%E8%BF%9E%E6%8E%A5%E5%99%A8) 吧。
+
+### 配置类型
+
+| 名称      | 类型        |
+|-----------|------------|
+| host      | string     |
+| port      | string     |
+| username  | string     |
+| password  | string     |
+| fromEmail | string     |
+| templates | Template[] |
+
+| 模板属性     | 类型         | 枚举值                            |
+|-------------|-------------|----------------------------------|
+| subject     | string      | N/A                              |
+| content     | string      | N/A                              |
+| usageType   | enum string | 'Register' \| 'SignIn' \| 'Test' |
+| contentType | enum string | 'text/plain' \| 'text/html'      |
+
+## 参考
+
+- [Gmail - 从打印机、扫描仪或应用发送电子邮件](https://support.google.com/a/answer/176600?hl=zh-Hans)
+- [SendGrid - Integrating with the SMTP API](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api)
+- [阿里云邮件推送 - 使用 SMTP 发送邮件](https://www.alibabacloud.com/help/zh/directmail/latest/send-emails-using-smtp)
+- [阿里云邮件推送 - SMTP 参考](https://www.alibabacloud.com/help/zh/directmail/latest/smtp-reference)
--- a/packages/connector-smtp/docs/config-template.json
+++ b/packages/connector-smtp/docs/config-template.json
@ -7,25 +7,25 @@
  "templates": [
      {
          "contentType": "text/plain",
-          "content": "This is for testing purposes only.",
+          "content": "This is for testing purposes only. Your verification code is {{code}}.",
          "subject": "Logto Test with SMTP",
          "usageType": "Test"
      },
      {
          "contentType": "text/plain",
-          "content": "This is for sign-in purposes only.",
+          "content": "This is for sign-in purposes only. Your verification code is {{code}}.",
          "subject": "Logto Sign In with SMTP",
          "usageType": "SignIn"
      },
      {
          "contentType": "text/plain",
-          "content": "This is for register purposes only.",
+          "content": "This is for register purposes only. Your verification code is {{code}}.",
          "subject": "Logto Register with SMTP",
          "usageType": "Register"
      },
      {
          "contentType": "text/plain",
-          "content": "This is for forgot-password purposes only.",
+          "content": "This is for forgot-password purposes only. Your verification code is {{code}}.",
          "subject": "Logto Forgot Password with SMTP",
          "usageType": "ForgotPassword"
      }