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 MedusaGo application generates a secure, single-use password reset token and emits the auth.password_reset event.
   • The token is cryptographically secure and expires automatically (default: 15 minutes).
   • Each new password reset request invalidates any previous tokens for the same user.
   • 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.
   • The token is automatically consumed and deleted upon successful password reset, preventing reuse.

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.

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 MedusaGo application with the following command:

go run . develop

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:

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:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Reset Your Password</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
            background-color: #ffffff;
            margin: 0;
            padding: 20px;
        }
        .container {
            max-width: 465px;
            margin: 40px auto;
            border: 1px solid #eaeaea;
            border-radius: 5px;
            padding: 20px;
        }
        .header {
            text-align: center;
            margin: 30px 0;
        }
        .title {
            color: #000000;
            font-size: 24px;
            font-weight: normal;
            margin: 0;
        }
        .content {
            margin: 32px 0;
        }
        .text {
            color: #000000;
            font-size: 14px;
            line-height: 24px;
            margin: 0 0 16px 0;
        }
        .button-container {
            text-align: center;
            margin: 32px 0;
        }
        .reset-button {
            background-color: #000000;
            border-radius: 3px;
            color: #ffffff;
            font-size: 12px;
            font-weight: 600;
            text-decoration: none;
            text-align: center;
            padding: 12px 20px;
            display: inline-block;
        }
        .reset-button:hover {
            background-color: #333333;
        }
        .url-section {
            margin: 32px 0;
        }
        .url-link {
            color: #2563eb;
            text-decoration: none;
            font-size: 14px;
            line-height: 24px;
            word-break: break-all;
        }
        .disclaimer {
            margin: 32px 0;
        }
        .disclaimer-text {
            color: #666666;
            font-size: 12px;
            line-height: 24px;
            margin: 0 0 8px 0;
        }
        .security-footer {
            margin-top: 32px;
            padding-top: 20px;
            border-top: 1px solid #eaeaea;
        }
        .security-text {
            color: #666666;
            font-size: 12px;
            line-height: 24px;
            margin: 0;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1 class="title">Reset Your Password</h1>
        </div>

        <div class="content">
            <p class="text">
                Hello{{#if email}} {{email}}{{/if}},
            </p>
            <p class="text">
                We received a request to reset your password. Click the button below to create a new password for your account.
            </p>
        </div>

        <div class="button-container">
            <a href="{{reset_url}}" class="reset-button">
                Reset Password
            </a>
        </div>

        <div class="url-section">
            <p class="text">
                Or copy and paste this URL into your browser:
            </p>
            <a href="{{reset_url}}" class="url-link">
                {{reset_url}}
            </a>
        </div>

        <div class="disclaimer">
            <p class="disclaimer-text">
                This password reset link will expire soon for security reasons.
            </p>
            <p class="disclaimer-text">
                If you didn't request a password reset, you can safely ignore this email. Your password will remain unchanged.
            </p>
        </div>

        <div class="security-footer">
            <p class="security-text">
                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.
            </p>
        </div>
    </div>
</body>
</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.