diff --git a/README.md b/README.md index fd21518..fb3fe5a 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,72 @@ Upgrade to premium for more features. Account created: {{formatDate user.createdAt "long"}} ``` +## Configuration + +### Plugin Options + +```typescript +mailingPlugin({ + // Template engine + templateEngine: 'liquidjs', // 'liquidjs' | 'mustache' | 'simple' + + // Custom template renderer + templateRenderer: async (template: string, variables: Record) => { + return yourCustomEngine.render(template, variables) + }, + + // Email settings + defaultFrom: 'noreply@yoursite.com', + defaultFromName: 'Your Site', + retryAttempts: 3, // Number of retry attempts + retryDelay: 300000, // 5 minutes between retries + + // Collection customization + collections: { + templates: 'email-templates', // Custom collection name + emails: 'emails' // Custom collection name + }, + + // Hooks + beforeSend: async (options, email) => { + // Modify email before sending + options.headers = { 'X-Campaign-ID': email.campaignId } + return options + }, + + onReady: async (payload) => { + // Plugin initialization complete + console.log('Mailing plugin ready!') + } +}) +``` + +### Collection Overrides + +Customize collections with access controls and custom fields: + +```typescript +mailingPlugin({ + collections: { + emails: { + access: { + read: ({ req: { user } }) => user?.role === 'admin', + create: ({ req: { user } }) => !!user, + update: ({ req: { user } }) => user?.role === 'admin', + delete: ({ req: { user } }) => user?.role === 'admin' + }, + fields: [ + { + name: 'campaignId', + type: 'text', + admin: { position: 'sidebar' } + } + ] + } + } +}) +``` + ## Requirements - PayloadCMS ^3.45.0 @@ -215,6 +281,87 @@ EMAIL_PASS=your-app-password EMAIL_FROM=noreply@yoursite.com ``` +## API Reference + +### `sendEmail(payload, options)` + +Send emails with full type safety using your generated Payload types. + +```typescript +import { sendEmail } from '@xtr-dev/payload-mailing' +import type { Email } from './payload-types' + +const email = await sendEmail(payload, { + template?: { + slug: string // Template slug + variables: Record // Template variables + }, + data: { + to: string | string[] // Recipients + cc?: string | string[] // CC recipients + bcc?: string | string[] // BCC recipients + subject?: string // Email subject (overrides template) + html?: string // HTML content (overrides template) + text?: string // Text content (overrides template) + scheduledAt?: Date // Schedule for later + priority?: number // Priority (1-5, 1 = highest) + // ... your custom fields from Email collection + }, + collectionSlug?: string // Custom collection name (default: 'emails') +}) +``` + +### `renderTemplate(payload, slug, variables)` + +Render a template without sending an email. + +```typescript +import { renderTemplate } from '@xtr-dev/payload-mailing' + +const result = await renderTemplate( + payload: Payload, + slug: string, + variables: Record +): Promise<{ + html: string // Rendered HTML content + text: string // Rendered text content + subject: string // Rendered subject line +}> +``` + +### Helper Functions + +```typescript +import { processEmails, retryFailedEmails, getMailing } from '@xtr-dev/payload-mailing' + +// Process pending emails manually +await processEmails(payload: Payload): Promise + +// Retry failed emails manually +await retryFailedEmails(payload: Payload): Promise + +// Get mailing service instance +const mailing = getMailing(payload: Payload): MailingService +``` + +### Job Task Types + +```typescript +import type { SendTemplateEmailInput } from '@xtr-dev/payload-mailing' + +interface SendTemplateEmailInput { + templateSlug: string // Template to use + to: string[] // Recipients + cc?: string[] // CC recipients + bcc?: string[] // BCC recipients + variables: Record // Template variables + scheduledAt?: string // ISO date string for scheduling + priority?: number // Priority (1-5) + processImmediately?: boolean // Send immediately (default: false) + [key: string]: any // Your custom email collection fields +} +``` + ## License MIT diff --git a/package.json b/package.json index ab5b1f0..f159ae4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@xtr-dev/payload-mailing", - "version": "0.4.8", + "version": "0.4.9", "description": "Template-based email system with scheduling and job processing for PayloadCMS", "type": "module", "main": "dist/index.js",