Authentication Emails

Authentication ties directly into the Email functionality that FrogBot provides. This allows you to send emails to users for verification, password resets, and more. While FrogBot provides default email templates for these actions, you can customize them to fit your brand.

Email Verification

Email Verification forces users to prove they have access to the email address they can authenticate. This will help to reduce spam accounts and ensure that users are who they say they are. To enable Email Verification, use the auth.verify property on your Collection Config:

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    verify: true,
  },
}

Tip: Verification emails are fully customizable. More details.

The following options are available:

Option	Type	Default	Description
`generateEmailHTML`	`({ req, token, user }) => string \| Promise<string>`	Built-in verification email	Returns the HTML of the verification email. More details.
`generateEmailSubject`	`({ req, token, user }) => string \| Promise<string>`	Built-in subject	Returns the subject of the verification email. More details.

generateEmailHTML

Function that allows for overriding the HTML within emails that are sent to users indicating how to validate their account. The function should return a string that supports HTML, which can optionally be a full HTML email. It receives these arguments:

Argument	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The request that created the user, with `req.frogbot`.
`token`	`string`	Always set	The verification token to send to the user.
`user`	`unknown`	Always set	The user document that needs to verify their email.

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    verify: {
      generateEmailHTML: ({ token, user }) => {
        // Use the token provided to allow your user to verify their account
        const url = `https://yourfrontend.com/verify?token=${token}`

        return `Hey ${user.email}, verify your email by clicking here: ${url}`
      },
    },
  },
}

Important: If you specify a different URL to send your users to for email verification, such as a page on the frontend of your app or similar, you need to handle making the call to the FrogBot REST or GraphQL verification operation yourself on your frontend, using the token that was provided for you. Above, it was passed via query parameter.

generateEmailSubject

Similarly to the above generateEmailHTML, you can also customize the subject of the email. The function arguments are the same but you can only return a string - not HTML.

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    verify: {
      generateEmailSubject: ({ user }) => {
        return `Hey ${user.email}, verify your email address`
      },
    },
  },
}

Forgot Password

You can customize how the Forgot Password workflow operates with the following options on the auth.forgotPassword property:

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    forgotPassword: {
      // ...
    },
  },
}

The following options are available:

Option	Type	Default	Description
`expiration`	`number`	`3600000` (1 hour)	How long a password reset token stays valid, in milliseconds.
`minRequestInterval`	`number`	`15000`	Minimum time, in milliseconds, between password reset emails for the same user. A request inside the interval sends no email. Set to `0` to disable.
`generateEmailHTML`	`({ req, token, user }) => string \| Promise<string>`	Built-in reset email	Returns the HTML of the password reset email. More details.
`generateEmailSubject`	`({ req, token, user }) => string \| Promise<string>`	Built-in subject	Returns the subject of the password reset email. More details.

Tip: FrogBot provides a built-in password reset page. If you don’t need a custom frontend, you can link directly to ${serverURL}/admin/reset/${token}. The admin and reset routes are configurable via config.routes.admin and config.admin.routes.reset respectively.

generateEmailHTML#forgot-password-generateemailhtml

This function allows for overriding the HTML within emails that are sent to users attempting to reset their password. The function should return a string that supports HTML, which can be a full HTML email.

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    forgotPassword: {
      generateEmailHTML: ({ token, user }) => {
        // Use the token provided to allow your user to reset their password
        const resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}`

        return `
          <!doctype html>
          <html>
            <body>
              <h1>Here is my custom email template!</h1>
              <p>Hello, ${user.email}!</p>
              <p>Click below to reset your password.</p>
              <p>
                <a href="${resetPasswordURL}">${resetPasswordURL}</a>
              </p>
            </body>
          </html>
        `
      },
    },
  },
}

Important: If you specify a different URL to send your users to for resetting their password, such as a page on the frontend of your app or similar, you need to handle making the call to the FrogBot REST or GraphQL reset-password operation yourself on your frontend, using the token that was provided for you. Above, it was passed via query parameter.

Tip: HTML templating can be used to create custom email templates, inline CSS automatically, and more. You can make a reusable function that standardizes all email sent from FrogBot, which makes sending custom emails more DRY. FrogBot doesn’t ship with an HTML templating engine, so you are free to choose your own.

The following arguments are passed to the generateEmailHTML function:

Argument	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The request that triggered the email, with `req.frogbot`.
`token`	`string`	Always set	The token that is generated for the user to reset their password.
`user`	`unknown`	Always set	The user document that is attempting to reset their password.

generateEmailSubject#forgot-password-generateemailsubject

Similarly to the above generateEmailHTML, you can also customize the subject of the email. The function arguments are the same but you can only return a string - not HTML.

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  // ...
  auth: {
    forgotPassword: {
      generateEmailSubject: ({ user }) => {
        return `Hey ${user.email}, reset your password!`
      },
    },
  },
}

The following arguments are passed to the generateEmailSubject function:

Argument	Type	Default	Description
`req`	`FrogBotRequest`	Always set	The request that triggered the email, with `req.frogbot`.
`token`	`string`	Always set	The password reset token.
`user`	`unknown`	Always set	The user document that is attempting to reset their password.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Email Verification

generateEmailHTML

generateEmailSubject

Forgot Password

generateEmailHTML#forgot-password-generateemailhtml

generateEmailSubject#forgot-password-generateemailsubject

​Email Verification

​generateEmailHTML

​generateEmailSubject

​Forgot Password

​generateEmailHTML#forgot-password-generateemailhtml

​generateEmailSubject#forgot-password-generateemailsubject

Email Verification

generateEmailHTML

generateEmailSubject

Forgot Password

generateEmailHTML#forgot-password-generateemailhtml

generateEmailSubject#forgot-password-generateemailsubject