logto/packages/connector-sendgrid-mail

SendGrid mail connector

SendGrid (a.k.a. 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.

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 Aliyun DM connector config JSON.

{
    "apiKey": "<your-api-key>",
    "fromEmail": "<noreply@logto.io>",
    "fromName": "<logto>",
    "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"
        },
    ]
}

Config types

Name	Type
apiKey	string
fromEmail	string
fromName	string
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'