Skip to content

Commit b1d8ce1

Browse files
Rany0101charIeszhao
Rany0101
authored and
charIeszhao
committed
refactor: add email/sms/social connectors into tutorial
1. Social connectors: Alipay, Feishu, WeChat, WeCom, Microsoft (Update the name) 2. Email connectors: Aliyun, Mailgun, Postmark, SMTP 3. SMS connectors: Aero, Aliyun, GatewayAPI, Tencent, Vonage
1 parent a2ec658 commit b1d8ce1

31 files changed

+1030
-934
lines changed

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

Lines changed: 6 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,15 @@ sidebar_label: Aliyun Direct Mail
44
sidebar_custom_props:
55
description: Aliyun provides cloud computing services to online businesses.
66
logoFilename: 'aliyun.svg'
7+
tutorial_name: Aliyun Direct Mail
8+
tutorial_config_name: Aliyun email connector
9+
tutorial_sign_up_identifier: Email address
710
---
811

912
import GuideTip from '../../fragments/_guide-tip.mdx';
1013

14+
import Integration from './_integration.mdx';
15+
1116
# Set up email verification with Aliyun Direct Mail
1217

1318
The official Logto connector for Aliyun connector for direct mail service.
@@ -18,56 +23,4 @@ The official Logto connector for Aliyun connector for direct mail service.
1823

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

21-
## Set up an email service in Aliyun DirectMail Console \{#set-up-an-email-service-in-aliyun-directmail-console}
22-
23-
### Create an Aliyun account \{#create-an-aliyun-account}
24-
25-
Head to [Aliyun](https://aliyun.com/) and create your Aliyun account if you don't have one.
26-
27-
### Enable and configure Aliyun Direct Mail \{#enable-and-configure-aliyun-direct-mail}
28-
29-
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.
30-
31-
Starting from the [DM admin console page](https://dm.console.aliyun.com/), you should:
32-
33-
1. Go to "Email Domains" (发信域名) from the sidebar and add "New Domain" (新建域名) following the instructions.
34-
2. Customize "Sender Addresses" (发信地址) and "Email Tags" (邮件标签) respectively.
35-
36-
After finishing setup, there are two different ways to test:
37-
38-
- 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.
39-
- Follow the path "Send Emails" (发送邮件) -> "Email Tasks" (发送邮件) in the sidebar to create a testing task.
40-
41-
## Compose the connector JSON \{#compose-the-connector-json}
42-
43-
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.
44-
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.
45-
3. Fill out the Aliyun DM Connector settings:
46-
- Fill out the `accessKeyId` and `accessKeySecret` fields with access key pairs you've got from step 1.
47-
- 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.)
48-
- You can add multiple DM connector templates for different cases. Here is an example of adding a single template:
49-
- Fill out the `subject` field, which will work as title of the sending email.
50-
- Fill out the `content` field with arbitrary string-type contents. Do not forget to leave `{{code}}` placeholder for random verification code.
51-
- 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.
52-
53-
### Test Aliyun DM connector \{#test-aliyun-dm-connector}
54-
55-
You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
56-
57-
That's it. Don't forget to <MainSiteUrl href="/connectors/email-connectors/#enable-email-sign-up-or-sign-in">Enable connector in sign-in experience</MainSiteUrl>.
58-
59-
### Config types \{#config-types}
60-
61-
| Name | Type |
62-
| --------------- | ----------------- |
63-
| accessKeyId | string |
64-
| accessKeySecret | string |
65-
| accountName | string |
66-
| fromAlias | string (OPTIONAL) |
67-
| templates | Template[] |
68-
69-
| Template Properties | Type | Enum values |
70-
| ------------------- | ----------- | ------------------------------------------------------- |
71-
| subject | string | N/A |
72-
| content | string | N/A |
73-
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |
26+
<Integration />

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Set up an email service in Aliyun DirectMail Console \{#set-up-an-email-service-in-aliyun-directmail-console}
2+
3+
### Create an Aliyun account \{#create-an-aliyun-account}
4+
5+
Head to [Aliyun](https://aliyun.com/) and create your Aliyun account if you don't have one.
6+
7+
### Enable and configure Aliyun Direct Mail \{#enable-and-configure-aliyun-direct-mail}
8+
9+
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.
10+
11+
Starting from the [DM admin console page](https://dm.console.aliyun.com/), you should:
12+
13+
1. Go to "Email Domains" (发信域名) from the sidebar and add "New Domain" (新建域名) following the instructions.
14+
2. Customize "Sender Addresses" (发信地址) and "Email Tags" (邮件标签) respectively.
15+
16+
After finishing setup, there are two different ways to test:
17+
18+
- 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.
19+
- Follow the path "Send Emails" (发送邮件) -> "Email Tasks" (发送邮件) in the sidebar to create a testing task.
20+
21+
## Compose the connector JSON \{#compose-the-connector-json}
22+
23+
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.
24+
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.
25+
3. Fill out the Aliyun DM Connector settings:
26+
- Fill out the `accessKeyId` and `accessKeySecret` fields with access key pairs you've got from step 1.
27+
- 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.)
28+
- You can add multiple DM connector templates for different cases. Here is an example of adding a single template:
29+
- Fill out the `subject` field, which will work as title of the sending email.
30+
- Fill out the `content` field with arbitrary string-type contents. Do not forget to leave `{{code}}` placeholder for random verification code.
31+
- 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.
32+
33+
### Test Aliyun DM connector \{#test-aliyun-dm-connector}
34+
35+
You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
36+
37+
That's it. Don't forget to <MainSiteUrl href="/connectors/email-connectors/#enable-email-sign-up-or-sign-in">Enable connector in sign-in experience</MainSiteUrl>.
38+
39+
### Config types \{#config-types}
40+
41+
| Name | Type |
42+
| --------------- | ----------------- |
43+
| accessKeyId | string |
44+
| accessKeySecret | string |
45+
| accountName | string |
46+
| fromAlias | string (OPTIONAL) |
47+
| templates | Template[] |
48+
49+
| Template Properties | Type | Enum values |
50+
| ------------------- | ----------- | ------------------------------------------------------- |
51+
| subject | string | N/A |
52+
| content | string | N/A |
53+
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |

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

Lines changed: 6 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -3,97 +3,22 @@ slug: /integrations/mailgun
33
sidebar_label: Mailgun
44
sidebar_custom_props:
55
description: Mailgun is an email delivery service for sending, receiving, and tracking emails.
6+
tutorial_name: Mailgun
7+
tutorial_config_name: Mailgun email connector
8+
tutorial_sign_up_identifier: Email address
69
---
710

811
import GuideTip from '../../fragments/_guide-tip.mdx';
912

13+
import Integration from './_integration.mdx';
14+
1015
# Set up email verification with Mailgun email service
1116

1217
The official Logto connector for Mailgun email service.
1318

1419
<GuideTip />
1520

16-
## Prerequisites \{#prerequisites}
17-
18-
- A [Mailgun](https://www.mailgun.com/) account
19-
- 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.
20-
21-
## Basic configuration \{#basic-configuration}
22-
23-
- 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`.
24-
- 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.
25-
- Fill out the `apiKey` field with the API key you have generated in your Mailgun account.
26-
- 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>`.
27-
28-
## Deliveries \{#deliveries}
29-
30-
### Config object \{#config-object}
31-
32-
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.
33-
34-
```json
35-
{
36-
"<usage-type>": {
37-
// ...
38-
}
39-
}
40-
```
41-
42-
### Usage types \{#usage-types}
43-
44-
The following usage types are supported:
45-
46-
- `Register`: The email to be sent when a user is registering.
47-
- `SignIn`: The email to be sent when a user is signing in.
48-
- `ForgotPassword`: The email to be sent when a user is resetting their password.
49-
- `Generic`: The email to be sent when a user is performing a generic action, for example, testing the email connector.
50-
51-
:::note
52-
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.
53-
:::
54-
55-
### Content config \{#content-config}
56-
57-
The connector supports both direct HTML content and Mailgun template. You can use one of them for each usage type.
58-
59-
In both subject and content, you can use the `{{code}}` placeholder to insert the verification code.
60-
61-
To use direct HTML content, fill out the following fields:
62-
63-
- `subject`: The subject of the email to be sent.
64-
- `replyTo`: The email address to be used as the reply-to address.
65-
- `html`: (Required) The HTML content of the email to be sent.
66-
- `text`: The plain text version of the email to be sent.
67-
68-
To use Mailgun template, fill out the following fields:
69-
70-
- `subject`: The subject of the email to be sent.
71-
- `replyTo`: The email address to be used as the reply-to address.
72-
- `template`: (Required) The name of the Mailgun template to be used.
73-
- `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.
74-
75-
### Example \{#example}
76-
77-
The following is an example of the deliveries config:
78-
79-
```json
80-
{
81-
"Register": {
82-
"subject": "{{code}} is your verification code",
83-
"replyTo": "Foo <foo@bar.com>",
84-
"html": "<h1>Welcome to Logto</h1><p>Your verification code is {{code}}.</p>",
85-
"text": "Welcome to Logto. Your verification code is {{code}}."
86-
},
87-
"SignIn": {
88-
"subject": "Welcome back to Logto",
89-
"replyTo": "Foo <foo@bar.com>",
90-
"template": "logto-sign-in",
91-
"variables": {
92-
"bar": "baz"
93-
}
94-
}
95-
}
96-
```
21+
<Integration />
9722

9823
## Test Mailgun email connector \{#test-mailgun-email-connector}
9924

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
## Prerequisites \{#prerequisites}
2+
3+
- A [Mailgun](https://www.mailgun.com/) account
4+
- 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.
5+
6+
## Basic configuration \{#basic-configuration}
7+
8+
- 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`.
9+
- 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.
10+
- Fill out the `apiKey` field with the API key you have generated in your Mailgun account.
11+
- 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>`.
12+
13+
## Deliveries \{#deliveries}
14+
15+
### Config object \{#config-object}
16+
17+
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.
18+
19+
```json
20+
{
21+
"<usage-type>": {
22+
// ...
23+
}
24+
}
25+
```
26+
27+
### Usage types \{#usage-types}
28+
29+
The following usage types are supported:
30+
31+
- `Register`: The email to be sent when a user is registering.
32+
- `SignIn`: The email to be sent when a user is signing in.
33+
- `ForgotPassword`: The email to be sent when a user is resetting their password.
34+
- `Generic`: The email to be sent when a user is performing a generic action, for example, testing the email connector.
35+
36+
:::note
37+
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.
38+
:::
39+
40+
### Content config \{#content-config}
41+
42+
The connector supports both direct HTML content and Mailgun template. You can use one of them for each usage type.
43+
44+
In both subject and content, you can use the `{{code}}` placeholder to insert the verification code.
45+
46+
To use direct HTML content, fill out the following fields:
47+
48+
- `subject`: The subject of the email to be sent.
49+
- `replyTo`: The email address to be used as the reply-to address.
50+
- `html`: (Required) The HTML content of the email to be sent.
51+
- `text`: The plain text version of the email to be sent.
52+
53+
To use Mailgun template, fill out the following fields:
54+
55+
- `subject`: The subject of the email to be sent.
56+
- `replyTo`: The email address to be used as the reply-to address.
57+
- `template`: (Required) The name of the Mailgun template to be used.
58+
- `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.
59+
60+
### Example \{#example}
61+
62+
The following is an example of the deliveries config:
63+
64+
```json
65+
{
66+
"Register": {
67+
"subject": "{{code}} is your verification code",
68+
"replyTo": "Foo <foo@bar.com>",
69+
"html": "<h1>Welcome to Logto</h1><p>Your verification code is {{code}}.</p>",
70+
"text": "Welcome to Logto. Your verification code is {{code}}."
71+
},
72+
"SignIn": {
73+
"subject": "Welcome back to Logto",
74+
"replyTo": "Foo <foo@bar.com>",
75+
"template": "logto-sign-in",
76+
"variables": {
77+
"bar": "baz"
78+
}
79+
}
80+
}
81+
```

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

Lines changed: 6 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,15 @@ slug: /integrations/postmark
33
sidebar_label: Postmark
44
sidebar_custom_props:
55
description: Postmark is a mail sending platform.
6+
tutorial_name: Postmark
7+
tutorial_config_name: Postmark email connector
8+
tutorial_sign_up_identifier: Email address
69
---
710

811
import GuideTip from '../../fragments/_guide-tip.mdx';
912

13+
import Integration from './_integration.mdx';
14+
1015
# Set up email verification with Postmark email service
1116

1217
Logto connector for Postmark email service.
@@ -17,56 +22,4 @@ Logto connector for Postmark email service.
1722

1823
Postmark is a mail platform for transactional and marketing email. We can use its email sending function to send a _verification code_.
1924

20-
## Register Postmark account \{#register-postmark-account}
21-
22-
Create a new account at [Postmark website](https://postmark.com/). You may skip this step if you've already got an account.
23-
24-
## Configure your connector \{#configure-your-connector}
25-
26-
Fill out the `serverToken` field with the Server Token you find under settings for your
27-
server in Postmark.
28-
29-
Fill out the `fromEmail` field with the senders' _From Address_.
30-
31-
In order to enable full user flows, templates with usageType `Register`, `SignIn`, `ForgotPassword` and `Generic` are required
32-
33-
Here is an example of Postmark connector template JSON.
34-
35-
```jsonc
36-
[
37-
{
38-
"usageType": "Register",
39-
"templateAlias": "logto-register",
40-
},
41-
{
42-
"usageType": "SignIn",
43-
"templateAlias": "logto-sign-in",
44-
},
45-
{
46-
"usageType": "ForgotPassword",
47-
"templateAlias": "logto-forgot-password",
48-
},
49-
{
50-
"usageType": "Generic",
51-
"templateAlias": "logto-generic",
52-
},
53-
]
54-
```
55-
56-
## Test Postmark email connector \{#test-postmark-email-connector}
57-
58-
You can type in an email address and click on "Send" to see whether the settings can work before "Save and Done".
59-
60-
That's it. Don't forget to <MainSiteUrl href="/connectors/email-connectors/#enable-email-sign-up-or-sign-in">Enable connector in sign-in experience</MainSiteUrl>.
61-
62-
## Config types \{#config-types}
63-
64-
| Name | Type |
65-
| ----------- | ------ |
66-
| serverToken | string |
67-
| fromEmail | string |
68-
69-
| Template Properties | Type | Enum values |
70-
| ------------------- | ----------- | ------------------------------------------------------- |
71-
| usageType | enum string | 'Register' \| 'SignIn' \| 'ForgotPassword' \| 'Generic' |
72-
| templateAlias | string | N/A |
25+
<Integration />

0 commit comments

Comments
 (0)