LogoMkSaaS Docs

Newsletter

Learn how to set up and use Resend for newsletter management

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

Setup

  1. Create a Resend account at resend.com
  2. Create an audience in Resend for your newsletter subscribers
  3. Get your API key and audience ID from the Resend dashboard
  4. Add the following environment variables:
.env
RESEND_API_KEY=re_...
RESEND_AUDIENCE_ID=your_audience_id
  1. Update the website config to use Resend for newsletters:
src/config/website.tsx
export const websiteConfig = {
  // ...other config
  newsletter: {
    provider: 'resend', // Newsletter 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

Newsletter System Structure

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

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 subscriber lists
  • Subscription status checking
  • Optional automatic subscription for new users
  • Modular architecture for easy provider switching
  • Simple API with strongly typed interfaces

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
  const success = await subscribe(email);
  
  if (success) {
    // Send a confirmation email
    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:

  1. Create a new file in the src/newsletter/provider directory
  2. 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;
  }
}
  1. 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 ResendNewsletterProvider();
    } else if (websiteConfig.newsletter.provider === 'custom') {
      newsletterProvider = new CustomNewsletterProvider();
    } else {
      throw new Error(
        `Unsupported newsletter provider: ${websiteConfig.newsletter.provider}`
      );
    }
  }
 
  return newsletterProvider;
};

Best Practices

  1. Validate Email Addresses: Always validate email addresses before subscribing users
  2. Handle Errors Gracefully: Provide user-friendly error messages when subscription fails
  3. Confirmation Emails: Send confirmation emails when users subscribe
  4. Unsubscribe Link: Always include an unsubscribe link in your newsletter emails
  5. Rate Limiting: Implement rate limiting on your subscription endpoints to prevent abuse
  6. Privacy Policy: Make sure your website has a privacy policy explaining how you use subscriber data

Next Steps

Now that you understand how to work with newsletters in MkSaaS, explore these related integrations:

Email

Configure email services for sending newsletters

Authentication

Set up user authentication with newsletter integration

Analytics

Track newsletter subscription metrics

Storage

Store newsletter data in your database

Table of Contents