payload-mailing/simplified-api-guide.md

Simplified API Guide

The mailing plugin now uses a much simpler, type-safe API that leverages PayloadCMS's existing collection system instead of custom email methods.

New API Approach

✅ Recommended: Use Payload Collections Directly

import { payload, renderTemplate } from '@xtr-dev/payload-mailing'

// 1. Render a template (optional)
const rendered = await renderTemplate(payload, 'welcome-email', {
  name: 'John Doe',
  activationLink: 'https://example.com/activate/123'
})

// 2. Create an email using Payload's collection API
const email = await payload.create({
  collection: 'emails', // Your email collection name
  data: {
    to: ['user@example.com'],
    subject: rendered.subject, // or your own subject
    html: rendered.html,       // or your own HTML
    text: rendered.text,       // or your own text
    // Add any custom fields you've defined in your collection
    priority: 1,
    scheduledAt: new Date('2024-01-01T10:00:00Z'), // Optional scheduling
  }
})

❌ Old API (Removed)

// These methods have been removed to simplify the API
await sendEmail(payload, { to: '...', subject: '...' })
await scheduleEmail(payload, { to: '...', scheduledAt: new Date() })

Benefits of the New Approach

🎯 Type Safety

• Full TypeScript support using your generated Payload types
• IntelliSense for all your custom collection fields
• Compile-time validation of email data

🚀 Flexibility

• Use any fields you've added to your email collection
• Leverage Payload's built-in validation, hooks, and access control
• Full control over email data structure

🧹 Simplicity

• One consistent API (Payload collections) instead of custom methods
• No duplicate type definitions
• Less code to maintain

Usage Examples

Basic Email with Template

import { renderTemplate } from '@xtr-dev/payload-mailing'

const { html, text, subject } = await renderTemplate(payload, 'order-confirmation', {
  orderNumber: '#12345',
  customerName: 'Jane Smith',
  items: [
    { name: 'Product 1', price: 29.99 },
    { name: 'Product 2', price: 49.99 }
  ]
})

await payload.create({
  collection: 'emails',
  data: {
    to: ['customer@example.com'],
    subject,
    html,
    text,
    priority: 2,
    // Add your custom fields
    orderId: '12345',
    customerSegment: 'premium'
  }
})

Bulk Email Creation

const customers = await payload.find({
  collection: 'customers',
  where: { newsletter: { equals: true } }
})

for (const customer of customers.docs) {
  const { html, text, subject } = await renderTemplate(payload, 'newsletter', {
    name: customer.name,
    unsubscribeLink: `https://example.com/unsubscribe/${customer.id}`
  })

  await payload.create({
    collection: 'emails',
    data: {
      to: [customer.email],
      subject,
      html,
      text,
      scheduledAt: new Date('2024-01-15T09:00:00Z'), // Send next week
    }
  })
}

Direct HTML Email (No Template)

await payload.create({
  collection: 'emails',
  data: {
    to: ['admin@example.com'],
    subject: 'System Alert',
    html: '<h1>Server Error</h1><p>Please check the logs immediately.</p>',
    text: 'Server Error: Please check the logs immediately.',
    priority: 10, // High priority
  }
})

Available Helper Functions

import {
  renderTemplate,    // Render email templates with variables
  processEmails,     // Process pending emails manually
  retryFailedEmails, // Retry failed emails
  getMailing        // Get mailing service instance
} from '@xtr-dev/payload-mailing'

Migration Guide

If you were using the old sendEmail/scheduleEmail methods, update your code:

Before:

await sendEmail(payload, {
  templateSlug: 'welcome',
  to: 'user@example.com',
  variables: { name: 'John' }
})

After:

const { html, text, subject } = await renderTemplate(payload, 'welcome', { name: 'John' })

await payload.create({
  collection: 'emails',
  data: {
    to: ['user@example.com'],
    subject,
    html,
    text
  }
})

This new approach gives you the full power and type safety of PayloadCMS while keeping the mailing functionality simple and consistent! 🚀