This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

SendGrid

SendGrid is a cloud-based email service to send and manage email campaigns, transactional emails, and other types of email communications. With SendGrid, you can create and send emails, track their performance, and manage your email lists and subscribers.

The Good Store comes with an out-of-the-box commercetools Frontend extension for SendGrid.

Prerequisites

A SendGrid account
A verified sender identity. SendGrid will send a verification email to your address, you must reply to the email to complete the verification process.
A verified email domain. You must do it after verifying your sender identity. You need access to your DNS settings or server to complete this step.
Dynamic transactional templates configured. The templates should include at least the following types of emails: welcome email, email verification, password reset request, account deletion, and order confirmation.
At least one contact list set up. You should at least create a newsletter list to send regular updates to your subscribers.

Get started

To start using the SendGrid extension, follow these steps:

Add the following project configuration fields to the project schema from the Studio.

Add SendGrid project configuration fieldsjson

{
  "name": "Sendgrid Extension",
  "fields": [
    {
      "label": "API Key",
      "field": "EXTENSION_SENDGRID_API_KEY",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Sender",
      "field": "EXTENSION_SENDGRID_SENDER",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Client Host",
      "field": "EXTENSION_SENDGRID_CLIENT_HOST",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Template ID: Account Verification",
      "field": "EXTENSION_SENDGRID_TEMPLATE_ACCOUNT_VERIFICATION",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Template ID: Password Reset",
      "field": "EXTENSION_SENDGRID_TEMPLATE_PASSWORD_RESET",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Template ID: Welcome Customer",
      "field": "EXTENSION_SENDGRID_TEMPLATE_WELCOME_CUSTOMER",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Template ID: Order Confirmation",
      "field": "EXTENSION_SENDGRID_TEMPLATE_ORDER_CONFIRMATION",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "Template ID: Account Deletion",
      "field": "EXTENSION_SENDGRID_TEMPLATE_ACCOUNT_DELETION",
      "type": "string",
      "translatable": false,
      "required": true
    },
    {
      "label": "List ID: Newsletter",
      "field": "EXTENSION_SENDGRID_LIST_NEWSLETTER",
      "type": "string",
      "translatable": false,
      "required": true
    }
  ]
}

Set the SendGrid configuration values from the Studio.
Open EmailApiFactory.ts file at the following path /commerce-commercetools/utils/EmailApiFactory.ts.
Check that the getDefaultApi method returns an instance of SendgridEmailApi to use SendGrid as default for sending emails.
getDefaultApi method in the EmailApiFactory.ts fileTypeScript
static getDefaultApi(context: Context, locale: string) {
return this.getSmtpApi(context, locale);
}

Out-of-the-box emails

The following transactional emails are already configured in The Good Store to be sent.

Welcome email upon account creation
Account verification email
Password reset request email
Account deletion confirmation email
Order confirmation email

You can also use SendGrid to send marketing emails. Marketing emails are not pre-configured in this extension.

Add emails

You can configure and send emails in addition to those already available. To implement additional emails, follow these steps:

From the SendGrid dashboard, create a dynamic template. For example, the Password Reset Confirmation template. Then, copy the ID of the template for later use.
From the Studio, edit the Sendgrid Extension configuration fields that you defined earlier by adding a field for the template you created.
Add a project configuration field for the Password Reset Confirmation templatejson
{
"label": "Template ID: Password Reset Confirmation",
"field": "EXTENSION_SENDGRID_TEMPLATE_PASSWORD_RESET_CONFIRMATION",
"type": "string",
"translatable": false,
"required": true
}
From the Studio, enter the ID of the template in the project configuration field you added. For example, enter the ID of the Password Reset Confirmation template in the Template ID: Password Reset Confirmation field.

Go to the EmailApi.ts file at the following path backend/email-sendgrid/apis. In the file, add the templateId to the constructor configuration values.

Add the ID of the Password Reset Confirmation template in the constructorTypeScript

constructor(frontasticContext: Context, locale?: string) {
 ...

 this.configuration = {
   ...,
   templateIds: {
     ...,
     passwordResetConfirmation: frontasticContext.projectConfiguration.EXTENSION_SENDGRID_TEMPLATE_PASSWORD_RESET_CONFIRMATION,
   }
 };
}

Go to the BaseEmailApi.ts file at the following path backend/interfaces. In the file, extend the BaseEmailApi interface with a method responsible for sending the desired email. For example, sendPasswordResetConfirmation.
Extend BaseEmailApi interface with the sendPasswordResetConfirmation methodTypeScript
export interface BaseEmailApi {
...
sendPasswordResetConfirmation: (customer: Account) =>
Promise<void>;
}

