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
newslettermodule is part of the base repository and shows as Waitlist under Content in the admin sidebar. - An admin account with
newsletter.readto open the pages andnewsletter.writeto 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
| Provider | Choose it for |
|---|---|
| Resend | Sync contacts with a full-access key |
| Beehiiv | Sync 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
- Open
/newsletterand subscribe an address you control. - On Invite Batch, click Retry provider sync.
- 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.