LogoMkSaaS Docs

Email

Learn how to set up and use email functionality with Resend and React Email templates

MkSaaS uses Resend for email delivery and React Email for creating beautiful, responsive email templates. This combination provides a modern, developer-friendly way to handle email communications in your application.

Setup

  1. Create a Resend account at resend.com
  2. Get your API key with the permissions to send emails from the dashboard
  3. Add the following environment variables:
.env
RESEND_API_KEY=re_...
  1. Update the website.tsx file to use Resend as the email provider, and set the default sender and recipient email addresse:
src/config/website.tsx
export const websiteConfig = {
  // ...other config
  mail: {
    provider: 'resend', // Email provider to use
    contact: 'contact@example.com', // Default sender and recipient email address
  },
  // ...other config
}

If you are setting up the environment, now you can go back to the Environment Setup guide and continue. The rest of this guide can be read later.

Environment Setup

Set up environment variables

Email System Structure

The email system in MkSaaS is designed with the following components:

index.ts
types.ts
README.md

This modular structure makes it easy to extend the email system with new providers, templates, and components.

Core Features

  • Transactional email sending with Resend integration
  • Beautiful, responsive email templates built with React Email
  • Pre-built templates for verification, password reset, and contact forms
  • Internationalization support with multi-language emails
  • Reusable email components (layout, buttons, etc.)
  • Modular architecture for easy provider switching
  • Developer tools for email preview and testing

Usage

MkSaaS provides a simple email sending utility that supports both template-based emails and raw content:

import { sendEmail } from '@/mail';
 
// Send using a template
await sendEmail({
  to: 'user@example.com',
  template: 'verifyEmail',
  context: {
    name: 'John Doe',
    url: 'https://example.com/verify?token=abc123',
  },
  locale: 'en', // Optional, defaults to config default locale
});
 
// Send a raw email
await sendEmail({
  to: 'user@example.com',
  subject: 'Welcome to our platform',
  html: '<h1>Hello!</h1><p>Welcome to our platform.</p>',
  text: 'Hello! Welcome to our platform.', // Optional
});

Email Templates

MkSaaS includes several pre-built email templates for different use cases:

Email Components

MkSaaS includes reusable email components in the src/mail/components directory to help build consistent email templates:

Customization

Creating Custom Templates

  1. Create a React component in the src/mail/templates directory:
src/mail/templates/my-custom-email.tsx
import { BaseEmailProps } from '@/mail/types';
import { EmailLayout } from '../components/email-layout';
import { EmailButton } from '../components/email-button';
 
interface MyCustomEmailProps extends BaseEmailProps {
  username: string;
  actionUrl: string;
}
 
export function MyCustomEmail({ 
  username, 
  actionUrl, 
  messages, 
  locale 
}: MyCustomEmailProps) {
  return (
    <EmailLayout>
      <p>Hello {username}!</p>
      <p>Thanks for joining our platform. Click the button below to get started.</p>
      <EmailButton href={actionUrl}>Get Started</EmailButton>
    </EmailLayout>
  );
}
  1. Update the EmailTemplates interface in types.ts to include your new template:
src/mail/types.ts
export interface EmailTemplates {
  // ... existing templates
  myCustomEmail: React.ComponentType<MyCustomEmailProps>;
}

  1. Add corresponding subject translations in your i18n messages if needed

  2. Preview your template locally:

pnpm run email
  1. Use the template in your code:
await sendEmail({
  to: 'user@example.com',
  template: 'myCustomEmail',
  context: {
    username: 'John',
    actionUrl: 'https://example.com/start',
  },
});

Creating a New Email Provider

MkSaaS makes it easy to extend the email system with new providers:

  1. Create a new file in the src/mail/provider directory
  2. Implement the MailProvider interface from types.ts
  3. Update the provider selection logic in index.ts

Example implementation for a new provider:

src/mail/provider/my-provider.ts
import { MailProvider, SendEmailResult, SendRawEmailParams, SendTemplateParams } from '@/mail/types';
 
export class MyProvider implements MailProvider {
  constructor() {
    // Initialize your provider
  }
 
  public async sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> {
    // Implementation for sending template emails
  }
 
  public async sendRawEmail(params: SendRawEmailParams): Promise<SendEmailResult> {
    // Implementation for sending raw emails
  }
 
  public getProviderName(): string {
    return 'my-provider';
  }
}

Then update the provider selection in index.ts:

src/mail/index.ts
import { MyProvider } from './provider/my-provider';
 
export const initializeMailProvider = (): MailProvider => {
  if (!mailProvider) {
    if (websiteConfig.mail.provider === 'resend') {
      mailProvider = new ResendMailProvider();
    } else if (websiteConfig.mail.provider === 'custom') {
      mailProvider = new CustomMailProvider();
    } else {
      throw new Error(
        `Unsupported mail provider: ${websiteConfig.mail.provider}`
      );
    }
  }
 
  return mailProvider;
};

Best Practices

  1. Validate Email Addresses: Always validate email addresses before sending emails
  2. Handle Errors Gracefully: Provide user-friendly error messages when email delivery fails

Next Steps

Now that you understand how to work with emails in MkSaaS, you might want to explore these related features:

Database Setup

Configure the database for storing email-related data

Authentication

Set up authentication with email verification

Newsletter

Configure newsletter subscriptions with email

Environment Setup

Set up environment variables for email services

Table of Contents