Newsletter

MkSaaS uses Resend for newsletter management. This integration provides a simple yet powerful way to manage newsletter subscriptions for your users.

Setup

Create a Resend account at resend.com
Click API Keys > Create API Key in the dashboard, set the permissions to Send emails or Full access
Create an Audience (or use the default one) in dashboard for newsletter subscribers (get the Audience ID in API view)
Get the API key and Audience ID from the dashboard, and add them to .env file:

.env

RESEND_API_KEY=re_...
RESEND_AUDIENCE_ID=your_audience_id

Update the website config to use Resend for newsletter management:

src/config/website.tsx

export const websiteConfig = {
  // ...other config
  newsletter: {
    provider: 'resend', // Newsletter service provider to use
    autoSubscribeAfterSignUp: false, // Whether to automatically subscribe users after sign up
  },
  // ...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

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

resend.ts

index.ts

types.ts

README.md

This modular structure makes it easy to extend the newsletter system with new providers if needed.

Core Features

Newsletter subscription and unsubscription management
Resend audience integration for user subscribed lists
User subscription status checking
Optional automatic subscription for new users
Modular architecture for easy newsletter service provider switching

Usage

Basic Usage

MkSaaS provides simple utility functions for newsletter management.

import { subscribe, unsubscribe, isSubscribed } from '@/newsletter';

// Subscribe a user to the newsletter
const success = await subscribe('user@example.com');

// Unsubscribe a user from the newsletter
const success = await unsubscribe('user@example.com');

// Check if a user is subscribed
const subscribed = await isSubscribed('user@example.com');

Using with Email Templates

You can combine the newsletter functionality with the email system to send confirmation emails:

import { subscribe } from '@/newsletter';
import { sendEmail } from '@/mail';

export async function subscribeWithConfirmation(email: string) {
  // Subscribe the user to the newsletter
  const success = await subscribe(email);

  if (success) {
    // Send a confirmation email to the user
    await sendEmail({
      to: email,
      template: 'subscribeNewsletter',
      context: {
        name: email.split('@')[0], // Simple name extraction
        unsubscribeUrl: `https://example.com/unsubscribe?email=${encodeURIComponent(email)}`,
      },
    });
  }

  return success;
}

Customization

Creating a Custom Provider

If you need to use a different newsletter service, you can create a custom provider:

Create a new file in the src/newsletter/provider directory as a custom newsletter service provider
Implement the NewsletterProvider interface

src/newsletter/provider/custom-provider.ts

import type {
  CheckSubscribeStatusParams,
  NewsletterProvider,
  SubscribeNewsletterParams,
  UnsubscribeNewsletterParams,
} from '@/newsletter/types';

export class CustomNewsletterProvider implements NewsletterProvider {
  constructor() {
    // Initialize your provider
  }

  public getProviderName(): string {
    return 'CustomProvider';
  }

  async subscribe({ email }: SubscribeNewsletterParams): Promise<boolean> {
    // Implementation for subscribing a user
    return true;
  }

  async unsubscribe({ email }: UnsubscribeNewsletterParams): Promise<boolean> {
    // Implementation for unsubscribing a user
    return true;
  }

  async checkSubscribeStatus({ email }: CheckSubscribeStatusParams): Promise<boolean> {
    // Implementation for checking subscription status
    return true;
  }
}

Update the provider selection logic in index.ts:

src/newsletter/index.ts

import { CustomNewsletterProvider } from './provider/custom-provider';

export const initializeNewsletterProvider = (): NewsletterProvider => {
  if (!newsletterProvider) {
    if (websiteConfig.newsletter.provider === 'resend') {
      newsletterProvider = new ResendProvider();
    } else if (websiteConfig.newsletter.provider === 'custom') {
      newsletterProvider = new CustomNewsletterProvider();
    } else {
      throw new Error(
        `Unsupported newsletter provider: ${websiteConfig.newsletter.provider}`
      );
    }
  }

  return newsletterProvider;
};

Best Practices

Validate Email Addresses: Always validate email addresses before subscribing users
Confirmation Emails: Send confirmation emails when users subscribe to the newsletter
Unsubscribe Link: Always include an unsubscribe link in your newsletter emails
Privacy Policy: Make sure your website has a privacy policy explaining how you use user subscribed data