Sending emails

The strategy for sending emails, that every provider has to implement, is extremely simple:

export interface EmailProviderStrategy {
  send: (args: {
    to: string;
    subject: string;
    text: string;
    html?: string;
  }) => Promise<void>;
}

Then, we define a general sendEmail function that you can use as an API for sending emails in your app:

const sendEmail = async <T extends EmailTemplate>({
  to,
  template,
  variables,
}: {
  to: string;
  template: T;
  variables: EmailVariables[T];
}) => {
  const strategy = strategies[provider];
  const { html, text, subject } = await getTemplate({
    id: template,
    variables,
  });
 
  return strategy.send({ to, subject, html, text });
};

The arguments are:

• to: The recipient's email address.
• template: The email template to use.
• variables: The variables to pass to the template.

It returns a promise that resolves when the email is sent successfully. If there is an error, the promise will be rejected with an error message.

To send an email, just invoke the sendEmail with the correct arguments from the server-side of your application:

import { sendEmail } from "@turbostarter/email/server";
 
sendEmail({
  to: "user@example.com",
  template: EmailTemplate.WELCOME,
  variables: {
    name: "John Doe",
  },
});

And that's it! You're ready to send emails in your application 🚀

Authentication emails

TurboStarter comes with a set of pre-configured authentication emails for various purposes, including magic links and password reset functionality.

To handle the sending of these emails at the right time, we use Better Auth Hooks, which trigger when specific authentication events occur.

The logic for determining which email to send is already implemented for you in the packages/auth/src/server.ts file, alongside your authentication configuration:

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    sendResetPassword: async ({ user, url }) =>
      sendEmail({
        to: user.email,
        template: EmailTemplate.RESET_PASSWORD,
        variables: {
          url,
        },
      }),
  },
  emailVerification: {
    sendVerificationEmail: async ({ user, url }) =>
      sendEmail({
        to: user.email,
        template: EmailTemplate.CONFIRM_EMAIL,
        variables: {
          url,
        },
      }),
  },
 
  /* other options */
});

As you can see, the authentication emails are automatically sent when needed (e.g. when user requests password reset or needs to verify their email address).

You can customize authentication templates by modifying them in the packages/email/src/templates directory, or create your own templates for other use cases in your application.