Go to the EmailApi.ts file at the following path backend/email-sendgrid/apis. In the file, define the method you declared in the BaseEmailApi interface.

Define the sendPasswordResetConfirmation methodTypeScript

   async sendPasswordResetConfirmation(customer: Account) {
     await this.emailClient.send({
       from: this.configuration.sender, // Sender's email address
       personalizations: [
         {
           to: [customer.email], // Reciepent's email address
           dynamicTemplateData: { customer }, // Template context data
         },
       ],
       templateId: this.configuration.templateIds.passwordResetConfirmation, // Dynamic transactional template ID
     });
   }

To send the email, call EmailApiFactory.getDefaultApi().METHOD_NAME(customerObject);.

Call the sendPasswordResetConfirmation method to send the related emailTypeScript

import { getLocale } from '../utils/Request';
import { EmailApiFactory } from '../utils/EmailApiFactory';

export const myAction = async (
  request: Request,
  actionContext: ActionContext
) => {
  const locale = getLocale(request);

  const account = { email: 'user@example.com' }; // The object that is returned by fetching the user account from Composable Commerce.

  const emailApi = EmailApiFactory.getDefaultApi(
    actionContext.frontasticContext,
    locale
  ).sendPasswordResetConfirmation(account);
};

Out-of-the-box contact list

The SendGrid extension is pre-configured to compile a contact list for newsletter subscribers. Customers can opt in for the newsletter through the Account Registration and My Account Frontend Components. If needed, you can add contacts lists.

Add contact lists

To add a contact list, follow these steps:

Log in to SendGrid dashboard and go to the Marketing Campaigns dashboard.
Go to Contacts > Lists. Then, click Create List.
Enter the name of the contact list (for example, Discounts).
Select the type of contacts you want to add to the list. You can choose to add contacts manually, import them from a file, or import them from a third-party service.
Click Create List: the contact list is saved in Contacts > Lists.
From Contacts > Lists, select the contact list you created and copy the contact list ID. The ID of the contact list is displayed in the page URL: https://app.sendgrid.com/marketing_campaigns/lists/CONTACT_LIST_ID.
From the Studio, edit the Sendgrid Extension configuration fields that you defined earlier by adding a field for the ID of the contact list you created. For example, for the Discounts contact list.
Add a project configuration field for the Discounts contact listjson
{
"label": "List ID: Discounts",
"field": "EXTENSION_SENDGRID_LIST_DISCOUNTS",
"type": "string",
"translatable": false,
"required": true
}
From the Studio, enter the ID of the contact list in the project configuration field you added. For example, enter the ID of the Discounts contact in the List ID: Discounts field.
Use the contact list ID to subscribe or unsubscribe users from the contact list using the subscribe and unsubscribe methods in the EmailApi.ts file at the following path backend/email-sendgrid/apis.
You must call the methods with the following parameters:
- account: an object containing the data of the user to subscribe/unsubscribe from the list. Currently, it only creates a subscription with email (required), first_name, and last_name.
- lists: an array of contact list IDs to subscribe the user to. Only applicable when calling the subscribe method.
Following is a sample implementation to subscribe and unsubscribe from the Discounts contact list.
First, go to the EmailApi.ts file at the following path backend/email-sendgrid/apis and add the listId to the constructor configuration values.
Add the ID of the Discounts contact list to the constructorTypeScript
constructor(frontasticContext: Context, locale?: string) {
...

this.configuration = {
...,
listIds: {
...,
discounts: frontasticContext.projectConfiguration.EXTENSION_SENDGRID_LIST_DISCOUNTS
}
}
}
Then, use the following code in the action controllers at this path backend/commerce-commercetools.
Subscribe and unsubscribe from the Discounts contact listJavaScript
import { getLocale } from '../utils/Request';
import { EmailApiFactory } from '../utils/EmailApiFactory';

export const myAction = async (
request: Request,
actionContext: ActionContext
) => {
const locale = getLocale(request);

const emailApi = EmailApiFactory.getDefaultApi(
actionContext.frontasticContext,
locale
);

const account = { email: 'user@example.com' }; // The object that is returned by fetching the user account from Composable Commerce.

emailApi.subscribe(account, ['discounts']); // Subscribes the user to the Discounts contact list.

emailApi.unsubscribe(account, 'discounts'); // Unsubscribes the user from the Discounts contact list.
};