logto/packages/connector-smtp/README.md

# 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

SMTP is a transmission protocol that is not exclusive to some specific email service providers but can work with all providers.

We are now offering guides on how to use the SMTP connector to send emails following providers for your better understanding:
- _Gmail_ is the most popular email service vendor worldwide.
- _Aliyun direct mail_ and _SendGrid mail_. Some of you might be familiar with these two email service providers because Logto Team provided corresponding connectors; you will likely have a general idea of them.

We hope you can figure out all other email vendors' setups with the following examples :rocket:

### Set up for Gmail use

You can get a new Gmail account at [Gmail](https://mail.google.com/), or you can use an existing account if you have one.

A [Gmail official post](https://support.google.com/a/answer/176600) shows how to determine required properties' values to operate Gmail via an SMTP connector.

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

```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"
        }
    ]
}
```

### Integrate with SendGrid SMTP API

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).

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:

```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"
        }
    ]
}
```

### Configure with Aliyun direct mail account

Sign in to the [Aliyun website](https://cn.aliyun.com/). Register a new account if you don't have one.

Follow the [Send emails using SMTP guide](https://www.alibabacloud.com/help/en/directmail/latest/send-emails-using-smtp) and finish those 'tasks' to get those required settings and information.

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.

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

```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"
        }
    ]
}
```

> ℹ️ **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 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.

### 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       |
|-----------|------------|
| host      | string     |
| port      | string     |
| username  | string     |
| password  | string     |
| fromEmail | string     |
| templates | Template[] |

| Template Properties | Type        | Enum values                      |
|---------------------|-------------|----------------------------------|
| subject             | string      | N/A                              |
| content             | string      | N/A                              |
| usageType           | enum string | 'Register' \| 'SignIn' \| 'Test' |
| contentType         | enum string | 'text/plain' \| 'text/html'      |

## References

- [Gmail - Send email from a printer, scanner, or app](https://support.google.com/a/answer/176600)
- [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)