Newsletters

Experimental. This Module has no test or production evidence recorded yet. Read it, run it locally, and hold off on real Orders. See maturity levels.

The Newsletter Module manages your email subscriber database: the full subscribe, unsubscribe, and resubscribe lifecycle, with tagging and source attribution. It does not send emails itself. Connect an email provider such as Resend by listening to the newsletter.subscribed event and using RESEND_API_KEY in your Integration code. Source: modules/newsletter · npm: @86d-store/newsletter

Installation

npm install @86d-store/newsletter

Add the Module to your store configuration:

import newsletter from "@86d-store/newsletter";
import { createModuleClient } from "@86d-store/core";

const client = createModuleClient([
  newsletter({
    allowResubscribe: "true",
  }),
]);

Configuration

string

default:"\"true\""

When "true", previously unsubscribed (or bounced) addresses can resubscribe. Set to "false" to prevent resubscription; calls to POST /newsletter/subscribe for an unsubscribed address return the subscriber unchanged.

Subscriber lifecycle

subscribe()      → active
unsubscribe()    → unsubscribed  (sets unsubscribedAt timestamp)
resubscribe()    → active        (clears unsubscribedAt, preserves original subscribedAt)

subscribe() is idempotent: calling it for an already-active address returns the existing subscriber unchanged. For an unsubscribed or bounced address, it reactivates the record while preserving the original subscribedAt date.

Store endpoints

Method	Path	Description
`POST`	`/newsletter/subscribe`	Subscribe an email address
`POST`	`/newsletter/unsubscribe`	Unsubscribe an email address

{
  "email": "subscriber_contact_here",
  "source": "footer-form",
  "tags": ["launch-announcement"]
}

All fields except email are optional. Use source to track where signups originate, for example "footer-form", "checkout-upsell", or "product-page". Tags are stored as a JSON array; use them to filter subscribers in Store Admin.

{
  "email": "subscriber_contact_here"
}

The endpoint sets the subscriber’s status to unsubscribed and records an unsubscribedAt timestamp.

Admin endpoints

Method	Path	Description
`GET`	`/admin/newsletter`	List subscribers (filter: `status`, `tag`; paginate: `page`, `limit`)
`DELETE`	`/admin/newsletter/:id/delete`	Permanently delete a subscriber

Param	Type	Default	Description
`status`	`string`		Filter by `active`, `unsubscribed`, or `bounced`
`tag`	`string`		Filter by a specific tag
`page`	`number`	`1`	Page number (1-indexed)
`limit`	`number`	`50`	Results per page (max 100)

Events

Event	Trigger	Payload
`newsletter.subscribed`	New subscriber added or reactivated	`subscriberId`, `email`, `source`
`newsletter.unsubscribed`	Subscriber opts out	`subscriberId`, `email`
`newsletter.campaign.sent`	Campaign sent to subscriber list	`campaignId`, `subject`, `recipientCount`

Listen to newsletter.subscribed to forward new signups to an external email provider:

module.on("newsletter.subscribed", async ({ email, source }) => {
  await resend.contacts.create({
    email,
    audienceId: process.env.RESEND_AUDIENCE_ID,
  });
});

Store components

Use these components in your MDX Template files.

`NewsletterForm`

A full email subscription form with optional name fields and customizable copy.

boolean

default:"false"

Show first and last name input fields alongside the email field.

string

Attribution source recorded on the subscriber (for example "footer-form").

string

default:"\"Subscribe to our newsletter\""

Form heading text.

string

default:"\"Get the latest updates...\""

Descriptive text displayed below the heading.

boolean

default:"false"

Render the form in a compact inline layout.

<NewsletterForm
  showName={true}
  source="footer"
  title="Stay in the loop"
  compact={true}
/>

`NewsletterInline`

Inline newsletter signup intended for embedding in blog posts or product pages. Accepts the same props as NewsletterForm. Use compact={true} for inline placement.

<NewsletterInline compact={true} source="product-page" />

`NewsletterUnsubscribe`

A self-service unsubscribe form for use on your unsubscribe page, typically linked from email footers.

<NewsletterUnsubscribe />

Types

type SubscriberStatus = "active" | "unsubscribed" | "bounced";

interface Subscriber {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  status: SubscriberStatus;
  source?: string;
  tags: string[];
  metadata: Record<string, unknown>;
  subscribedAt: Date;
  unsubscribedAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

Overview

Catalog

Shopping

Customers

Fulfillment

Marketing

Content

Finance

Sales channels

Operations

Newsletters

Installation

Configuration

Subscriber lifecycle

Store endpoints

Admin endpoints

Events

Store components

`NewsletterForm`

`NewsletterInline`

`NewsletterUnsubscribe`

Types

​Installation

​Configuration

​Subscriber lifecycle

​Store endpoints

​Subscribe (POST /newsletter/subscribe)

​Unsubscribe (POST /newsletter/unsubscribe)

​Admin endpoints

​Query parameters for GET /admin/newsletter

​Events

​Store components

​NewsletterForm

​NewsletterInline

​NewsletterUnsubscribe

​Types

​Related pages

Installation

Configuration

Subscriber lifecycle

Store endpoints

Subscribe (`POST /newsletter/subscribe`)

Unsubscribe (`POST /newsletter/unsubscribe`)

Admin endpoints

Query parameters for `GET /admin/newsletter`

Events

Store components

`NewsletterForm`

`NewsletterInline`

`NewsletterUnsubscribe`

Types

Related pages