logto/packages/connector-sendgrid-mail/README.md

SendGrid mail connector

The official Logto connector for SendGrid email service.

SendGrid 邮件服务 Logto 官方连接器 中文文档

Table of contents

• SendGrid mail connector
  • Get started
  • Register SendGrid account
  • Verify senders
  • Create API keys
  • Compose the connector JSON
    • Test SendGrid email connector
    • Config types
• SendGrid 邮件连接器
  • 开始上手
  • 创建 SendGrid 帐号
  • 验证 sender
  • 创建 API 密钥
  • 编写连接器的 JSON
    • 测试 SendGrid 邮件连接器
    • 配置类型

Get started

SendGrid (i.e. Twilio SendGrid) is a customer communication platform for transactional and marketing email. We can use its email sending function to send a verification code.

Register SendGrid account

Create a new account at SendGrid website. You may skip this step if you've already got an account.

Verify senders

Go to the SendGrid console page and sign in with your SendGrid account.

Senders indicate the addresses our verification code email will be sent from. In order to send emails via the SendGrid mail server, you need to verify at least one sender.

Starting from the SendGrid console page, go to "Settings" -> "Sender Authentication" from the sidebar.

Domain Authentication is recommended but not obligatory. You can click "Get Started" in "Authenticate Your Domain" card and follow the upcoming guide to link and verify a sender to SendGrid.

By clicking the "Verify a Single Sender" button in the panel, you are now focusing on a form requiring some critical information to create a sender. Follow the guide, fill out all these fields, and hit the "Create" button.

After the single sender is created, an email with a verification link should be sent to your sender's email address. Go to your mailbox, find the verification mail and finish verifying the single sender by clicking the link given in the email. You can now send emails via SendGrid connector using the sender you've just verified.

Create API keys

Let's start from the SendGrid console page, go to "Settings" -> "API Keys" from the sidebar.

Click the "Create API Key" in the top-right corner of the API Keys page. Type in the name of the API key and customize "API Key Permission" per your use case. A global Full Access or Restricted Access with full access to Mail Send is required before sending emails with this API key.

The API Key is presented to you on the screen as soon as you finished the Create API Key process. You should save this API Key somewhere safe because this is the only chance that you can see it.

Compose the connector JSON

Fill out the apiKey field with the API Key created in "Create API keys" section.

Fill out the fromEmail and fromName fields with the senders' From Address and Nickname. You can find the sender's details on the "Sender Management" page. fromName is OPTIONAL, so you can skip filling it.

You can add multiple SendGrid mail connector templates for different cases. Here is an example of adding a single template:

• Fill out the subject field, which works as the title of emails.
• Fill out the content field with arbitrary string-typed contents. Do not forget to leave the {{code}} placeholder for the random passcode.
• Fill out usageType field with either Register, SignIn or Test for different use cases.
• Fill out type field with either text/plain or text/html for different types of content.

Here is an example of SendGrid connector config JSON.

{
    "apiKey": "<your-api-key>",
    "fromEmail": "<noreply@logto.io>",
    "fromName": "<logto>", // This is OPTIONAL
    "templates": [
        {
            "subject": "<register-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (regitser template)>",
            "usageType": "Register",
            "type": "text/plain"
        },
        {
            "subject": "<sign-in-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (sign-in template)>",
            "usageType": "SignIn",
            "type": "text/plain"
        },
        {
            "subject": "<test-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (test template)>",
            "usageType": "Test",
            "type": "text/plain"
        },
    ]
}

Test SendGrid email 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

Config types

Name	Type
apiKey	string
fromEmail	string
fromName	string (OPTIONAL)
templates	Template[]

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

SendGrid 邮件连接器

开始上手

SendGrid（即 Twilio SendGrid）是一个用于交易和营销电子邮件的通信平台。我们可以使用它的电子邮件发送功能来发送 verification code。

创建 SendGrid 帐号

在 SendGrid 创建一个新帐号。如果已经拥有帐号则可以跳过这一步。

验证 sender

前往 SendGrid 控制台 并用 SendGrid 帐号登录。

Sender 指的是验证码邮件发出的地址。若是要通过 SendGrid 邮件服务器对外发送邮件，你需要验证通过至少一个 sender。

从 SendGrid 控制台 开始，从侧边栏依次前往 "Settings" -> "Sender Authentication"。

Domain Authentication 是推荐，但是不强制的。你可以点按 "Authenticate Your Domain" 卡片中的 "Get Started" 按钮，并各随其中的流程完成对 SendGrid sender 的验证。

点按 "Verify a Single Sender" 按钮，便会弹出需要输入一些重要信息以创建 sender 的页面。跟随指引，把相关信息填入输入栏中，点按 "Create" 按钮。

在创建好了单个的 sender 以后，你会收到一封带有验证链接的邮件发送到你配置的 sender 邮箱。前往收件箱，找到邮件并通过其中的链接完成验证。如此一来，你便可以通过 SendGrid 连接器从你验证过的 sender 邮件地址发送邮件了。

创建 API 密钥

从 SendGrid 控制台 的侧边栏，前往 "Settings" -> "API Keys"。

点按 API Keys 页面右上角 "Create API Key" 按钮。输入 API Key 的名字并根据使用场景选择合适的 "API Key Permission"。该 API Key 需要全局的 Full Access 或者拥有「发送邮件」所有权限的 Restricted Access 才能发送邮件。

完成 Create API Key 流程之后，API Key 会出现在屏幕上。出于安全因素，API Key 只会出现这一次，因此你需要将它妥善保管。

编写连接器的 JSON

用在 "Create API Key" 中获取的 API Key 值，填入 apiKey 栏中。

用 sender 的 From Address 和 Nickname 的值分别填写给 fromEmail 和 fromName 栏。你可以在 "Sender Management" 找到这些值。fromName 栏是 可选的，所以你可以将其留白。

你可以为不同的使用场景为 SendGrid 邮件连接器添加多个内容模板，这里我们给出添加单个模板的样例：

• 填写 subject 栏，它是发送邮件的标题
• 用字符型的值填入 content 栏，不要忘了用占位符 {{code}} 预留你想放置随机生成的验证码的位置
• 从 Register，SignIn 或 Test 中选一个填入 usageType 栏，以决定当前模板所使用的场景
• 用 text/plain 或 text/html 填入 type 栏，以表明内容的形式

这是一个 SendGrid 邮件服务连接器 JSON 配置的样例。

{
    "apiKey": "<your-api-key>",
    "fromEmail": "<noreply@logto.io>",
    "fromName": "<logto>", // This is OPTIONAL
    "templates": [
        {
            "subject": "<register-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (regitser template)>",
            "usageType": "Register",
            "type": "text/plain"
        },
        {
            "subject": "<sign-in-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (sign-in template)>",
            "usageType": "SignIn",
            "type": "text/plain"
        },
        {
            "subject": "<test-template-subject>",
            "content": "<Logto: Your passcode is {{code}}. (test template)>",
            "usageType": "Test",
            "type": "text/plain"
        },
    ]
}

测试 SendGrid 邮件连接器

你可以在「保存并完成」之前输入一个邮箱地址并点按「发送」来测试配置是否可以正常工作。

大功告成！快去 启用短信或邮件验证码登录 吧。

配置类型

名称	类型
apiKey	string
fromEmail	string
fromName	string (OPTIONAL)
templates	Template[]

模板属性	类型	枚举值
subject	string	N/A
content	string	N/A
usageType	enum string	'Register' | 'SignIn' | 'Test'
type	enum string	'text/plain' | 'text/html'