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:
- The user requests to reset their password either through the frontend (for example, Medusa Admin) or the Generate Reset Password Token API route.
- 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.
- 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
:
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:
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 theemailpass
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, theactor_type
iscustomer
. If it's an admin user, theactor_type
isuser
.
actorType
field. It was renamed to actor_type
after Medusa v2.0.7.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
andconfig.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:
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:
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#
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:
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
:
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:
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: