Newsletter

MkSaaS supports Resend, Beehiiv, and MailCheap for managing newsletter subscriptions.

SetupCopy Anchor Link

Choose one provider and configure its environment variables. The template uses Resend by default; switching the newsletter provider does not change the transactional email provider.

RESEND_API_KEY=YOUR-RESEND-API-KEY

export const websiteConfig = {
  // ...other config
  newsletter: {
    enable: true,
    provider: 'resend',
    autoSubscribeAfterSignUp: false,
  },
  // ...other config
}

UsageCopy Anchor Link

Call these functions from server-side code:

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

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

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

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

Email addresses are trimmed and converted to lowercase before they are sent to the provider. When autoSubscribeAfterSignUp is enabled, signup schedules the subscription asynchronously after a short delay so newsletter failures do not block account creation. The welcome email is scheduled separately.

The Resend provider uses the Contacts API without an audience ID. It first tries to create the contact and falls back to updating an existing contact, making repeat subscriptions safe.

With MailCheap, subscribe and isSubscribed return true only for an active contact. If the newsletter requires email confirmation, a new contact can be pending; the current subscription form reports failure until the contact is active, even though MailCheap may already have created it. Confirm the email and check the contact's status in MailCheap before retrying.

MailCheap requests use a 20-second timeout per attempt and follow HTTP redirects with native fetch defaults. Reads retry once for network or response failures or HTTP 5xx; writes do not retry automatically because an unsuccessful response can hide a completed write.

Extending New Newsletter ProvidersCopy Anchor Link

MkSaaS supports extending with new newsletter providers:

1. Create a new file in the src/newsletter/provider directory (e.g., custom-provider.ts).
2. Implement the NewsletterProvider interface:

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;
  }
}

3. Add the provider name to NewsletterConfig['provider'] in src/types/index.d.ts, then register its lazy factory in index.ts:

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

const providerRegistry: Partial<
  Record<NewsletterProviderName, NewsletterProviderFactory>
> = {
  resend: () => new ResendNewsletterProvider(),
  beehiiv: () => new BeehiivNewsletterProvider(),
  mailcheap: () => new MailCheapNewsletterProvider(),
  custom: () => new CustomNewsletterProvider(),
};

FAQCopy Anchor Link

Which provider should I choose?Copy Anchor Link

• Choose Resend if you already use Resend for transactional emails and want a simple, unified solution for both email sending and newsletter management.
• Choose Beehiiv if you need advanced newsletter features like analytics, monetization, referral programs, and growth tools for professional content creators.
• Choose MailCheap if you want to manage contacts in a MailCheap newsletter through the same subscription, unsubscribe, and status APIs.

RESEND_AUDIENCE_ID Environment VariableCopy Anchor Link

As of November 15, 2025, the RESEND_AUDIENCE_ID environment variable has been removed from the template, and the newsletter module no longer needs this environment variable.

Please refer to the documentation for more details: Migrating from Audiences to Segments

Video TutorialCopy Anchor Link

Next StepsCopy Anchor Link