From 305d92e0f8aa8a7081416cd01ad613408e4cb450 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 12 Apr 2023 21:13:57 +0300 Subject: [PATCH] docs: added customer confirmation email guide (#3817) * docs: added customer confirmation email guide * fix id in sidebar * fix link --- .../customers/backend/send-confirmation.md | 194 ++++++++++++++++++ docs/content/modules/customers/overview.mdx | 15 +- www/docs/sidebars.js | 7 +- 3 files changed, 201 insertions(+), 15 deletions(-) create mode 100644 docs/content/modules/customers/backend/send-confirmation.md diff --git a/docs/content/modules/customers/backend/send-confirmation.md b/docs/content/modules/customers/backend/send-confirmation.md new file mode 100644 index 0000000000..aad4246988 --- /dev/null +++ b/docs/content/modules/customers/backend/send-confirmation.md @@ -0,0 +1,194 @@ +--- +description: 'Learn how to send a confirmation email to the customer after they sign up. This guide uses SendGrid as an example Notification provider.' +addHowToData: true +--- + +# How to Send Confirmation Email + +In this document, you’ll learn how to send a confirmation email to the customer after they sign up. + +## Overview + +When a customer registers, the event `customer.created` is triggered. You can then listen to this event in a subscriber to perform an action, such as send the customer a confirmation email. + +This guide will explain how to create the subscriber and how to use SendGrid to send the confirmation email. SendGrid is only used to illustrate how the process works, but you’re free to use any other notification service. + +--- + +## Prerequisites + +### Medusa Backend + +It’s assumed you already have the Medusa backend installed. If not, you can either use the [create-medusa-app command](../../../create-medusa-app.mdx) to install different Medusa tools, including the backend, or [install the backend only](../../../development/backend/install.mdx). + +### Event Bus Module + +The triggered events are relayed to the listening subscribers using an event bus module. So, it’s required to have an event bus module installed and configured on your Medusa backend. + +The [Local Event Bus module](../../../development/events/modules/local.md) works in a development environment. For production, it’s recommended to use the [Redis Event Bus module](../../../development/events/modules/redis.md). + +### Notification Provider + +As mentioned in the overview, this guide illustrates how to send the email using SendGrid. If you intend to follow along, you must have the [SendGrid plugin](../../../plugins/notifications/sendgrid.mdx) installed and configured. + +You can also find other available Notification provider plugins in the [Plugins directory](https://medusajs.com/plugins/), or [create your own](../../../development/notification/create-notification-provider.md). + +--- + +## Step 1: Create the Subscriber + +To subscribe to and handle an event, you must create a subscriber. + +:::note + +You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx). + +::: + +Create the file `src/subscribers/customer-confirmation.ts` with the following content: + +```ts title=src/subscribers/customer-confirmation.ts +type InjectedDependencies = { + // TODO add necessary dependencies +} + +class CustomerConfirmationSubscriber { + constructor(container: InjectedDependencies) { + // TODO subscribe to event + } +} + +export default CustomerConfirmationSubscriber +``` + +You’ll be adding in the next step the necessary dependencies to the subscriber. + +:::note + +You can learn more about dependency injection in [this documentation](../../../development/fundamentals/dependency-injection.md). + +::: + +--- + +## Step 2: Subscribe to the Event + +In this step, you’ll subscribe to the `customer.created` event to send the customer a confirmation email. + +There are two ways to do this: + +### Method 1: Using the NotificationService + +If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`: + +```ts title=src/subscribers/customer-confirmation.ts +import { NotificationService } from "@medusajs/medusa" + +type InjectedDependencies = { + notificationService: NotificationService +} + +class CustomerConfirmationSubscriber { + constructor({ notificationService }: InjectedDependencies) { + notificationService.subscribe( + "customer.created", + "" + ) + } +} + +export default CustomerConfirmationSubscriber +``` + +Where `` is the identifier for your notification provider. + +:::note + +You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md). + +::: + +### Method 2: Using the EventBusService + +If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`: + +```ts title=src/subscribers/customer-confirmation.ts +import { Customer, EventBusService } from "@medusajs/medusa" + +type InjectedDependencies = { + eventBusService: EventBusService +} + +class CustomerConfirmationSubscriber { + constructor({ eventBusService }: InjectedDependencies) { + eventBusService.subscribe( + "customer.created", + this.handleCustomerConfirmation + ) + } + + handleCustomerConfirmation = async (data: Customer) => { + // TODO: handle event + } +} + +export default CustomerConfirmationSubscriber +``` + +When using this method, you’ll have to handle the logic of sending the confirmation email to the customer inside the handler function, which in this case is `handleCustomerConfirmation`. + +## Step 3: Handle the Event + +The `handleCustomerConfirmation` event receives a `data` object as a parameter. This object is the entire customer object. So, you can find in it fields like `first_name`, `last_name`, `email`, and more. + +In this method, you should typically send an email to the customer. You can place any content in the email, such as welcoming them to your store or thanking them for registering. + +### Example: Using SendGrid + +For example, you can implement this subscriber to send emails using SendGrid: + +```ts title=src/subscribers/customer-confirmation.ts +import { Customer, EventBusService } from "@medusajs/medusa" + +type InjectedDependencies = { + eventBusService: EventBusService, + sendgridService: any +} + +class CustomerConfirmationSubscriber { + protected sendGridService: any + + constructor({ + eventBusService, + sendgridService, + }: InjectedDependencies) { + this.sendGridService = sendgridService + eventBusService.subscribe( + "customer.created", + this.handleCustomerConfirmation + ) + } + + handleCustomerConfirmation = async (data: Customer) => { + this.sendGridService.sendEmail({ + templateId: "customer-confirmation", + from: "hello@medusajs.com", + to: data.email, + data: { + // any data necessary for your template... + first_name: data.first_name, + last_name: data.last_name, + }, + }) + } +} + +export default CustomerConfirmationSubscriber +``` + +Notice that you should replace the values in the object passed to the `sendEmail` method: + +- `templateId`: Should be the ID of your confirmation email template in SendGrid. +- `from`: Should be the from email. +- `to`: Should be the customer’s email. +- `data`: Should be an object holding any data that should be passed to your SendGrid email template. diff --git a/docs/content/modules/customers/overview.mdx b/docs/content/modules/customers/overview.mdx index 116e9d8dbc..fdbc431e05 100644 --- a/docs/content/modules/customers/overview.mdx +++ b/docs/content/modules/customers/overview.mdx @@ -28,22 +28,20 @@ An admin can manage all customers and their details. diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 2055ae75c2..61c99e6b6c 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -526,12 +526,9 @@ module.exports = { }, }, { - type: "link", - href: "#", + type: "doc", + id: "modules/customers/backend/send-confirmation", label: "Backend: Send SignUp Email", - customProps: { - sidebar_is_soon: true, - }, }, { type: "doc",