Send Reset Password Email Notification

In this guide, you'll learn how to handle the auth.password_reset event to send a reset password email (or other notification type) to users.

Reset Password Flow Overview#

Users of any actor type (admin, customer, or custom actor type) can request to reset their password. The flow for resetting a password is as follows:

1. The user requests to reset their password either through the frontend (for example, Medusa Admin) or the Generate Reset Password Token API route.
2. The Medusa application generates a password reset token and emits the auth.password_reset event.
   • At this point, you can handle the event to send a notification to the user with instructions on how to reset their password.
3. The user receives the notification and clicks on the link to reset their password.
   • The user can reset their password either through the frontend (for example, Medusa Admin) or the Reset Password API route.

In this guide, you'll implement a subscriber that handles the auth.password_reset event to send an email notification to the user with instructions on how to reset their password.

After adding the subscriber, you will have a complete reset password flow you can utilize using the Medusa Admin, storefront, or API routes.

Prerequisites: Notification Module Provider#

To send an email or notification to the user, you must have a Notification Module Provider set up.

Medusa provides providers like SendGrid and Resend, and you can also create your own custom provider.

Refer to the Notification Module documentation for a list of available providers and how to set them up.

Testing with the Local Notification Module Provider#

For testing purposes, you can use the Local Notification Module Provider by adding this to your medusa-config.ts:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/notification",6      options: {7        providers: [8          // ...9          {10            resolve: "@medusajs/medusa/notification-local",11            id: "local",12            options: {13              channels: ["email"],14            },15          },16        ],17      },18    },19  ],20})

The Local provider logs email details to your terminal instead of sending actual emails, which is useful for development and testing.

Create the Reset Password Subscriber#

To create a subscriber that handles the auth.password_reset event, create the file src/subscribers/password-reset.ts with the following content:

