Email

ShipSaaS supports Resend and Cloudflare Email Service as email providers, utilizing React Email to build email templates.

Setup

ShipSaaS supports Resend and Cloudflare Email Service as built-in providers.

Cloudflare Email

Enable Cloudflare Email Service

Enable the email service in the Cloudflare Dashboard:

• Navigate to Cloudflare Dashboard > Build > Compute > Email Service > Email Sending
• Click Onboard Domain in the upper-right corner, and add and verify the domain you want to send emails from (e.g., example.com).

For more details, see the Cloudflare Email Service Documentation.

Configure Cloudflare API Token

First, complete the Cloudflare configuration. Ensure that your Token contains Account > Email Sending > Edit permissions.

Update Website Configuration

Update your website.ts file to use Cloudflare as the email provider:

Please note that fromEmail is the email address used to send emails, and supportEmail is the email address used to receive support emails (e.g., contact form submissions). The email domain must match the domain verified in the Cloudflare Email Service.

src/config/website.ts

export const websiteConfig = {
  // ...other configurations
  mail: {
    enable: true,                                           // Whether to enable email features
    provider: 'cloudflare',                                 // The email provider to use
    fromEmail: 'YourApp <support@example.com>',             // The email address used to send emails
    supportEmail: 'YourApp <support@example.com>',          // The email address used to receive support emails
  },
  // ...other configurations
}

Resend

Create Resend Account

Create an account at resend.com, and add and verify your domain.

Get API Key

Navigate to Resend Dashboard > API Keys, create a new API key, and ensure that it has permission to send emails.

Configure Environment Variables

Add the following to your .env file:

.env

RESEND_API_KEY=re_xxxxxxxxxxxx

Update Website Configuration

Update your website.ts file to use Resend as the email provider:

src/config/website.ts

export const websiteConfig = {
  // ...other configurations
  mail: {
    enable: true,                                           // Whether to enable email features
    provider: 'resend',                                     // The email provider to use
    fromEmail: 'YourApp <support@example.com>',             // The email address used to send emails
    supportEmail: 'YourApp <support@example.com>',          // The email address used to receive support emails
  },
  // ...other configurations
}

If you are setting up your environment, you can now return to the Environment Configuration document and continue. The remainder of this document can be read later.

Environment configuration set environment variables

---

Customization

Creating New Email Templates

1. Create the email template in the src/mail/templates directory:

src/mail/templates/my-custom-email.tsx

import { EmailLayout } from '../components/email-layout';
import { EmailButton } from '../components/email-button';

interface MyCustomEmailProps {
  username: string;
  actionUrl: string;
}

export function MyCustomEmail({
  username,
  actionUrl,
}: MyCustomEmailProps) {
  return (
    <EmailLayout>
      <p>Hello {username}!</p>
      <p>Thank you for joining our platform. Click the button below to get started.</p>
      <EmailButton href={actionUrl}>Get Started</EmailButton>
    </EmailLayout>
  );
}

2. Add the template name to the EmailTemplate type in src/mail/types.ts:

src/mail/types.ts

export type EmailTemplate =
  | 'forgotPassword'
  | 'verifyEmail'
  | 'subscribeNewsletter'
  | 'contactMessage'
  | 'myCustomEmail'; // ← Add your template name here

3. Register the component in src/mail/render.ts:

src/mail/render.ts

import MyCustomEmail from './templates/my-custom-email';

const EmailTemplates = {
  forgotPassword: ForgotPassword,
  verifyEmail: VerifyEmail,
  subscribeNewsletter: SubscribeNewsletter,
  contactMessage: ContactMessage,
  myCustomEmail: MyCustomEmail, // ← Register here
} as const;

4. Add the email subject in the message file (src/messages/en.ts):

src/messages/en.ts

mail: {
  // ...Existing templates
  myCustomEmail: {
    subject: 'Welcome to Our Platform',
  },
}

5. Preview your template locally:

bun run email:dev

6. Use the template in your code:

await sendEmail({
  to: 'user@example.com',
  template: 'myCustomEmail',
  context: {
    username: 'John',
    actionUrl: 'https://example.com/start',
  },
});

Creating New Email Providers

ShipSaaS supports integrating and extending new email providers:

1. Create a new file in the src/mail/provider directory (e.g., sendgrid.ts).
2. Implement the MailProvider interface defined in src/mail/types.ts. You must implement the following methods:

src/mail/provider/sendgrid.ts

import type {
  MailProvider,
  SendEmailResult,
  SendRawEmailParams,
  SendTemplateParams,
} from '../types';

export class SendGridProvider implements MailProvider {
  getProviderName(): string {
    return 'sendgrid';
  }

  async sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> {
    // Logic to send email using a template
  }

  async sendRawEmail(params: SendRawEmailParams): Promise<SendEmailResult> {
    // Logic to send raw HTML email
  }
}

3. Register the new email provider in the providerRegistry in src/mail/index.ts:

src/mail/index.ts

import { SendGridProvider } from './provider/sendgrid';

const providerRegistry: Record<MailProviderName, ProviderFactory> = {
  resend: () => new ResendProvider(),
  cloudflare: () => new CloudflareProvider(),
  sendgrid: () => new SendGridProvider(),
};

Next Steps

Now that you know how to use email in ShipSaaS, explore these related topics:

• Database - Configure database

• Authentication - Configure authentication

• Newsletter - Configure email list subscription

• Environment Configuration - Configure environment variables

• Authentication

• Payment