logto/packages/connectors/connector-sendgrid-email/README.md

SendGrid email connector

The official Logto connector for SendGrid email service.

Table of contents

• SendGrid email connector
  • Get started
  • Register SendGrid account
  • Verify senders
  • Create API keys
  • Configure your connector
    • Test SendGrid email connector
    • Config types

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.

Configure your connector

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 verification code.
• Fill out usageType field with either Register, SignIn, ForgotPassword, Generic for different use cases.
• Fill out type field with either text/plain or text/html for different types of content.

In order to enable full user flows, templates with usageType Register, SignIn, ForgotPassword and Generic are required.

Here is an example of SendGrid connector template JSON.

[
    {
        "subject": "<register-template-subject>",
        "content": "<Logto: Your verification code is {{code}}. (register template)>",
        "usageType": "Register",
        "type": "text/plain"
    },
    {
        "subject": "<sign-in-template-subject>",
        "content": "<Logto: Your verification code is {{code}}. (sign-in template)>",
        "usageType": "SignIn",
        "type": "text/plain"
    },
    {
        "subject": "<forgot-password-template-subject>",
        "content": "<Logto: Your verification code is {{code}}. (forgot-password template)>",
        "usageType": "ForgotPassword",
        "type": "text/plain"
    },
    {
        "subject": "<generic-template-subject>",
        "content": "<Logto: Your verification code is {{code}}. (generic template)>",
        "usageType": "Generic",
        "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' | 'ForgotPassword' | 'Generic'
type	enum string	'text/plain' | 'text/html'