Skip to main content
Documentation menu

Newsletter

Configure and manage newsletter subscriptions

MinuteShip supports Resend, Beehiiv, and MailCheap to manage newsletter subscriptions.

Setup

Choose one newsletter provider and configure its environment variables. The template uses Resend by default.

Resend

Create Resend Account

Create a Resend account at resend.com, bind and verify your domain.

Get API Key

Go to Resend Dashboard > API Keys, and create an API key

Configure Environment Variables

Add the following to your .env file:

.env

RESEND_API_KEY=re_xxxxxxxxxxxx

Note: The RESEND_API_KEY is shared between the Email and Newsletter modules when using Resend.

Update Website Configuration

Update the website configuration to use Resend for newsletter management:

src/config/website.ts

export const websiteConfig = {
  // ...other config
  newsletter: {
    enable: true,
    provider: 'resend',
    autoSubscribeAfterSignUp: true, // Auto-subscribe users after registration
  },
  // ...other config
}

Beehiiv

Create Beehiiv Account

Create a Beehiiv account at beehiiv.com.

Get API Key and Publication ID

  • Go to Settings > API to generate an API key.
  • Get your Publication ID from the URL or settings page.

Configure Environment Variables

Add the following to your .env file:

.env

BEEHIIV_API_KEY=your-beehiiv-api-key
BEEHIIV_PUBLICATION_ID=your-beehiiv-publication-id

Update Website Configuration

Update the website configuration to use Beehiiv for newsletter management:

src/config/website.ts

export const websiteConfig = {
  // ...other config
  newsletter: {
    enable: true,
    provider: 'beehiiv',
    autoSubscribeAfterSignUp: true, // Auto-subscribe users after registration
  },
  // ...other config
}

MailCheap

Create a Newsletter

Sign up at mailcheap.ai, create a newsletter, and note its ID or slug.

Get an API Key

Create a Full access key on the dashboard's API keys page. A Signups only key cannot check subscription status or unsubscribe contacts. See the official authentication guide.

Configure Environment Variables

Add the following to your .env file:

.env

MAILCHEAP_API_KEY='mc_your_full_access_api_key'
MAILCHEAP_NEWSLETTER_ID='your-newsletter-id-or-slug'

Both variables are server-side only; do not add a VITE_ prefix.

Update Website Configuration

src/config/website.ts

newsletter: {
  enable: true,
  provider: 'mailcheap',
  autoSubscribeAfterSignUp: false, // Auto-subscribe users after registration
},

To subscribe users after registration, set autoSubscribeAfterSignUp to true once your signup flow obtains their consent.

Note

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

Status Cache

When Cache is enabled, MinuteShip can cache newsletter subscription status checks in Cloudflare KV. Subscribe and unsubscribe operations delete the related cache key so the next status check fetches fresh data.

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 newsletter service provider
  }

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

  async subscribe({ email }: SubscribeNewsletterParams): Promise<boolean> {
    // Subscribe user implementation
    return true;
  }

  async unsubscribe({ email }: UnsubscribeNewsletterParams): Promise<boolean> {
    // Unsubscribe user implementation
    return true;
  }

  async checkSubscribeStatus({ email }: CheckSubscribeStatusParams): Promise<boolean> {
    // Check subscription status implementation
    return true;
  }
}
  1. Register the new provider in the providerRegistry in src/newsletter/index.ts:

src/newsletter/index.ts

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

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

Next Steps

Now that you understand how to use newsletter subscriptions in MinuteShip, you might want to explore these related features: