From a78427e470f6c9dbfe3b427e6c603b8fc33687fb Mon Sep 17 00:00:00 2001 From: Darcy Ye Date: Tue, 12 Jul 2022 15:57:26 +0800 Subject: [PATCH] docs(connector): smtp readme zh-CN (#1514) --- packages/connector-smtp/README.md | 194 +++++++++++++++++- .../connector-smtp/docs/config-template.json | 8 +- 2 files changed, 187 insertions(+), 15 deletions(-) diff --git a/packages/connector-smtp/README.md b/packages/connector-smtp/README.md index 9f599efd4..b7c40d82f 100644 --- 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": 587, // your SMTP port "username": "", "password": "", "fromEmail": "", @@ -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": "", "fromEmail": "", @@ -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": "", - "port": , + "port": 1234, // your SMTP port "username": "", "password": "", "fromEmail": "", @@ -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": "", + "password": "", + "fromEmail": "", + "templates": [ + { + "subject": "", + "content": "", + "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": "", + "fromEmail": "", + "templates": [ + { + "subject": "", + "content": "", + "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": "", + "port": 1234, // your SMTP port + "username": "", + "password": "", + "fromEmail": "", + "templates": [ + { + "subject": "", + "content": "", + "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) diff --git a/packages/connector-smtp/docs/config-template.json b/packages/connector-smtp/docs/config-template.json index 6346584a6..bd25830dd 100644 --- 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" }