---

Unsubscribe





)
}
`

The plugin automatically detects templates at email-templates/broadcast-template.tsx.

$3

Convert Lexical content to email-safe HTML:

`typescript
import { convertToEmailSafeHtml } from 'payload-plugin-newsletter/utils'

const html = await convertToEmailSafeHtml(editorState)
`

Validate any HTML for email compatibility:

`typescript
import { validateEmailHtml } from 'payload-plugin-newsletter/utils'

const result = validateEmailHtml(html)
if (!result.valid) {
console.error('Email issues:', result.errors)
}
`

Configuration Options

$3

`typescript
newsletterPlugin({
providers: {
default: 'resend',
resend: {
apiKey: process.env.RESEND_API_KEY,
fromAddress: 'newsletter@yoursite.com',
fromName: 'Your Newsletter',
},
},
})
`

$3

`typescript
newsletterPlugin({
// Subscriber collection slug (default: 'subscribers')
subscribersSlug: 'newsletter-subscribers',

// Email providers
providers: {
default: 'resend',
resend: {
apiKey: process.env.RESEND_API_KEY,
fromAddress: 'newsletter@yoursite.com',
fromName: 'Your Newsletter',
audienceIds: {
en: {
production: 'aud_prod_123',
development: 'aud_dev_123',
},
es: {
production: 'aud_prod_456',
development: 'aud_dev_456',
},
},
},
},

// Magic link authentication
auth: {
enabled: true,
tokenExpiration: '7d', // How long magic links are valid
magicLinkPath: '/newsletter/verify', // Where to redirect for verification
},

// Features
features: {
// Lead magnets (e.g., downloadable PDFs)
leadMagnets: {
enabled: true,
collection: 'media', // Which collection stores your lead magnets
},

// Post-signup surveys
surveys: {
enabled: true,
questions: [
{
id: 'interests',
question: 'What topics interest you?',
type: 'multiselect',
options: ['Tech', 'Business', 'Design'],
},
],
},

// Newsletter scheduling for articles
newsletterScheduling: {
enabled: true,
articlesCollection: 'posts', // Your articles/posts collection
},

// Broadcast management (v0.10.0+)
newsletterManagement: {
enabled: true, // Enables broadcasts collection
},

// UTM tracking
utmTracking: {
enabled: true,
fields: ['source', 'medium', 'campaign', 'content', 'term'],
},
},

// Internationalization
i18n: {
defaultLocale: 'en',
locales: ['en', 'es', 'fr'],
},

// Custom hooks
hooks: {
afterSubscribe: async ({ doc, req }) => {
// Send to analytics, CRM, etc.
console.log('New subscriber:', doc.email)
},
},
})
`

API Endpoints

The plugin adds these endpoints to your application:

$3

Subscribe a new email address

`typescript
// Request
{
"email": "user@example.com",
"name": "John Doe", // optional
"preferences": { // optional
"newsletter": true,
"announcements": false
}
}

// Response
{
"success": true,
"subscriber": { / subscriber object / }
}
`

$3

Verify a magic link token

`typescript
// Request
{
"token": "eyJhbGc..."
}

// Response
{
"success": true,
"subscriber": { / subscriber object / },
"sessionToken": "eyJhbGc..."
}
`

$3

Get or update subscriber preferences (requires magic link auth)

$3

Unsubscribe an email address

$3

Request a magic link for existing subscribers

`typescript
// Request
{
"email": "user@example.com"
}

// Response
{
"success": true,
"message": "Check your email for the sign-in link"
}
`

$3

Get current authenticated subscriber (requires authentication)

`typescript
// Response
{
"success": true,
"subscriber": {
"id": "123",
"email": "user@example.com",
"name": "John Doe",
"status": "active",
"preferences": { / preferences / }
}
}
`

$3

Sign out the current subscriber

`typescript
// Response
{
"success": true,
"message": "Signed out successfully"
}
`

Authentication

The plugin provides complete magic link authentication for subscribers:

$3

Use the useNewsletterAuth hook in your React components:

`tsx
import { useNewsletterAuth } from 'payload-plugin-newsletter/client'

function MyComponent() {
const {
subscriber,
isAuthenticated,
isLoading,
signOut,
refreshAuth
} = useNewsletterAuth()

if (isLoading) return

if (!isAuthenticated) {
return

Please sign in to manage your preferences

}

return (

Welcome {subscriber.email}!

Sign Out

)
}
`

$3

For Next.js applications, use the session utilities:

`typescript
import { requireAuth, getServerSideAuth } from 'payload-plugin-newsletter'

