# SendGrid

[SendGrid](https://sendgrid.com/) 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 Store Launchpad for B2C Retail comes with an out-of-the-box commercetools Frontend [extension](/frontend-development/extensions.md) for SendGrid.

**Prerequisites**

- A [SendGrid account](https://signup.sendgrid.com/)
- A [verified sender identity](https://docs.sendgrid.com/ui/sending-email/sender-verification). SendGrid will send a verification email to your address, you must reply to the email to complete the verification process.
- A [verified email domain](https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication). 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](https://sendgrid.com/solutions/email-api/dynamic-email-templates/). 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](https://sendgrid.com/solutions/email-marketing/email-list-management/). 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:

1. [Add the following project configuration fields to the project schema](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) from the Studio.

   ```json title="Add SendGrid project configuration fields"
   {
     "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
       }
     ]
   }
   ```

2. [Set the SendGrid configuration values](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) from the Studio.

3. Open `EmailApiFactory.ts` file at the following path `/commerce-commercetools/utils/EmailApiFactory.ts`.

4. Check that the `getDefaultApi` method returns an instance of `SendgridEmailApi` to use SendGrid as default for sending emails.

   ```ts title="getDefaultApi method in the EmailApiFactory.ts file"
     static getDefaultApi(context: Context, locale: string) {
       return this.getSmtpApi(context, locale);
     }

   ```

## Out-of-the-box emails

The following transactional emails are already configured to be sent in the Store Launchpad for B2C Retail.

- 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:

1. From the SendGrid dashboard, [create a dynamic template](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates#design-a-dynamic-template). For example, the **Password Reset Confirmation** template. Then, copy the ID of the template for later use.

2. From the Studio, edit the `Sendgrid Extension` configuration fields that you [defined earlier](/frontend-development/sendgrid.md#get-started) by [adding a field](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) for the template you created.

   ```json title="Add a project configuration field for the Password Reset Confirmation template"
   {
     "label": "Template ID: Password Reset Confirmation",
     "field": "EXTENSION_SENDGRID_TEMPLATE_PASSWORD_RESET_CONFIRMATION",
     "type": "string",
     "translatable": false,
     "required": true
   }
   ```

3. From the Studio, [enter the ID of the template](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) 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.

4. 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.

   ```ts title="Add the ID of the Password Reset Confirmation template in the constructor"
   constructor(frontasticContext: Context, locale?: string) {
    ...

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

5. 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`.

   ```ts title="Extend BaseEmailApi interface with the sendPasswordResetConfirmation method"
     export interface BaseEmailApi {
     ...
     sendPasswordResetConfirmation: (customer: Account) =>
     Promise<void>;
     }
   ```

6. 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.

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

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

   ```ts title="Call the sendPasswordResetConfirmation method to send the related email"
   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](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/frontend/frontastic/tastics/newsletter) subscribers. Customers can opt in for the newsletter through the [Account Registration](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/frontend/frontastic/tastics/account/register) and [My Account](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/frontend/frontastic/tastics/account/details) Frontend Components. If needed, you can add contact lists.

## Add contact lists

To add a contact list, follow these steps:

1. [Log in to SendGrid dashboard](https://signup.sendgrid.com/) and go to the **Marketing Campaigns** dashboard.

2. Go to **Contacts > Lists**. Then, click **Create List**.

3. Enter the name of the contact list (for example, **Discounts**).

4. 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.

5. Click **Create List**: the contact list is saved in **Contacts > Lists**.

6. 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`.

7. From the Studio, edit the `Sendgrid Extension` configuration fields that you [defined earlier](/frontend-development/sendgrid.md#get-started) by [adding a field](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) for the ID of the contact list you created. For example, for the **Discounts** contact list.

   ```json title="Add a project configuration field for the Discounts contact list"
   {
     "label": "List ID: Discounts",
     "field": "EXTENSION_SENDGRID_LIST_DISCOUNTS",
     "type": "string",
     "translatable": false,
     "required": true
   }
   ```

8. From the Studio, [enter the ID of the contact list](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) in the project configuration field you added. For example, enter the ID of the **Discounts** contact in the **List ID: Discounts** field.

9. 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.

   ```ts title="Add the ID of the Discounts contact list to the constructor"
   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`.

   ```javascript title="Subscribe and unsubscribe from the Discounts contact list"
   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.
   };
   ```

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Google Tag Manager](/frontend-development/google-tag-manager.md)
- [Next page: Checkout](/frontend-development/b2c-checkout.md)
- [Search documentation and API specs](/search.md)