Skip to main content

Newsletter

Marketing

Email marketing and campaigns for subscriber engagement. Manage subscribers, send campaigns, and track engagement.

Subscriber Management

Import, export, segment

Campaign Builder

Create & send campaigns

Engagement Analytics

Opens, clicks, unsubscribes

GDPR Compliance

Double opt-in, consent

Newsletter vs Email

Sylphx provides two email services for different use cases:

Email (Transactional)

1:1

Password resets, order confirmations, notifications. One email to one recipient.

Newsletter (Marketing)

1:N

Product updates, promotions, content. One campaign to many subscribers.

Subscribe Users

Add subscribers to your newsletter list:

Server-side
import { platform } from '@/lib/platform'

// Subscribe with double opt-in (recommended)
await platform.newsletter.subscribe({
  email: 'user@example.com',
  preferences: ['product_updates', 'promotions'],
  source: 'website',
  metadata: {
    signupPage: '/pricing',
    referrer: req.headers.referer,
  },
})

// Subscriber receives confirmation email
// Clicks link to verify → status becomes 'verified'
PropertyTypeDescription
emailstringSubscriber email address
preferencesstring[]Topics they want to receive
sourcestringSignup source (website, api, import)
metadataobjectCustom metadata for segmentation
doubleOptInbooleanRequire email verification (default: true)

Double Opt-In

Double opt-in is enabled by default for GDPR compliance. Subscribers must verify their email before receiving campaigns.

Manage Preferences

Let subscribers control what they receive:

// Get current preferences
const { preferences, subscribedAt } = await platform.newsletter.getPreferences({
  email: 'user@example.com',
})

// Update preferences
await platform.newsletter.updatePreferences({
  email: 'user@example.com',
  preferences: {
    product_updates: true,
    promotions: false,
    weekly_digest: true,
  },
})

// Unsubscribe completely
await platform.newsletter.unsubscribe({
  email: 'user@example.com',
  reason: 'Too many emails', // Optional feedback
})

Send Campaigns

Create and send email campaigns to your subscribers:

// Send to all subscribers
await platform.newsletter.sendCampaign({
  subject: 'New Feature Launch! 🚀',
  html: '<h1>Introducing Dark Mode</h1><p>...</p>',
  from: 'Updates <updates@myapp.com>',
})

// Send to specific segment
await platform.newsletter.sendCampaign({
  subject: 'Special Offer for Power Users',
  html: offerHtml,
  segment: {
    preferences: ['promotions'],
    metadata: { plan: 'pro' },
  },
})

// Schedule for later
await platform.newsletter.sendCampaign({
  subject: 'Weekly Digest',
  html: digestHtml,
  scheduledAt: nextMonday,
})
PropertyTypeDescription
subjectstringEmail subject line
htmlstringHTML email content
textstringPlain text fallback
segmentobjectTarget specific subscribers
scheduledAtDateSchedule for later (optional)
fromstringSender name and email

Segmentation

Target specific subscribers based on preferences and metadata:

// Segment by preference
const productUsers = await platform.newsletter.getSubscribers({
  segment: {
    preferences: { includes: 'product_updates' },
  },
})

// Segment by metadata
const proUsers = await platform.newsletter.getSubscribers({
  segment: {
    metadata: { plan: 'pro' },
  },
})

// Complex segment
const targetedUsers = await platform.newsletter.getSubscribers({
  segment: {
    preferences: { includes: 'promotions' },
    metadata: { country: 'US' },
    subscribedAfter: '2024-01-01',
  },
})

Campaign Analytics

Track engagement for each campaign:

const stats = await platform.newsletter.getCampaignStats(campaignId)

// {
//   id: 'campaign_abc123',
//   subject: 'New Feature Launch!',
//   sentAt: '2024-01-15T10:00:00Z',
//   recipients: 5420,
//   delivered: 5380,
//   bounced: 40,
//   opened: 2150,
//   clicked: 890,
//   unsubscribed: 12,
//   openRate: 40.0,
//   clickRate: 16.4,
//   unsubscribeRate: 0.2,
// }

Open Rate

Unique opens / delivered

Click Rate

Unique clicks / delivered

Bounce Rate

Bounces / sent

Unsubscribe

Unsubs / delivered

Webhooks

React to newsletter events in real-time:

app/api/webhooks/newsletter/route.ts
import { platform } from '@/lib/platform'
import { NextRequest } from 'next/server'

export async function POST(req: NextRequest) {
  const isValid = await platform.webhooks.verify(req)
  if (!isValid) {
    return new Response('Unauthorized', { status: 401 })
  }

  const event = await req.json()

  switch (event.type) {
    case 'newsletter.subscribed':
      console.log('New subscriber:', event.data.email)
      break
    case 'newsletter.verified':
      // Double opt-in completed
      await welcomeNewSubscriber(event.data.email)
      break
    case 'newsletter.unsubscribed':
      // Handle unsubscribe
      await updateCRM(event.data.email, { newsletter: false })
      break
    case 'newsletter.bounced':
      // Handle bounce
      await markEmailInvalid(event.data.email)
      break
  }

  return new Response('OK')
}
PropertyTypeDescription
newsletter.subscribedeventNew subscriber added
newsletter.verifiedeventDouble opt-in completed
newsletter.unsubscribedeventSubscriber opted out
newsletter.bouncedeventEmail bounced (hard/soft)
newsletter.complainedeventMarked as spam
newsletter.campaign.senteventCampaign finished sending

Best Practices

Use Double Opt-In

GDPR compliant, better deliverability

Segment Your List

Send relevant content to each group

Monitor Bounces

Clean invalid emails regularly

Respect Unsubscribes

Process immediately, no delays