// Protect a page - redirects to /auth/signin if not authenticated
export const getServerSideProps = requireAuth()

// Or with custom logic
export const getServerSideProps = requireAuth(async (context) => {
// Your custom logic here
const data = await fetchData()
return { props: { data } }
})

// Manual authentication check
export const getServerSideProps = async (context) => {
const { subscriber, isAuthenticated } = await getServerSideAuth(context)

if (!isAuthenticated) {
// Handle unauthenticated state
}

return {
props: { subscriber }
}
}
`

$3

1. Subscribe: New users receive a magic link email to verify their email
2. Sign In: Existing subscribers can request a new magic link via /api/newsletter/signin
3. Verify: Clicking the magic link verifies the email and creates a session
4. Session: Sessions are stored in httpOnly cookies (30-day expiry by default)
5. Sign Out: Clears the session cookie

$3

`typescript
newsletterPlugin({
auth: {
enabled: true, // Enable/disable authentication
tokenExpiration: '7d', // Magic link validity
magicLinkPath: '/newsletter/verify', // Verification redirect path
},
// Email templates can be customized
emails: {
magicLink: {
subject: 'Sign in to {{siteName}}',
},
welcome: {
enabled: true,
subject: 'Welcome to {{siteName}}!',
},
signIn: {
subject: 'Sign in to your account',
},
},
})
`

Newsletter Scheduling

If you enable newsletter scheduling, the plugin adds scheduling fields to your articles collection:

`typescript
features: {
newsletterScheduling: {
enabled: true,
articlesCollection: 'articles', // Your existing collection
}
}
`

This adds a "Newsletter Scheduling" group to your articles with:
- Schedule toggle
- Send date/time picker
- Audience segment selection
- Send status tracking

Webhook Configuration (Broadcast)

The plugin supports real-time webhook integration with Broadcast for instant updates:

$3

When configured, the plugin automatically receives and processes:
- Subscriber Events: subscribed, unsubscribed
- Broadcast Events: All status changes (scheduled, in_progress, sent, etc.)

$3

1. Save your Newsletter Settings in the Payload admin to generate a webhook URL
2. Configure in Broadcast:
- Go to your Broadcast dashboard → "Webhook Endpoints"
- Click "Add Webhook Endpoint"
- Paste the webhook URL from Payload
- Select events:
- Subscriber Events: subscribed, unsubscribed
- Broadcast Events: All
- Create the webhook and copy the webhook secret
3. Add the webhook secret to your Newsletter Settings in Payload
4. Save and verify the webhook connection

$3

Webhooks are secured with:
- HMAC-SHA256 signature verification
- Timestamp validation (5-minute window)
- Secret key stored in Newsletter Settings

$3

- Subscriber events update the subscriber's status and metadata
- Broadcast events update the broadcast's status and delivery metrics
- All updates happen in real-time without polling

Note: Email engagement events (opens, clicks) remain in Broadcast for analytics.

Email Providers

$3

Resend is a modern email API for developers.

`typescript
providers: {
default: 'resend',
resend: {
apiKey: process.env.RESEND_API_KEY,
fromAddress: 'hello@yoursite.com',
fromName: 'Your Newsletter',
audienceIds: {
en: {
production: 'your_audience_id',
},
},
},
}
`

$3

Broadcast is a self-hosted email automation platform.

`typescript
providers: {
default: 'broadcast',
broadcast: {
apiUrl: process.env.BROADCAST_API_URL,
token: process.env.BROADCAST_TOKEN,
// Optional: These can be set here as defaults or configured in the admin UI
fromAddress: 'hello@yoursite.com',
fromName: 'Your Newsletter',
replyTo: 'replies@yoursite.com',
},
}
`

Note: Settings configured in the Payload admin UI take precedence over these config values. The config values serve as defaults when settings haven't been configured yet.

TypeScript

The plugin is fully typed. Import types as needed:

`typescript
import type {
NewsletterPluginConfig,
Subscriber,
EmailProvider
} from 'payload-plugin-newsletter/types'
`

Customization

$3

Add custom fields to the subscribers collection:

`typescript
newsletterPlugin({
fields: {
additional: [
{
name: 'company',
type: 'text',
label: 'Company Name',
},
{
name: 'role',
type: 'select',
options: ['developer', 'designer', 'manager'],
},
],
},
})
`

$3

Override the default email templates:

`typescript
import { WelcomeEmail } from './emails/Welcome'