src/subscribers/handle-reset.ts
Show more
5import { Modules } from "@medusajs/framework/utils"6
7export default async function resetPasswordTokenHandler({8  event: { data: {9    entity_id: email,10    token,11    actor_type,12  } },13  container,14}: SubscriberArgs<{ entity_id: string, token: string, actor_type: string }>) {15  const notificationModuleService = container.resolve(16    Modules.NOTIFICATION17  )18  const config = container.resolve("configModule")19
20  let urlPrefix = ""21
22  if (actor_type === "customer") {23    urlPrefix = config.admin.storefrontUrl || "https://storefront.com"24  } else {25    const backendUrl = config.admin.backendUrl !== "/" ? config.admin.backendUrl :26      "http://localhost:9000"27    const adminPath = config.admin.path28    urlPrefix = `${backendUrl}${adminPath}`29  }30
31  await notificationModuleService.createNotifications({32    to: email,33    channel: "email",34    // TODO replace with template ID in notification provider35    template: "password-reset",36    data: {37      // a URL to a frontend application38      reset_url: `${urlPrefix}/reset-password?token=${token}&email=${email}`,39    },40  })41}42
43export const config: SubscriberConfig = {44  event: "auth.password_reset",45}

The subscriber receives the following data through the event payload:

• entity_id: The identifier of the user. When using the emailpass provider, it's the user's email.
• token: The token to reset the user's password.
• actor_type: The user's actor type. For example, if the user is a customer, the actor_type is customer. If it's an admin user, the actor_type is user.

Reset Password URL#

Based on the user's actor type, you set the URL prefix to redirect the user to the appropriate frontend page to reset their password:

• If the user is a customer, you set the URL prefix to the storefront URL.
• If the user is an admin, you set the URL prefix to the backend URL, which is constructed from the config.admin.backendUrl and config.admin.path values.

Note that the Medusa Admin has a reset password form at /reset-password?token={token}&email={email}.

Notification Configurations#

For the notification, you can configure the following fields:

• to: The identifier to send the notification to, which in this case is the email.
• channel: The channel to send the notification through, which in this case is email.
• template: The template ID of the email to send. This ID depends on the Notification Module provider you use. For example, if you use SendGrid, this would be the ID of the SendGrid template.
  • Refer to the Example Notification Templates section below for examples of notification templates to use.
• data: The data payload to pass to the template. You can pass additional fields, if necessary.

Test It Out#

After you set up the Notification Module Provider, create a template in the provider, and create the subscriber, you can test the reset password flow.

Start the Medusa application with the following command:

npm
yarn
pnpm

Then, open the Medusa Admin (locally at http://localhost:9000/app) and click on "Reset" in the login form. Then, enter the email of the user you want to reset the password for.

Once you reset the password, you should see that the auth.password_reset event is emitted in the server's logs:

Terminal
❯info:    Processing auth.password_reset which has 1 subscribers

If you're using an email Notification Module Provider, check the user's email inbox for the reset password email with the link to reset their password.

If you're using the Local provider, check your terminal for the logged email details.

Next Steps: Implementing Frontend#

In your frontend, you must have a page that accepts token and email query parameters.

The page shows the user password fields to enter their new password, then submits the new password, token, and email to the Reset Password Route.

The Medusa Admin already has a reset password page at /reset-password?token={token}&email={email}. So, you only need to implement this page in your storefront or custom admin dashboard.

Examples#

• Storefront Guide: Reset Customer Password

Example Notification Templates#

The following section provides example notification templates for some Notification Module Providers.

SendGrid#

The following HTML template can be used with SendGrid to send a reset password email:

Code
1<!DOCTYPE html>2<html>3<head>4    <meta charset="utf-8">5    <meta name="viewport" content="width=device-width, initial-scale=1.0">6    <title>Reset Your Password</title>7    <style>8        body {9            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;10            background-color: #ffffff;11            margin: 0;12            padding: 20px;13        }14        .container {15            max-width: 465px;16            margin: 40px auto;17            border: 1px solid #eaeaea;18            border-radius: 5px;19            padding: 20px;20        }21        .header {22            text-align: center;23            margin: 30px 0;24        }25        .title {26            color: #000000;27            font-size: 24px;28            font-weight: normal;29            margin: 0;30        }31        .content {32            margin: 32px 0;33        }34        .text {35            color: #000000;36            font-size: 14px;37            line-height: 24px;38            margin: 0 0 16px 0;39        }40        .button-container {41            text-align: center;42            margin: 32px 0;43        }44        .reset-button {45            background-color: #000000;46            border-radius: 3px;47            color: #ffffff;48            font-size: 12px;49            font-weight: 600;50            text-decoration: none;51            text-align: center;52            padding: 12px 20px;53            display: inline-block;54        }55        .reset-button:hover {56            background-color: #333333;57        }58        .url-section {59            margin: 32px 0;60        }61        .url-link {62            color: #2563eb;63            text-decoration: none;64            font-size: 14px;65            line-height: 24px;66            word-break: break-all;67        }68        .disclaimer {69            margin: 32px 0;70        }71        .disclaimer-text {72            color: #666666;73            font-size: 12px;74            line-height: 24px;75            margin: 0 0 8px 0;76        }77        .security-footer {78            margin-top: 32px;79            padding-top: 20px;80            border-top: 1px solid #eaeaea;81        }82        .security-text {83            color: #666666;84            font-size: 12px;85            line-height: 24px;86            margin: 0;87        }88    </style>89</head>90<body>91    <div class="container">92        <div class="header">93            <h1 class="title">Reset Your Password</h1>94        </div>95
96        <div class="content">97            <p class="text">98                Hello{{#if email}} {{email}}{{/if}},99            </p>100            <p class="text">101                We received a request to reset your password. Click the button below to create a new password for your account.102            </p>103        </div>104
105        <div class="button-container">106            <a href="{{reset_url}}" class="reset-button">107                Reset Password108            </a>109        </div>110
111        <div class="url-section">112            <p class="text">113                Or copy and paste this URL into your browser:114            </p>115            <a href="{{reset_url}}" class="url-link">116                {{reset_url}}117            </a>118        </div>119
120        <div class="disclaimer">121            <p class="disclaimer-text">122                This password reset link will expire soon for security reasons.123            </p>124            <p class="disclaimer-text">125                If you didn't request a password reset, you can safely ignore this email. Your password will remain unchanged.126            </p>127        </div>128
129        <div class="security-footer">130            <p class="security-text">131                For security reasons, never share this reset link with anyone. If you're having trouble with the button above, copy and paste the URL into your web browser.132            </p>133        </div>134    </div>135</body>136</html>

Make sure to pass the reset_url variable to the template, which contains the URL to reset the password.

You can also customize the template further to show other information.

Resend#

If you've integrated Resend as explained in the Resend Integration Guide, you can add a new template for password reset emails at src/modules/resend/emails/password-reset.tsx:

src/modules/resend/emails/password-reset.tsx
1import { 2  Text, 3  Container, 4  Heading, 5  Html, 6  Section, 7  Tailwind, 8  Head, 9  Preview, 10  Body, 11  Link,12  Button, 13} from "@react-email/components"14
15type PasswordResetEmailProps = {16  reset_url: string17  email?: string18}19
20function PasswordResetEmailComponent({ reset_url, email }: PasswordResetEmailProps) {21  return (22    <Html>23      <Head />24      <Preview>Reset your password</Preview>25      <Tailwind>26        <Body className="bg-white my-auto mx-auto font-sans px-2">27          <Container className="border border-solid border-[#eaeaea] rounded my-[40px] mx-auto p-[20px] max-w-[465px]">28            <Section className="mt-[32px]">29              <Heading className="text-black text-[24px] font-normal text-center p-0 my-[30px] mx-0">30                Reset Your Password31              </Heading>32            </Section>33
34            <Section className="my-[32px]">35              <Text className="text-black text-[14px] leading-[24px]">36                Hello{email ? ` ${email}` : ""},37              </Text>38              <Text className="text-black text-[14px] leading-[24px]">39                We received a request to reset your password. Click the button below to create a new password for your account.40              </Text>41            </Section>42
43            <Section className="text-center mt-[32px] mb-[32px]">44              <Button45                className="bg-[#000000] rounded text-white text-[12px] font-semibold no-underline text-center px-5 py-3"46                href={reset_url}47              >48                Reset Password49              </Button>50            </Section>51
52            <Section className="my-[32px]">53              <Text className="text-black text-[14px] leading-[24px]">54                Or copy and paste this URL into your browser:55              </Text>56              <Link57                href={reset_url}58                className="text-blue-600 no-underline text-[14px] leading-[24px] break-all"59              >60                {reset_url}61              </Link>62            </Section>63
64            <Section className="my-[32px]">65              <Text className="text-[#666666] text-[12px] leading-[24px]">66                This password reset link will expire soon for security reasons.67              </Text>68              <Text className="text-[#666666] text-[12px] leading-[24px] mt-2">69                If you didn't request a password reset, you can safely ignore this email. Your password will remain unchanged.70              </Text>71            </Section>72
73            <Section className="mt-[32px] pt-[20px] border-t border-solid border-[#eaeaea]">74              <Text className="text-[#666666] text-[12px] leading-[24px]">75                For security reasons, never share this reset link with anyone. If you're having trouble with the button above, copy and paste the URL into your web browser.76              </Text>77            </Section>78          </Container>79        </Body>80      </Tailwind>81    </Html>82  )83}84
85export const passwordResetEmail = (props: PasswordResetEmailProps) => (86  <PasswordResetEmailComponent {...props} />87)88
89// Mock data for preview/development90const mockPasswordReset: PasswordResetEmailProps = {91  reset_url: "https://your-app.com/reset-password?token=sample-reset-token-123",92  email: "user@example.com",93}94
95export default () => <PasswordResetEmailComponent {...mockPasswordReset} />

Feel free to customize the email template further to match your branding and style, or to add additional information.

Then, in the Resend Module's service at src/modules/resend/service.ts, add the new template to the templates object and Templates type:

src/modules/resend/service.ts
1// other imports...2import { passwordResetEmail } from "./emails/password-reset"3
4enum Templates {5  // ...6  PASSWORD_RESET = "password-reset",7}8
9const templates: {[key in Templates]?: (props: unknown) => React.ReactNode} = {10  // ...11  [Templates.PASSWORD_RESET]: passwordResetEmail,12}

Finally, find the getTemplateSubject function in the ResendNotificationProviderService and add a case for the USER_INVITED template:

src/modules/resend/service.ts
1class ResendNotificationProviderService extends AbstractNotificationProviderService {2  // ...3
4  private getTemplateSubject(template: Templates) {5    // ...6    switch (template) {7      // ...8      case Templates.PASSWORD_RESET:9        return "Reset Your Password"10    }11  }12}