Skip to content

Commit 7449a1a

Browse files
charIeszhaocharIeszhao
authored
feat: generate social sms and email connector guides (#667)
* feat: script to pull readme * chore: add code annotations * chore: update content
1 parent b4d57f2 commit 7449a1a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+3716
-54
lines changed

‎docs/integrations/email/aliyun-dm/README.mdx

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
slug: /integrations/aliyun-dm
3+
sidebar_label: Aliyun Direct Mail
4+
sidebar_custom_props:
5+
description: Aliyun provides cloud computing services to online businesses.
6+
logoFilename: 'aliyun.svg'
7+
---
8+
9+
import GuideTip from '../../fragments/_guide-tip.mdx';
10+
11+
<GuideTip />
12+
13+
# Aliyun direct mail connector
14+
15+
The official Logto connector for Aliyun connector for direct mail service.
16+
17+
阿里云邮件推送服务 Logto 官方连接器 [中文文档](#阿里云邮件连接器)
18+
19+
**Table of contents**
20+
21+
- [Aliyun direct mail connector](#aliyun-direct-mail-connector)
22+
- [Get started](#get-started)
23+
- [Set up an email service in Aliyun DirectMail Console](#set-up-an-email-service-in-aliyun-directmail-console)
24+
- [Create an Aliyun account](#create-an-aliyun-account)
25+
- [Enable and configure Aliyun Direct Mail](#enable-and-configure-aliyun-direct-mail)
26+
- [Compose the connector JSON](#compose-the-connector-json)
27+
- [Test Aliyun DM connector](#test-aliyun-dm-connector)
28+
- [Config types](#config-types)
29+
- [阿里云邮件连接器](#阿里云邮件连接器)
30+
- [开始上手](#开始上手)
31+
- [在阿里云邮件服务控制台中配置一个邮件服务](#在阿里云邮件服务控制台中配置一个邮件服务)
32+
- [注册阿里云帐号](#注册阿里云帐号)
33+
- [启用并配置阿里云邮件服务](#启用并配置阿里云邮件服务)
34+
- [编写连接器的 JSON](#编写连接器的-json)
35+
- [测试阿里云邮件连接器](#测试阿里云邮件连接器)
36+
- [配置类型](#配置类型)
37+
38+
## Get started
39+
40+
Aliyun is a primary cloud service provider in Asia, offering many cloud services, including DM (direct mail). Aliyun DM Connector is a plugin provided by the Logto team to call the Aliyun DM service APIs, with the help of which Logto end-users can register and sign in to their Logto account via mail verification code (or in other words, verification code).
41+
42+
## Set up an email service in Aliyun DirectMail Console
43+
44+
> 💡 **Tip**
45+
>
46+
> You can skip some sections if you have already finished.
47+
48+
### Create an Aliyun account
49+
50+
Head to [Aliyun](https://aliyun.com/) and create your Aliyun account if you don't have one.
51+
52+
### Enable and configure Aliyun Direct Mail
53+
54+
Go to the [DM service console page](https://www.aliyun.com/product/directmail) and sign in. Enable the Direct Mail service by clicking the "Apply to enable" (申请开通) button on the top left of the page and begin the configuration process.
55+
56+
Starting from the [DM admin console page](https://dm.console.aliyun.com/), you should:
57+
58+
1. Go to "Email Domains" (发信域名) from the sidebar and add "New Domain" (新建域名) following the instructions.
59+
2. Customize "Sender Addresses" (发信地址) and "Email Tags" (邮件标签) respectively.
60+
61+
After finishing setup, there are two different ways to test:
62+
63+
- Go to the [DirectMail Overview page](https://dm.console.aliyun.com/), find "Operation Guide" (操作引导) at the bottom of the page, and click on "Send Emails" (发送邮件). You will find all the different kinds of testing methods.
64+
- Follow the path "Send Emails" (发送邮件) -> "Email Tasks" (发送邮件) in the sidebar to create a testing task.
65+
66+
## Compose the connector JSON
67+
68+
1. From the [DM admin console page](https://dm.console.aliyun.com/), hover on your avatar in the top right corner and go to "AccessKey Management" (AccessKey 管理), and click "Create AccessKey" (创建 AccessKey). You will get an "AccessKey ID" and "AccessKey Secret" pair after finishing security verification. Please keep them properly.
69+
2. Go to the "Sender Addresses" (发信地址) or "Email Tags" (邮件标签) tab you just visited from the [DM admin console page](https://dm.console.aliyun.com/), you can find _Sender Address_ or _Email Tag_ easily.
70+
3. Fill out the Aliyun DM Connector settings:
71+
- Fill out the `accessKeyId` and `accessKeySecret` fields with access key pairs you've got from step 1.
72+
- Fill out the `accountName` and `fromAlias` field with "Sender Address" and "Email Tag" which were found in step 2. All templates will share this signature name. (You can leave `fromAlias` blank as it is OPTIONAL.)
73+
- You can add multiple DM connector templates for different cases. Here is an example of adding a single template:
74+
- Fill out the `subject` field, which will work as title of the sending email.
75+
- Fill out the `content` field with arbitrary string-type contents. Do not forget to leave `{{code}}` placeholder for random verification code.
76+
- Fill out `usageType` field with either `Register`, `SignIn`, `ForgotPassword` or `Generic` for different use cases. (`usageType` is a Logto property to identify the proper use case.) In order to enable full user flows, templates with usageType `Register`, `SignIn`, `ForgotPassword` and `Generic` are required.
77+
78+
### Test Aliyun DM connector
79+
80+
You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
81+
82+
That's it. Don't forget to [Enable connector in sign-in experience](https://docs.logto.io/docs/tutorials/get-started/passwordless-sign-in-by-adding-connectors#enable-sms-or-email-passwordless-sign-in).
83+
84+
### Config types
85+
86+
| Name | Type |
87+
| --------------- | ----------------- |
88+
| accessKeyId | string |
89+
| accessKeySecret | string |
90+
| accountName | string |
91+
| fromAlias | string (OPTIONAL) |
92+
| templates | Template[] |
93+
94+
| Template Properties | Type | Enum values |
95+
| ------------------- | ----------- | ------------------------------------------------------- |
96+
| subject | string | N/A |
97+
| content | string | N/A |
98+
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |
99+
100+
# 阿里云邮件连接器
101+
102+
## 开始上手
103+
104+
阿里云是亚洲地区一个重要的云服务厂商，提供了包括邮件服务在内的诸多云服务。
105+
106+
本连接器是 Logto 官方提供的阿里云邮件连接器，帮助终端用户通过邮件验证码进行登录注册。
107+
108+
## 在阿里云邮件服务控制台中配置一个邮件服务
109+
110+
> 💡 **Tip**
111+
>
112+
> 你可以跳过已经完成的部分。
113+
114+
### 注册阿里云帐号
115+
116+
前往 [阿里云](https://aliyun.com/) 并完成帐号的注册。
117+
118+
### 启用并配置阿里云邮件服务
119+
120+
来到 [阿里云邮件服务](https://www.aliyun.com/product/directmail) 然后登录。点按页面左上的「申请开通」按钮以开通邮件服务并开始配置流程。
121+
122+
从 [邮件服务管理控制台](https://dm.console.aliyun.com/) 开始：
123+
124+
1. 从侧边栏进入到「发信域名」，点按「新建域名」并完成指引。
125+
2. 依次配置好「发信地址」和「邮件标签」。
126+
127+
在完成了设置之后，这里提供了两种测试的方法：
128+
129+
- 前往 [邮件服务管理控制台概览](https://dm.console.aliyun.com/)，在该页面底部找到「操作引导」框并点按「发送邮件」。你可以找到很多不同的测试方法。
130+
- 在侧边栏中选择「发送邮件」->「发送邮件」，在这里你可以「新建发送任务」来测试。
131+
132+
## 编写连接器的 JSON
133+
134+
1. 在 [邮件服务管理控制台](https://dm.console.aliyun.com/)，鼠标停在右上角你的头像上，进入「AccessKey 管理」，点按「创建 AccessKey」。完成了安全验证之后，你会得到一对「AccessKey ID」和「AccessKey Secret」，请妥善保管他们。
135+
2. 从 [邮件服务管理控制台](https://dm.console.aliyun.com/) 的侧边栏，分别进入「发信地址」和「邮件标签」。这里你可以找到之前创建的 _发信地址_ 和 _邮件标签_。
136+
3. 完成阿里云邮件服务连接器的设置：
137+
- 用你在步骤 1 中拿到的一对「AccessKey ID」和「AccessKey Secret」来分别填入 `accessKeyId` 和 `accessKeySecret`。
138+
- 用步骤 2 中的 _发信地址_ 和 _邮件标签_ 填写 `accountName` 和 `fromAlias`。（`fromAlias` 可以不填写，它是 **可选的**。）
139+
- 你可以添加多个邮件服务模板以应对不同的用户场景。这里展示填写单个模板的例子：
140+
- 在 `subject` 栏填写发送邮件的 _标题_。
141+
- 在 `content` 栏中填写字符形式的内容。不要忘了在内容中插入 `{{code}}` 占位符，在真实发送时他会被替换成随机生成的验证码。
142+
- `usageType` 栏填写 `Register`，`SignIn`，`ForgotPassword` 或者`Generic` 其中之一以分别对应 _注册_，_登录_，_忘记密码_ 和 _通用_ 的不同场景。（`usageType` 是 Logto 的属性，用来确定使用场景。）为了能够使用完成的流程，需要配置 `usageType` 为 `Register`，`SignIn`, `ForgotPassword` 以及 `Generic` 的模板。
143+
144+
### 测试阿里云邮件连接器
145+
146+
你可以在「保存并完成」之前输入一个邮件地址并点按「发送」来测试配置是否可以正常工作。
147+
148+
大功告成！快去 [启用短信或邮件验证码登录](https://docs.logto.io/docs/tutorials/get-started/passwordless-sign-in-by-adding-connectors#enable-sms-or-email-passwordless-sign-in) 吧。
149+
150+
### 配置类型
151+
152+
| 名称 | 类型 |
153+
| --------------- | ----------------- |
154+
| accessKeyId | string |
155+
| accessKeySecret | string |
156+
| accountName | string |
157+
| fromAlias | string (OPTIONAL) |
158+
| templates | Template[] |
159+
160+
| 模板属性 | 类型 | 枚举值 |
161+
| --------- | ----------- | ------------------------------------------------------- |
162+
| subject | string | N/A |
163+
| content | string | N/A |
164+
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |

‎docs/integrations/email/aws-ses/README.mdx

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
slug: /integrations/aws-ses
3+
sidebar_label: AWS Direct Mail
4+
sidebar_custom_props:
5+
description: Amazon SES is a cloud email service provider that can integrate into any application for bulk email sending.
6+
logoFilename: 'aws.svg'
7+
---
8+
9+
import GuideTip from '../../fragments/_guide-tip.mdx';
10+
11+
<GuideTip />
12+
13+
# AWS direct mail connector
14+
15+
The official Logto connector for AWS connector for direct mail service.
16+
17+
- [AWS direct mail connector](#aws-direct-mail-connector)
18+
- [Get started](#get-started)
19+
- [Configure a mail service in the AWS service console](#configure-a-mail-service-in-the-aws-service-console)
20+
- [Register AWS account](#register-aws-account)
21+
- [Create a identity](#create-a-identity)
22+
- [Configuration of the connector](#configuration-of-the-connector)
23+
- [Test the Amazon SES connector](#test-the-amazon-ses-connector)
24+
- [Configure types](#configure-types)
25+
26+
## Get started
27+
28+
Amazon SES is a cloud email service provider that can integrate into any application for bulk email sending.
29+
30+
Logto team to call the Amazon Simple Email Service APIs, with the help of which Logto end-users can register and sign in to their Logto account via mail verification code.
31+
32+
## Configure a mail service in the AWS service console
33+
34+
> 💡 **Tip**
35+
>
36+
> You can skip some sections if you have already finished.
37+
38+
### Register AWS account
39+
40+
Go to [AWS](https://aws.amazon.com/) and register an account.
41+
42+
### Create a identity
43+
44+
- Go to `Amazon Simple Email Service` Console
45+
- Create an identity, choose one of the following options
46+
- Create an domain
47+
- Create an email address
48+
49+
### Configuration of the connector
50+
51+
1. Click your username in the upper right corner of the Amazon console to enter `Security Credentials`. If you don't have one, create an `AccessKey` and save it carefully.
52+
2. Complete the settings of the `Amazon Simple Email Service` connector:
53+
- Use the `AccessKey ID` and `AccessKey Secret` obtained in step 1 to fill in `accessKeyId` and `accessKeySecret` respectively.
54+
- `region`: Fill in the `region` field with the region of the identity you use to send mail.
55+
- `emailAddress`: The email address you use to send mail, in the format of `Logto\<noreply@logto.io>` or `\<noreply@logto.io>`
56+
57+
the following parameters are optional; parameters description can be found in the [AWS SES API documentation](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html).
58+
59+
- `feedbackForwardingEmailAddress`
60+
- `feedbackForwardingEmailAddressIdentityArn`
61+
- `configurationSetName`
62+
63+
### Test the Amazon SES connector
64+
65+
You can type in an email address and click on "Send" to see whether the settings work before "Save and Done".
66+
67+
That's it. Don't forget to [Enable connector in sign-in experience](https://docs.logto.io/docs/tutorials/get-started/passwordless-sign-in-by-adding-connectors#enable-sms-or-email-passwordless-sign-in).
68+
69+
### Configure types
70+
71+
| Name | Type |
72+
| ----------------------------------------- | ----------------- |
73+
| accessKeyId | string |
74+
| accessKeySecret | string |
75+
| region | string |
76+
| emailAddress | string (OPTIONAL) |
77+
| emailAddressIdentityArn | string (OPTIONAL) |
78+
| feedbackForwardingEmailAddress | string (OPTIONAL) |
79+
| feedbackForwardingEmailAddressIdentityArn | string (OPTIONAL) |
80+
| configurationSetName | string (OPTIONAL) |
81+
| templates | Template[] |
82+
83+
| Template Properties | Type | Enum values |
84+
| ------------------- | ----------- | ------------------------------------------------------- |
85+
| subject | string | N/A |
86+
| content | string | N/A |
87+
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |

‎docs/integrations/email/mailgun/README.mdx

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
slug: /integrations/mailgun
3+
sidebar_label: Mailgun
4+
sidebar_custom_props:
5+
description: Mailgun is an email delivery service for sending, receiving, and tracking emails.
6+
---
7+
8+
import GuideTip from '../../fragments/_guide-tip.mdx';
9+
10+
<GuideTip />
11+
12+
# Mailgun email connector
13+
14+
The official Logto connector for Mailgun email service.
15+
16+
**Table of contents**
17+
18+
- [Mailgun email connector](#mailgun-email-connector)
19+
- [Prerequisites](#prerequisites)
20+
- [Basic configuration](#basic-configuration)
21+
- [Deliveries](#deliveries)
22+
- [Config object](#config-object)
23+
- [Usage types](#usage-types)
24+
- [Content config](#content-config)
25+
- [Example](#example)
26+
- [Test Mailgun email connector](#test-mailgun-email-connector)
27+
28+
## Prerequisites
29+
30+
- A [Mailgun](https://www.mailgun.com/) account
31+
- An API key from your Mailgun account, requires the permission to send messages (emails). See [Where Can I Find My API Key and SMTP Credentials?](https://help.mailgun.com/hc/en-us/articles/203380100-Where-Can-I-Find-My-API-Key-and-SMTP-Credentials-) for more information.
32+
33+
## Basic configuration
34+
35+
- Fill out the `endpoint` field when you are using a different Mailgun API endpoint, for example, EU region should be `https://api.eu.mailgun.net`. The default value is `https://api.mailgun.net`.
36+
- Fill out the `domain` field with the domain you have registered in your Mailgun account. This value can be found in the **Domains** section of the Mailgun dashboard. The domain should be in the format `example.com`, without the `https://` or `http://` prefix.
37+
- Fill out the `apiKey` field with the API key you have generated in your Mailgun account.
38+
- Fill out the `from` field with the email address you want to send emails from. This email address must be registered in your Mailgun account. The email address should be in the format `Sender Name \<sender@example.com>`.
39+
40+
## Deliveries
41+
42+
### Config object
43+
44+
The "Deliveries" section allows you to configure the content of the emails to be sent in different scenarios. It is a JSON key-value map where the key is the usage type and the value is an object containing the content config for the email to be sent.
45+
46+
```json
47+
{
48+
"<usage-type>": {
49+
// ...
50+
}
51+
}
52+
```
53+
54+
### Usage types
55+
56+
The following usage types are supported:
57+
58+
- `Register`: The email to be sent when a user is registering.
59+
- `SignIn`: The email to be sent when a user is signing in.
60+
- `ForgotPassword`: The email to be sent when a user is resetting their password.
61+
- `Generic`: The email to be sent when a user is performing a generic action, for example, testing the email connector.
62+
63+
> **Note**
64+
> If the usage type is not specified in the deliveries config, the generic email will be sent. If the generic email is not specified, the connector will return an error.
65+
66+
### Content config
67+
68+
The connector supports both direct HTML content and Mailgun template. You can use one of them for each usage type.
69+
70+
In both subject and content, you can use the `{{code}}` placeholder to insert the verification code.
71+
72+
To use direct HTML content, fill out the following fields:
73+
74+
- `subject`: The subject of the email to be sent.
75+
- `replyTo`: The email address to be used as the reply-to address.
76+
- `html`: (Required) The HTML content of the email to be sent.
77+
- `text`: The plain text version of the email to be sent.
78+
79+
To use Mailgun template, fill out the following fields:
80+
81+
- `subject`: The subject of the email to be sent.
82+
- `replyTo`: The email address to be used as the reply-to address.
83+
- `template`: (Required) The name of the Mailgun template to be used.
84+
- `variables`: The variables to be passed to the Mailgun template. Should be a JSON key-value map since it will be stringified before sending to Mailgun. Note there's no need to include the `code` variable since it will be automatically added by the connector.
85+
86+
### Example
87+
88+
The following is an example of the deliveries config:
89+
90+
```json
91+
{
92+
"Register": {
93+
"subject": "{{code}} is your verification code",
94+
"replyTo": "Foo <foo@bar.com>",
95+
"html": "<h1>Welcome to Logto</h1><p>Your verification code is {{code}}.</p>",
96+
"text": "Welcome to Logto. Your verification code is {{code}}."
97+
},
98+
"SignIn": {
99+
"subject": "Welcome back to Logto",
100+
"replyTo": "Foo <foo@bar.com>",
101+
"template": "logto-sign-in",
102+
"variables": {
103+
"bar": "baz"
104+
}
105+
}
106+
}
107+
```
108+
109+
## Test Mailgun email connector
110+
111+
You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
112+
113+
That's it. Don't forget to [Enable connector in sign-in experience](https://docs.logto.io/docs/tutorials/get-started/passwordless-sign-in-by-adding-connectors#enable-sms-or-email-passwordless-sign-in)

0 commit comments

Comments
 (0)