SendGrid

SendGridExternal link icon 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.

Information icon

Prerequisites

Get started

To start using the SendGrid extension, follow these steps:

  1. Open the project.yml file at the following path <root>/thegoodstore_home/config/project.yml.

  2. Add your SendGrid credentials in the configuration section as follows.

    Add your SendGrid credentialsyml
    sendgrid:
    apiKey: YOUR_API_KEY
    sender: sender@example.com
    client_host: https://my-frontend-host.com
    templateIds:
    accountVerification:
    passwordReset:
    orderConfirmation:
    welcomeCustomer:
    accountDeletion:
    listIds:
    newsletter:
    Clipboard icon
  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.

    getDefaultApi method in the EmailApiFactory.ts fileTypeScript
    static getDefaultApi(context: Context, locale: string) {
    return this.getSmtpApi(context, locale);
    }
    Clipboard icon

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:

  1. Go to the BaseEmailApi.ts file at the following path backend/interfaces/BaseEmailApi.ts

  2. 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>;
    }
    Clipboard icon
  3. Go to the EmailApi.ts file at the following path backend/email-sendgrid/apis/EmailApi.ts.

  4. In the EmailApi.ts 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.accountDeletion, // Dynamic transactional template ID
    });
    }
    Clipboard icon
  5. To send the email, call EmailApiFactory.getDefaultApi().METHOD_NAME(customerObject);.

    Call the sendPasswordResetConfirmation method to send the related emailTypeScript
    EmailApiFactory.getDefaultApi().sendPasswordResetConfirmation(
    customerObject
    );
    Clipboard icon

Contact lists

The SendGrid extension is pre-configured to compile a contacts list for newsletterExternal link icon subscribers. Customers can opt in for the newsletter through the Account RegistrationExternal link icon and My AccountExternal link icon Frontend Components.

You can add contacts lists if needed. To do so, follow these steps:

  1. Log in to SendGrid dashboardExternal link icon and go to the Marketing Campaigns dashboard.

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

  3. Enter the name of the contact list.

  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: the ID of the contact list is displayed in the page URL. For example, if the URL is https://app.sendgrid.com/marketing_campaigns/lists/123456, the list ID is 123456. Copy the contact list ID.

  7. Open the project.yml file at the following path <root>/thegoodstore_home/config/project.yml. In configuration.sendgrid.listIds, add an entry for the contact list you created. For example, the discounts contact list.

    Add discounts contact list to SendGrid configurationyml
    sendgrid:
    listIds:
    newsletter: NEWSLETTER_SENDGRID_LIST_ID
    discounts: DISCOUNTS_SENDGRID_LIST_ID
    Clipboard icon
  8. Use the contact list key (for example, discounts) to subscribe or unsubscribe users from the list using the subscribe and unsubscribe methods in the EmailApi.ts file at the following path backend/email-sendgrid/apis/EmailApi.ts.
    You must call the methods with the following parameters:

    • account: 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: only applicable when calling the subscribe method. Array of keys of the lists to subscribe the user to.

    Following is a sample implementation to subscribe and unsubscribe from the discounts contact list.

    Subscribe and unsubscribe from the discounts contact listJavaScript
    const emailApi = EmailApiFactory.getDefaultApi();
    const account = { email: 'user@example.com' }; // The object that is returned by fetching the user account from Composable Commerce.
    emailApi.subscribe(account, ['discounts']); // Subscribes user to the discounts contact list.
    emailApi.unsubscribe(account, 'discounts'); // Unsubscribes user to the discounts contact list.
    Clipboard icon