Kernlift

Newsletter and waitlist

Collect newsletter subscribers and a launch waitlist, sync them to Resend or Beehiiv, invite people in batches and retry failed syncs.

The newsletter module adds public /newsletter, /waitlist and /waitlist/status pages, subscribes every new account, and syncs each subscribe, unsubscribe and invite to Resend or Beehiiv. Sign-ups work without a provider. Syncs stay queued until you connect one.

Before you begin

  • A project that runs locally. See Quick start. The newsletter module is part of the base repository and shows as Waitlist under Content in the admin sidebar.
  • An admin account with newsletter.read to open the pages and newsletter.write to save settings, invite and retry.
  • A Resend API key with full access (so it can create contacts), or a Beehiiv API key and your publication ID.

To give a teammate access, assign the Content Manager role in Overview → Users. The role includes both newsletter permissions and the CMS permissions.

Prepare the newsletter provider

ProviderChoose it for
ResendSync contacts with a full-access key
BeehiivSync subscribers to one publication

Connect a provider

One provider is active at a time.

Open Provider settings

Go to Content → Waitlist (/admin/waitlist) and open the Provider settings tab (/admin/waitlist/settings). The Newsletter provider item on /setup links here too.

Choose the provider and enter credentials

Under Provider, choose Resend or Beehiiv, then fill in its fields:

Use the field mapping in your provider’s guide above.

Keys and the publication id are write-only. A field with a stored value shows Stored. Leave blank to keep it.

Save

Click Save provider settings. The page shows Newsletter provider settings saved. and the next subscribe, unsubscribe or invite uses the provider.

To stop syncing, choose Not configured and save. New syncs then stay queued.

Email Config is separate

The module sends no email and does not read Email Config. A Resend key saved there is used for transactional email only. The newsletter needs its own key here.

Invite from the waitlist

Open Invite Batch

Open the Invite Batch tab (/admin/waitlist/invites).

Invite a batch

Enter a Batch size from 1 to 100 and click Invite batch. The oldest waiting entries move to invited, and each email is synced to the provider.

Tell them

No invitation email is sent. Send one through your own email flow.

Retry queued and failed syncs

Syncs from before the provider was configured are still queued, and syncs the provider rejected are logged as failed.

Open Invite Batch

Open the Invite Batch tab (/admin/waitlist/invites).

Retry

Enter a Batch size under Retry provider sync and click Retry provider sync. The oldest syncs whose latest attempt is pending or failed are retried.

Verify

  1. Open /newsletter and subscribe an address you control.
  2. On Invite Batch, click Retry provider sync.
  3. The log shows a new row with your provider and status success, and the contact appears in the Resend or Beehiiv dashboard.

In the repository, pnpm validate:newsletter runs these flows. To test a real provider, set EXTERNAL_VALIDATE_NEWSLETTER_EMAIL and run EXTERNAL_VALIDATE_STRICT=true pnpm validate:external.

Troubleshooting

Sync logs stay pending

No provider is configured, so nothing was sent. Connect a provider, then run Retry provider sync.

Sync logs show failed

The provider rejected the request, and the log message contains its error. Correct the credentials on Provider settings, then run Retry provider sync.

Saving provider settings shows an error

The message names the problem: Resend needs an API key before it can be selected., Beehiiv needs an API key and a publication id before it can be selected. or The Beehiiv API base URL must be an https URL. Nothing is saved until the form is complete.

A waitlist entry got no invitation email

Invites only change the status and sync the contact. Send the email yourself.

Reference

Next steps