newsletterPlugin({
templates: {
welcome: WelcomeEmail,
},
})
`

$3

You can extend the Broadcasts collection with additional fields and custom email-compatible blocks:

`typescript
import type { Block } from 'payload'

const customBlock: Block = {
slug: 'product-spotlight',
labels: { singular: 'Product Spotlight', plural: 'Product Spotlights' },
fields: [
{ name: 'product', type: 'relationship', relationTo: 'products', required: true },
{ name: 'description', type: 'textarea' }
]
}

newsletterPlugin({
// ... existing config
customizations: {
broadcasts: {
additionalFields: [
{
name: 'slug',
type: 'text',
required: true,
admin: { position: 'sidebar' }
}
],
customBlocks: [customBlock], // Processed server-side for email compatibility
fieldOverrides: {
content: (defaultField) => ({
...defaultField,
admin: {
...defaultField.admin,
description: 'Custom description'
}
})
},
// Email preview customization (v0.20.0+)
emailPreview: {
// Disable default email template wrapping
wrapInTemplate: false,

// Or provide a custom wrapper function
customWrapper: async (content, { subject, preheader }) => {
return


}
}
}
}
})
`

Note: Custom blocks are processed server-side to ensure email compatibility and prevent Next.js serialization errors.

$3

The plugin now supports full customization of email preview rendering. This is useful when you have custom email templates and want the preview to match what's actually sent.

#### Disable Default Template Wrapping

If you're using your own email template system, you can disable the default template wrapping:

`typescript
newsletterPlugin({
customizations: {
broadcasts: {
emailPreview: {
wrapInTemplate: false // Show raw HTML without email template
}
}
}
})
`

#### Custom Email Wrapper

Provide your own wrapper function to match your email service's template:

`typescript
newsletterPlugin({
customizations: {
broadcasts: {
emailPreview: {
customWrapper: async (content, { subject, preheader }) => {
// Return your custom email template
return

${content}




}
}
}
}
})
`

#### Advanced: Using with React Email

If you're using React Email for templates, you can integrate it with the preview:

`typescript
import { render } from '@react-email/render'
import { MyEmailTemplate } from './emails/MyEmailTemplate'

newsletterPlugin({
customizations: {
broadcasts: {
emailPreview: {
customWrapper: async (content, { subject, preheader }) => {
return await render(
subject={subject}
preheader={preheader}
content={content}
/>
)
}
}
}
}
})
`

This ensures your preview exactly matches what subscribers will see.

For complete extensibility documentation, see the Extension Points Guide.

Troubleshooting

$3

"Already subscribed" error
- The email already exists in the subscribers collection
- Check the admin panel to manage existing subscribers

Magic links not working
- Ensure JWT_SECRET is set in your environment variables
- Check that the magicLinkPath matches your frontend route

Emails not sending
- Verify your API keys are correct
- Check the email provider's dashboard for errors
- Ensure from address is verified with your provider

Security

$3

The plugin implements proper access control for all operations:

- Subscriber data: Users can only access and modify their own data via magic link authentication
- Newsletter settings: Only admin users can modify email provider settings and configurations
- API endpoints: All endpoints respect Payload's access control rules

#### Custom Admin Check

The plugin supports multiple admin authentication patterns out of the box:
- user.roles.includes('admin') - Role-based
- user.isAdmin === true - Boolean field
- user.role === 'admin' - Single role field
- user.admin === true - Admin boolean

If your setup uses a different pattern, configure a custom admin check:

`typescript
newsletterPlugin({
access: {
isAdmin: (user) => {
// Your custom logic
return user.customAdminField === true
}
},
// ... other config
})
`

$3

- Always use environment variables for sensitive data (API keys, JWT secrets)
- Enable double opt-in for GDPR compliance
- Configure allowed domains to prevent spam subscriptions
- Set reasonable rate limits for subscriptions per IP

Migration Guide

Coming from another newsletter system? The plugin stores subscribers in a standard Payload collection, making it easy to import existing data:

`typescript
// Example migration script
const existingSubscribers = await getFromOldSystem()

for (const subscriber of existingSubscribers) {
await payload.create({
collection: 'subscribers',
data: {
email: subscriber.email,
name: subscriber.name,
subscriptionStatus: 'active',
// Map other fields as needed
},
})
}
``

Contributing

We welcome contributions! Please see our feedback and contribution guide.

$3

This project uses a developer-controlled release process:
- Version bumps happen locally - You control when and what type
- CI/CD publishes automatically - When it detects a version change
- No bot commits - Your local repo stays in sync

See Release Documentation for details.

License

MIT