Merge pull request #21 from xtr-dev/dev

Dev

README.md

@@ -6,12 +6,19 @@
 
 ## Features
 
-✅ **Template System**: Create reusable email templates with Handlebars syntax  
-✅ **Outbox Scheduling**: Schedule emails for future delivery  
-✅ **Job Integration**: Automatic processing via PayloadCMS jobs queue  
-✅ **Retry Failed Sends**: Automatic retry mechanism for failed emails  
-✅ **Template Variables**: Dynamic content with validation  
-✅ **Developer API**: Simple methods for sending emails programmatically
+✅ **Template System**: Create reusable email templates with LiquidJS, Mustache, or simple variables
+
+✅ **Type Safety**: Full TypeScript support using your generated Payload types
+
+✅ **Flexible Template Engines**: LiquidJS, Mustache, or bring your own template renderer
+
+✅ **Email Scheduling**: Schedule emails for future delivery using Payload collections
+
+✅ **Job Integration**: Automatic processing via PayloadCMS jobs queue
+
+✅ **Retry Failed Sends**: Automatic retry mechanism for failed emails
+
+✅ **Payload Native**: Uses Payload collections directly - no custom APIs to learn
 
 ## Installation
 
@@ -49,29 +56,50 @@ export default buildConfig({
 })
 ```
 
-### 2. Send emails in your code
+### 2. Send emails with type-safe helper
 
 ```typescript
-import { sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
+import { sendEmail } from '@xtr-dev/payload-mailing'
+import { Email } from './payload-types' // Your generated types
 
-// Send immediately using template slug
-const emailId = await sendEmail(payload, {
-  templateSlug: 'welcome-email',
-  to: 'user@example.com',
-  variables: {
-    firstName: 'John',
-    welcomeUrl: 'https://yoursite.com/welcome'
+// Option 1: Using templates with full type safety
+const email = await sendEmail<Email>(payload, {
+  template: {
+    slug: 'welcome-email',
+    variables: {
+      firstName: 'John',
+      welcomeUrl: 'https://yoursite.com/welcome'
+    }
+  },
+  data: {
+    to: 'user@example.com',
+    // Schedule for later (optional)
+    scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+    priority: 1,
+    // Your custom fields are type-safe!
+    customField: 'your-value',
   }
 })
 
-// Schedule for later
-const scheduledId = await scheduleEmail(payload, {
-  templateSlug: 'reminder-email',
-  to: 'user@example.com',
-  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
-  variables: {
-    eventName: 'Product Launch',
-    eventDate: new Date('2024-01-15')
+// Option 2: Direct HTML email (no template)
+const directEmail = await sendEmail<Email>(payload, {
+  data: {
+    to: ['user@example.com', 'another@example.com'],
+    subject: 'Welcome!',
+    html: '<h1>Welcome John!</h1><p>Thanks for joining!</p>',
+    text: 'Welcome John! Thanks for joining!',
+    // All your custom fields work with TypeScript autocomplete!
+    customField: 'value',
+  }
+})
+
+// Option 3: Use payload.create() directly for full control
+const manualEmail = await payload.create({
+  collection: 'emails',
+  data: {
+    to: ['user@example.com'],
+    subject: 'Hello',
+    html: '<p>Hello World</p>',
   }
 })
 ```
@@ -81,21 +109,72 @@ const scheduledId = await scheduleEmail(payload, {
 ### Plugin Options
 
 ```typescript
-interface MailingPluginConfig {
-  collections?: {
-    templates?: string    // default: 'email-templates'
-    emails?: string      // default: 'emails'
+mailingPlugin({
+  // Template engine (optional)
+  templateEngine: 'liquidjs',  // 'liquidjs' | 'mustache' | 'simple'
+
+  // Custom template renderer (optional)
+  templateRenderer: async (template: string, variables: Record<string, any>) => {
+    return yourCustomEngine.render(template, variables)
+  },
+
+  // Email transport
+  transport: {
+    host: 'smtp.gmail.com',
+    port: 587,
+    auth: { user: '...', pass: '...' }
+  },
+
+  // Collection names (optional)
+  collections: {
+    templates: 'email-templates',  // default
+    emails: 'emails'              // default
+  },
+
+  // Sending options
+  defaultFrom: 'noreply@yoursite.com',
+  defaultFromName: 'Your Site',
+  retryAttempts: 3,              // default
+  retryDelay: 300000,            // 5 minutes (default)
+
+  // Advanced options
+  emailWrapper: (email) => ({    // optional layout wrapper
+    ...email,
+    html: `<html><body>${email.html}</body></html>`
+  }),
+  richTextEditor: lexicalEditor(),  // optional custom editor
+  onReady: async (payload) => {     // optional initialization hook
+    console.log('Mailing plugin ready!')
   }
-  defaultFrom?: string
-  transport?: Transporter | MailingTransportConfig
-  queue?: string         // default: 'default'
-  retryAttempts?: number // default: 3
-  retryDelay?: number    // default: 300000 (5 minutes)
-  emailWrapper?: EmailWrapperHook // optional email layout wrapper
-  richTextEditor?: RichTextField['editor'] // optional custom rich text editor
-  onReady?: (payload: any) => Promise<void> // optional callback after plugin initialization
-  initOrder?: 'before' | 'after' // default: 'before'
-}
+})
+```
+
+### Template Engine Options
+
+Choose your preferred template engine:
+
+```typescript
+// LiquidJS (default) - Modern syntax with logic
+mailingPlugin({
+  templateEngine: 'liquidjs'  // {% if user.isPremium %}Premium!{% endif %}
+})
+
+// Mustache - Logic-less templates
+mailingPlugin({
+  templateEngine: 'mustache'  // {{#user.isPremium}}Premium!{{/user.isPremium}}
+})
+
+// Simple variable replacement
+mailingPlugin({
+  templateEngine: 'simple'    // Just {{variable}} replacement
+})
+
+// Custom template renderer
+mailingPlugin({
+  templateRenderer: async (template, variables) => {
+    return handlebars.compile(template)(variables)  // Bring your own!
+  }
+})
 ```
 
 ### Transport Configuration
@@ -473,73 +552,127 @@ mailingPlugin({
 })
 ```
 
-## Handlebars Helpers
+## Template Syntax Reference
 
-The plugin includes several built-in helpers:
+Depending on your chosen template engine, you can use different syntax:
 
-- `{{formatDate date 'short'}}` - Format dates (short, long, or default)
-- `{{formatCurrency amount 'USD'}}` - Format currency
-- `{{capitalize string}}` - Capitalize first letter
-- `{{#ifEquals value1 value2}}...{{/ifEquals}}` - Conditional equality
+### LiquidJS (Default)
+- Variables: `{{ user.name }}`
+- Logic: `{% if user.isPremium %}Premium content{% endif %}`
+- Loops: `{% for item in items %}{{ item.name }}{% endfor %}`
+- Filters: `{{ amount | formatCurrency }}`, `{{ date | formatDate: "short" }}`
 
-## API Methods
+### Mustache
+- Variables: `{{ user.name }}`
+- Logic: `{{#user.isPremium}}Premium content{{/user.isPremium}}`
+- Loops: `{{#items}}{{ name }}{{/items}}`
+- No built-in filters (use variables with pre-formatted data)
 
-### sendEmail(payload, options)
+### Simple
+- Variables only: `{{ user.name }}`, `{{ amount }}`, `{{ date }}`
 
-Send an email immediately:
+### Built-in Filters (LiquidJS only)
+- `formatDate` - Format dates: `{{ createdAt | formatDate: "short" }}`
+- `formatCurrency` - Format currency: `{{ amount | formatCurrency: "USD" }}`
+- `capitalize` - Capitalize first letter: `{{ name | capitalize }}`
+
+## Available Helper Functions
 
 ```typescript
-const emailId = await sendEmail(payload, {
-  templateSlug: 'order-confirmation', // optional - use template slug
-  to: ['customer@example.com'],       // string or array of emails
-  cc: ['manager@example.com'],        // optional - array of emails
-  bcc: ['archive@example.com'],       // optional - array of emails  
-  from: 'orders@yoursite.com',        // optional, uses default
-  replyTo: 'support@yoursite.com',    // optional
-  subject: 'Custom subject',          // required if no template
-  html: '<h1>Custom HTML</h1>',       // required if no template
-  text: 'Custom text version',        // optional
-  variables: {                        // template variables
-    orderNumber: '12345',
-    customerName: 'John Doe'
-  },
-  priority: 1                         // optional, 1-10 (1 = highest)
+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'
+
+// Render a template
+const { html, text, subject } = await renderTemplate(payload, 'welcome', {
+  name: 'John',
+  activationUrl: 'https://example.com/activate'
 })
+
+// Process emails manually
+await processEmails(payload)
+
+// Retry failed emails
+await retryFailedEmails(payload)
 ```
 
-### scheduleEmail(payload, options)
+## PayloadCMS Task Integration
 
-Schedule an email for later delivery:
+The plugin provides a ready-to-use PayloadCMS task for queuing template emails:
+
+### 1. Add the task to your Payload config
 
 ```typescript
-const emailId = await scheduleEmail(payload, {
-  templateSlug: 'newsletter',
-  to: ['user1@example.com', 'user2@example.com'],
-  scheduledAt: new Date('2024-01-15T10:00:00Z'),
-  variables: {
-    month: 'January',
-    highlights: ['Feature A', 'Feature B']
+import { buildConfig } from 'payload/config'
+import { sendTemplateEmailTask } from '@xtr-dev/payload-mailing'
+
+export default buildConfig({
+  // ... your config
+  jobs: {
+    tasks: [
+      sendTemplateEmailTask,
+      // ... your other tasks
+    ]
   }
 })
 ```
 
-### processEmails(payload)
-
-Manually process pending emails:
+### 2. Queue emails from your code
 
 ```typescript
-import { processEmails } from '@xtr-dev/payload-mailing'
-await processEmails(payload)
+import type { SendTemplateEmailInput } from '@xtr-dev/payload-mailing'
+
+// Queue a template email
+const result = await payload.jobs.queue({
+  task: 'send-template-email',
+  input: {
+    templateSlug: 'welcome-email',
+    to: ['user@example.com'],
+    cc: ['manager@example.com'],
+    variables: {
+      firstName: 'John',
+      activationUrl: 'https://example.com/activate/123'
+    },
+    priority: 1,
+    // Add any custom fields from your email collection
+    customField: 'value'
+  } as SendTemplateEmailInput
+})
+
+// Queue a scheduled email
+await payload.jobs.queue({
+  task: 'send-template-email',
+  input: {
+    templateSlug: 'reminder-email',
+    to: ['user@example.com'],
+    variables: { eventName: 'Product Launch' },
+    scheduledAt: new Date('2024-01-15T10:00:00Z').toISOString(),
+    priority: 3
+  }
+})
 ```
 
-### retryFailedEmails(payload)
+### 3. Use in admin panel workflows
 
-Manually retry failed emails:
+The task can also be triggered from the Payload admin panel with a user-friendly form interface that includes:
+- Template slug selection
+- Email recipients (to, cc, bcc)
+- Template variables as JSON
+- Optional scheduling
+- Priority setting
+- Any custom fields you've added to your email collection
 
-```typescript
-import { retryFailedEmails } from '@xtr-dev/payload-mailing'
-await retryFailedEmails(payload)
-```
+### Task Benefits
+
+- ✅ **Easy Integration**: Just add to your tasks array
+- ✅ **Type Safety**: Full TypeScript support with `SendTemplateEmailInput`
+- ✅ **Admin UI**: Ready-to-use form interface
+- ✅ **Flexible**: Supports all your custom email collection fields
+- ✅ **Error Handling**: Comprehensive error reporting
+- ✅ **Queue Management**: Leverage Payload's job queue system
 
 ## Job Processing
 
@@ -716,35 +849,134 @@ import {
 } from '@xtr-dev/payload-mailing'
 ```
 
+## API Reference
+
+### `sendEmail<T>(payload, options)`
+
+Type-safe email sending with automatic template rendering and validation.
+
+```typescript
+import { sendEmail } from '@xtr-dev/payload-mailing'
+import { Email } from './payload-types'
+
+const email = await sendEmail<Email>(payload, {
+  template: {
+    slug: 'template-slug',
+    variables: { /* template variables */ }
+  },
+  data: {
+    to: 'user@example.com',
+    // Your custom fields are type-safe here!
+  }
+})
+```
+
+**Type Parameters:**
+- `T extends BaseEmailData` - Your generated Email type for full type safety
+
+**Options:**
+- `template.slug` - Template slug to render
+- `template.variables` - Variables to pass to template
+- `data` - Email data (merged with template output)
+- `collectionSlug` - Custom collection name (defaults to 'emails')
+
+### `renderTemplate(payload, slug, variables)`
+
+Render an email template without sending.
+
+```typescript
+const { html, text, subject } = await renderTemplate(
+  payload,
+  'welcome-email',
+  { name: 'John' }
+)
+```
+
+### Helper Functions
+
+- `getMailing(payload)` - Get mailing context
+- `processEmails(payload)` - Manually trigger email processing
+- `retryFailedEmails(payload)` - Manually retry failed emails
+
+## Migration Guide (v0.0.x → v0.1.0)
+
+**🚨 BREAKING CHANGES**: The API has been simplified to use Payload collections directly.
+
+### Before (v0.0.x)
+```typescript
+import { sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
+
+// Old way
+const emailId = await sendEmail(payload, {
+  templateSlug: 'welcome',
+  to: 'user@example.com',
+  variables: { name: 'John' }
+})
+
+const scheduledId = await scheduleEmail(payload, {
+  templateSlug: 'reminder',
+  to: 'user@example.com',
+  scheduledAt: new Date('2024-01-15T10:00:00Z'),
+  variables: { eventName: 'Launch' }
+})
+```
+
+### After (v0.1.0+)
+```typescript
+import { renderTemplate } from '@xtr-dev/payload-mailing'
+
+// New way - render template first
+const { html, text, subject } = await renderTemplate(payload, 'welcome', {
+  name: 'John'
+})
+
+// Then create email using Payload collections (full type safety!)
+const email = await payload.create({
+  collection: 'emails',
+  data: {
+    to: ['user@example.com'],
+    subject,
+    html,
+    text,
+    // For scheduling
+    scheduledAt: new Date('2024-01-15T10:00:00Z'),
+    // Add any custom fields from your collection
+    customField: 'value',
+  }
+})
+```
+
+### Benefits of Migration
+- ✅ **Full TypeScript support** with your generated Payload types
+- ✅ **Use any custom fields** you add to your email collection
+- ✅ **Leverage Payload's features**: validation, hooks, access control
+- ✅ **One consistent API** - just use `payload.create()`
+- ✅ **No wrapper methods** - direct access to Payload's power
+
 ## Recent Changes
 
-### v0.0.x (Latest)
+### v0.1.0 (Latest - Breaking Changes)
 
-**🔄 Breaking Changes:**
-- Removed email layouts system in favor of `emailWrapper` hook for better flexibility
-- Email fields (`to`, `cc`, `bcc`) now use `hasMany: true` for proper array handling  
-- Templates now use slug-based lookup instead of ID-based for developer-friendly API
-- Email collection renamed from "outbox" to "emails"
-- Unified job processing: single `process-email-queue` job handles both pending and failed emails
+**🚀 Major API Simplification:**
+- **REMOVED**: `sendEmail()` and `scheduleEmail()` wrapper methods
+- **REMOVED**: `SendEmailOptions` custom types
+- **ADDED**: Direct Payload collection usage with full type safety
+- **ADDED**: `renderTemplate()` helper for template rendering
+- **ADDED**: Support for LiquidJS, Mustache, and custom template engines
+- **IMPROVED**: Webpack compatibility with proper dynamic imports
 
-**✨ New Features:**
-- Rich text editor with automatic HTML/text conversion
-- Template slugs for easier template reference
-- `emailWrapper` hook for consistent email layouts
-- Custom rich text editor configuration support
-- Initialization hooks (`onReady`, `initOrder`) for better plugin lifecycle control
-- Improved Handlebars variable interpolation with defensive programming
+**Template Engine Enhancements:**
+- **NEW**: LiquidJS support (default) with modern syntax and logic
+- **NEW**: Mustache support for logic-less templates
+- **NEW**: Custom template renderer hook for maximum flexibility
+- **NEW**: Simple variable replacement as fallback
+- **FIXED**: All webpack compatibility issues resolved
 
-**🐛 Bug Fixes:**
-- Fixed text version uppercase conversion in headings
-- Fixed Handlebars interpolation issues in text version
-- Improved plugin initialization order to prevent timing issues
-
-**💡 Improvements:**
-- Better admin UI with proper array input controls
-- More robust error handling and logging
-- Enhanced TypeScript definitions
-- Simplified template creation workflow
+**Developer Experience:**
+- **IMPROVED**: Full TypeScript inference using generated Payload types
+- **IMPROVED**: Comprehensive migration guide and documentation
+- **IMPROVED**: Better error handling and async patterns
+- **SIMPLIFIED**: Cleaner codebase with fewer abstractions
 
 ## License
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/payload-mailing",
-  "version": "0.0.8",
+  "version": "0.1.5",
   "description": "Template-based email system with scheduling and job processing for PayloadCMS",
   "type": "module",
   "main": "dist/index.js",
@@ -47,9 +47,12 @@
     "payload": "^3.37.0"
   },
   "dependencies": {
-    "handlebars": "^4.7.8",
     "nodemailer": "^6.9.8"
   },
+  "optionalDependencies": {
+    "liquidjs": "^10.19.0",
+    "mustache": "^4.2.0"
+  },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@payloadcms/db-mongodb": "^3.37.0",

pnpm-lock.yaml

@@ -8,9 +8,6 @@ importers:
 
   .:
     dependencies:
-      handlebars:
-        specifier: ^4.7.8
-        version: 4.7.8
       nodemailer:
         specifier: ^6.9.8
         version: 6.10.1
@@ -117,6 +114,13 @@ importers:
       vitest:
         specifier: ^3.1.2
         version: 3.2.4(@types/debug@4.1.12)(@types/node@22.18.1)(sass@1.77.4)(tsx@4.20.3)
+    optionalDependencies:
+      liquidjs:
+        specifier: ^10.19.0
+        version: 10.21.1
+      mustache:
+        specifier: ^4.2.0
+        version: 4.2.0
 
 packages:
 
@@ -2637,6 +2641,10 @@ packages:
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
+  commander@10.0.1:
+    resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==}
+    engines: {node: '>=14'}
+
   commander@2.20.3:
     resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
 
@@ -3540,11 +3548,6 @@ packages:
     resolution: {integrity: sha512-mS1lbMsxgQj6hge1XZ6p7GPhbrtFwUFYi3wRzXAC/FmYnyXMTvvI3td3rjmQ2u8ewXueaSvRPWaEcgVVOT9Jnw==}
     engines: {node: ^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0}
 
-  handlebars@4.7.8:
-    resolution: {integrity: sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==}
-    engines: {node: '>=0.4.7'}
-    hasBin: true
-
   has-bigints@1.1.0:
     resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==}
     engines: {node: '>= 0.4'}
@@ -3922,6 +3925,11 @@ packages:
   lines-and-columns@1.2.4:
     resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
 
+  liquidjs@10.21.1:
+    resolution: {integrity: sha512-NZXmCwv3RG5nire3fmIn9HsOyJX3vo+ptp0yaXUHAMzSNBhx74Hm+dAGJvscUA6lNqbLuYfXgNavRQ9UbUJhQQ==}
+    engines: {node: '>=14'}
+    hasBin: true
+
   locate-path@5.0.0:
     resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
     engines: {node: '>=8'}
@@ -4186,6 +4194,10 @@ packages:
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
+  mustache@4.2.0:
+    resolution: {integrity: sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==}
+    hasBin: true
+
   nanoid@3.3.11:
     resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -4202,9 +4214,6 @@ packages:
   natural-compare@1.4.0:
     resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
 
-  neo-async@2.6.2:
-    resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
-
   new-find-package-json@2.0.0:
     resolution: {integrity: sha512-lDcBsjBSMlj3LXH2v/FW3txlh2pYTjmbOXPYJD93HI5EwuLzI11tdHSIpUMmfq/IOsldj4Ps8M8flhm+pCK4Ew==}
     engines: {node: '>=12.22.0'}
@@ -5170,11 +5179,6 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
-  uglify-js@3.19.3:
-    resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==}
-    engines: {node: '>=0.8.0'}
-    hasBin: true
-
   uint8array-extras@1.5.0:
     resolution: {integrity: sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A==}
     engines: {node: '>=18'}
@@ -5377,9 +5381,6 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
-  wordwrap@1.0.0:
-    resolution: {integrity: sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==}
-
   wrap-ansi@7.0.0:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
@@ -8540,6 +8541,9 @@ snapshots:
 
   colorette@2.0.20: {}
 
+  commander@10.0.1:
+    optional: true
+
   commander@2.20.3: {}
 
   commander@6.2.1: {}
@@ -9689,15 +9693,6 @@ snapshots:
 
   graphql@16.11.0: {}
 
-  handlebars@4.7.8:
-    dependencies:
-      minimist: 1.2.8
-      neo-async: 2.6.2
-      source-map: 0.6.1
-      wordwrap: 1.0.0
-    optionalDependencies:
-      uglify-js: 3.19.3
-
   has-bigints@1.1.0: {}
 
   has-flag@4.0.0: {}
@@ -10044,6 +10039,11 @@ snapshots:
 
   lines-and-columns@1.2.4: {}
 
+  liquidjs@10.21.1:
+    dependencies:
+      commander: 10.0.1
+    optional: true
+
   locate-path@5.0.0:
     dependencies:
       p-locate: 4.1.0
@@ -10431,6 +10431,9 @@ snapshots:
 
   ms@2.1.3: {}
 
+  mustache@4.2.0:
+    optional: true
+
   nanoid@3.3.11: {}
 
   napi-postinstall@0.3.3: {}
@@ -10439,8 +10442,6 @@ snapshots:
 
   natural-compare@1.4.0: {}
 
-  neo-async@2.6.2: {}
-
   new-find-package-json@2.0.0:
     dependencies:
       debug: 4.4.1
@@ -11571,9 +11572,6 @@ snapshots:
 
   typescript@5.9.2: {}
 
-  uglify-js@3.19.3:
-    optional: true
-
   uint8array-extras@1.5.0: {}
 
   unbox-primitive@1.1.0:
@@ -11820,8 +11818,6 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
-  wordwrap@1.0.0: {}
-
   wrap-ansi@7.0.0:
     dependencies:
       ansi-styles: 4.3.0

src/index.ts

@@ -11,13 +11,17 @@ export { MailingService } from './services/MailingService.js'
 export { default as EmailTemplates, createEmailTemplatesCollection } from './collections/EmailTemplates.js'
 export { default as Emails } from './collections/Emails.js'
 
-// Jobs are integrated into the plugin configuration
+// Jobs (includes the send email task)
+export { mailingJobs, sendEmailJob } from './jobs/index.js'
+export type { SendEmailTaskInput } from './jobs/sendEmailTask.js'
 
 // Utility functions for developers
 export {
   getMailing,
-  sendEmail,
-  scheduleEmail,
+  renderTemplate,
   processEmails,
   retryFailedEmails,
+  sendEmail,
+  type BaseEmailData,
+  type SendEmailOptions,
 } from './utils/helpers.js'

src/jobs/index.ts

@@ -1,19 +1,35 @@
 import { processEmailsJob, ProcessEmailsJobData } from './processEmailsJob.js'
+import { sendEmailJob } from './sendEmailTask.js'
 import { MailingService } from '../services/MailingService.js'
 
-export const createMailingJobs = (mailingService: MailingService): any[] => {
-  return [
-    {
-      slug: 'processEmails',
-      handler: async ({ job, req }: { job: any; req: any }) => {
-        return processEmailsJob(
-          job as { data: ProcessEmailsJobData },
-          { req, mailingService }
-        )
-      },
-      interfaceName: 'ProcessEmailsJob',
-    },
-  ]
-}
+export const mailingJobs = [
+  {
+    slug: 'processEmails',
+    handler: async ({ job, req }: { job: any; req: any }) => {
+      // Get mailing context from payload
+      const payload = (req as any).payload
+      const mailingContext = payload.mailing
+      if (!mailingContext) {
+        throw new Error('Mailing plugin not properly initialized')
+      }
 
-export * from './processEmailsJob.js'
+      // Use the existing mailing service from context
+      await processEmailsJob(
+        job as { data: ProcessEmailsJobData },
+        { req, mailingService: mailingContext.service }
+      )
+
+      return {
+        output: {
+          success: true,
+          message: 'Email queue processing completed successfully'
+        }
+      }
+    },
+    interfaceName: 'ProcessEmailsJob',
+  },
+  sendEmailJob,
+]
+
+export * from './processEmailsJob.js'
+export * from './sendEmailTask.js'

src/jobs/processEmailsJob.ts

@@ -2,7 +2,7 @@ import type { PayloadRequest } from 'payload'
 import { MailingService } from '../services/MailingService.js'
 
 export interface ProcessEmailsJobData {
-  type: 'process-emails' | 'retry-failed'
+  // No type needed - always processes both pending and failed emails
 }
 
 export const processEmailsJob = async (
@@ -10,18 +10,19 @@ export const processEmailsJob = async (
   context: { req: PayloadRequest; mailingService: MailingService }
 ) => {
   const { mailingService } = context
-  const { type } = job.data
 
   try {
-    if (type === 'process-emails') {
-      await mailingService.processEmails()
-      console.log('Email processing completed successfully')
-    } else if (type === 'retry-failed') {
-      await mailingService.retryFailedEmails()
-      console.log('Failed email retry completed successfully')
-    }
+    console.log('🔄 Processing email queue (pending + failed emails)...')
+
+    // Process pending emails first
+    await mailingService.processEmails()
+
+    // Then retry failed emails
+    await mailingService.retryFailedEmails()
+
+    console.log('✅ Email queue processing completed successfully (pending and failed emails)')
   } catch (error) {
-    console.error(`${type} job failed:`, error)
+    console.error('❌ Email queue processing failed:', error)
     throw error
   }
 }
@@ -29,7 +30,6 @@ export const processEmailsJob = async (
 export const scheduleEmailsJob = async (
   payload: any,
   queueName: string,
-  jobType: 'process-emails' | 'retry-failed',
   delay?: number
 ) => {
   if (!payload.jobs) {
@@ -41,10 +41,10 @@ export const scheduleEmailsJob = async (
     await payload.jobs.queue({
       queue: queueName,
       task: 'processEmails',
-      input: { type: jobType },
+      input: {},
       waitUntil: delay ? new Date(Date.now() + delay) : undefined,
     })
   } catch (error) {
-    console.error(`Failed to schedule ${jobType} job:`, error)
+    console.error('Failed to schedule email processing job:', error)
   }
 }

src/jobs/sendEmailTask.ts

@@ -0,0 +1,178 @@
+import { sendEmail, type BaseEmailData } from '../utils/helpers.js'
+
+export interface SendEmailTaskInput {
+  // Template mode fields
+  templateSlug?: string
+  variables?: Record<string, any>
+
+  // Direct email mode fields
+  subject?: string
+  html?: string
+  text?: string
+
+  // Common fields
+  to: string | string[]
+  cc?: string | string[]
+  bcc?: string | string[]
+  scheduledAt?: string // ISO date string
+  priority?: number
+
+  // Allow any additional fields that users might have in their email collection
+  [key: string]: any
+}
+
+export const sendEmailJob = {
+  slug: 'send-email',
+  label: 'Send Email',
+  inputSchema: [
+    {
+      name: 'templateSlug',
+      type: 'text' as const,
+      label: 'Template Slug',
+      admin: {
+        description: 'Use a template (leave empty for direct email)',
+        condition: (data: any) => !data.subject && !data.html
+      }
+    },
+    {
+      name: 'variables',
+      type: 'json' as const,
+      label: 'Template Variables',
+      admin: {
+        description: 'JSON object with variables for template rendering',
+        condition: (data: any) => Boolean(data.templateSlug)
+      }
+    },
+    {
+      name: 'subject',
+      type: 'text' as const,
+      label: 'Subject',
+      admin: {
+        description: 'Email subject (required if not using template)',
+        condition: (data: any) => !data.templateSlug
+      }
+    },
+    {
+      name: 'html',
+      type: 'textarea' as const,
+      label: 'HTML Content',
+      admin: {
+        description: 'HTML email content (required if not using template)',
+        condition: (data: any) => !data.templateSlug
+      }
+    },
+    {
+      name: 'text',
+      type: 'textarea' as const,
+      label: 'Text Content',
+      admin: {
+        description: 'Plain text email content (optional)',
+        condition: (data: any) => !data.templateSlug
+      }
+    },
+    {
+      name: 'to',
+      type: 'text' as const,
+      required: true,
+      label: 'To (Email Recipients)',
+      admin: {
+        description: 'Comma-separated list of email addresses'
+      }
+    },
+    {
+      name: 'cc',
+      type: 'text' as const,
+      label: 'CC (Carbon Copy)',
+      admin: {
+        description: 'Optional comma-separated list of CC email addresses'
+      }
+    },
+    {
+      name: 'bcc',
+      type: 'text' as const,
+      label: 'BCC (Blind Carbon Copy)',
+      admin: {
+        description: 'Optional comma-separated list of BCC email addresses'
+      }
+    },
+    {
+      name: 'scheduledAt',
+      type: 'date' as const,
+      label: 'Schedule For',
+      admin: {
+        description: 'Optional date/time to schedule email for future delivery'
+      }
+    },
+    {
+      name: 'priority',
+      type: 'number' as const,
+      label: 'Priority',
+      min: 1,
+      max: 10,
+      defaultValue: 5,
+      admin: {
+        description: 'Email priority (1 = highest, 10 = lowest)'
+      }
+    }
+  ],
+  handler: async ({ input, payload }: any) => {
+    // Cast input to our expected type
+    const taskInput = input as SendEmailTaskInput
+
+    try {
+      // Prepare options for sendEmail based on task input
+      const sendEmailOptions: any = {
+        data: {}
+      }
+
+      // If using template mode
+      if (taskInput.templateSlug) {
+        sendEmailOptions.template = {
+          slug: taskInput.templateSlug,
+          variables: taskInput.variables || {}
+        }
+      }
+
+      // Build data object from task input
+      const dataFields = ['to', 'cc', 'bcc', 'subject', 'html', 'text', 'scheduledAt', 'priority']
+      const additionalFields: string[] = []
+
+      // Copy standard fields
+      dataFields.forEach(field => {
+        if (taskInput[field] !== undefined) {
+          sendEmailOptions.data[field] = taskInput[field]
+        }
+      })
+
+      // Copy any additional custom fields
+      Object.keys(taskInput).forEach(key => {
+        if (!['templateSlug', 'variables', ...dataFields].includes(key)) {
+          sendEmailOptions.data[key] = taskInput[key]
+          additionalFields.push(key)
+        }
+      })
+
+      // Use the sendEmail helper to create the email
+      const email = await sendEmail<BaseEmailData>(payload, sendEmailOptions)
+
+      return {
+        output: {
+          success: true,
+          emailId: email.id,
+          message: `Email queued successfully with ID: ${email.id}`,
+          mode: taskInput.templateSlug ? 'template' : 'direct',
+          templateSlug: taskInput.templateSlug || null,
+          subject: email.subject,
+          recipients: Array.isArray(email.to) ? email.to.length : 1,
+          scheduledAt: email.scheduledAt || null
+        }
+      }
+
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      throw new Error(`Failed to queue email: ${errorMessage}`)
+    }
+  }
+}
+
+export default sendEmailJob

src/plugin.ts

@@ -3,53 +3,8 @@ import { MailingPluginConfig, MailingContext } from './types/index.js'
 import { MailingService } from './services/MailingService.js'
 import { createEmailTemplatesCollection } from './collections/EmailTemplates.js'
 import Emails from './collections/Emails.js'
+import { mailingJobs, scheduleEmailsJob } from './jobs/index.js'
 
-// Helper function to schedule the email processing job
-async function scheduleEmailProcessingJob(payload: any, queueName: string, delayMs: number = 60000): Promise<boolean> {
-  if (!queueName || typeof queueName !== 'string') {
-    throw new Error('Invalid queueName: must be a non-empty string')
-  }
-
-  const jobSlug = 'process-email-queue'
-
-  // Check if there's already a scheduled job for this task
-  const existingJobs = await payload.find({
-    collection: 'payload-jobs',
-    where: {
-      and: [
-        {
-          taskSlug: {
-            equals: jobSlug,
-          },
-        },
-        {
-          hasCompleted: {
-            equals: false,
-          },
-        },
-      ],
-    },
-    limit: 1,
-  })
-
-  // If no existing job, schedule a new one
-  if (existingJobs.docs.length === 0) {
-    await payload.create({
-      collection: 'payload-jobs',
-      data: {
-        taskSlug: jobSlug,
-        input: {},
-        queue: queueName,
-        waitUntil: new Date(Date.now() + delayMs),
-      },
-    })
-    console.log(`🔄 Scheduled email processing job in queue: ${queueName}`)
-    return true
-  } else {
-    console.log(`✅ Email processing job already scheduled in queue: ${queueName}`)
-    return false
-  }
-}
 
 export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Config): Config => {
   const queueName = pluginConfig.queue || 'default'
@@ -59,6 +14,7 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
     throw new Error('Invalid queue configuration: queue must be a non-empty string')
   }
 
+
   // Handle templates collection configuration
   const templatesConfig = pluginConfig.collections?.templates
   const templatesSlug = typeof templatesConfig === 'string' ? templatesConfig : 'email-templates'
@@ -129,61 +85,7 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
       ...(config.jobs || {}),
       tasks: [
         ...(config.jobs?.tasks || []),
-        {
-          slug: 'process-email-queue',
-          handler: async ({ job, req }: { job: any; req: any }) => {
-            const payload = (req as any).payload
-            let jobResult = null
-
-            try {
-              const mailingService = new MailingService(payload, pluginConfig)
-
-              console.log('🔄 Processing email queue (pending + failed emails)...')
-
-              // Process pending emails first
-              await mailingService.processEmails()
-
-              // Then retry failed emails
-              await mailingService.retryFailedEmails()
-
-              jobResult = {
-                output: {
-                  success: true,
-                  message: 'Email queue processed successfully (pending and failed emails)'
-                }
-              }
-
-              console.log('✅ Email queue processing completed successfully')
-
-            } catch (error) {
-              console.error('❌ Error processing email queue:', error)
-              const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-
-              jobResult = new Error(`Email queue processing failed: ${errorMessage}`)
-            }
-
-            // Always reschedule the next job (success or failure) using duplicate prevention
-            let rescheduled = false
-            try {
-              rescheduled = await scheduleEmailProcessingJob(payload, queueName, 300000) // Reschedule in 5 minutes
-              if (rescheduled) {
-                console.log(`🔄 Rescheduled next email processing job in ${queueName} queue`)
-              }
-            } catch (rescheduleError) {
-              console.error('❌ Failed to reschedule email processing job:', rescheduleError)
-              // If rescheduling fails, we should warn but not fail the current job
-              // since the email processing itself may have succeeded
-              console.warn('⚠️  Email processing completed but next job could not be scheduled')
-            }
-
-            // Return the original result or throw the error
-            if (jobResult instanceof Error) {
-              throw jobResult
-            }
-            return jobResult
-          },
-          interfaceName: 'ProcessEmailQueueJob',
-        },
+        ...mailingJobs,
       ],
     },
     onInit: async (payload: any) => {
@@ -191,7 +93,7 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
         await config.onInit(payload)
       }
 
-      // Initialize mailing service
+      // Initialize mailing service with proper payload instance
       const mailingService = new MailingService(payload, pluginConfig)
 
       // Add mailing context to payload for developer access
@@ -207,9 +109,10 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
 
       console.log('PayloadCMS Mailing Plugin initialized successfully')
 
-      // Schedule the email processing job if not already scheduled
+      // Schedule the initial email processing job
       try {
-        await scheduleEmailProcessingJob(payload, queueName)
+        await scheduleEmailsJob(payload, queueName, 60000) // Schedule in 1 minute
+        console.log(`🔄 Scheduled initial email processing job in queue: ${queueName}`)
       } catch (error) {
         console.error('Failed to schedule email processing job:', error)
       }

src/services/MailingService.ts

@@ -1,9 +1,9 @@
 import { Payload } from 'payload'
-import Handlebars from 'handlebars'
+import { Liquid } from 'liquidjs'
 import nodemailer, { Transporter } from 'nodemailer'
-import { 
-  MailingPluginConfig, 
-  SendEmailOptions, 
+import {
+  MailingPluginConfig,
+  TemplateVariables,
   MailingService as IMailingService,
   EmailTemplate,
   QueuedEmail,
@@ -13,27 +13,33 @@ import {
 import { serializeRichTextToHTML, serializeRichTextToText } from '../utils/richTextSerializer.js'
 
 export class MailingService implements IMailingService {
-  private payload: Payload
+  public payload: Payload
   private config: MailingPluginConfig
   private transporter!: Transporter | any
   private templatesCollection: string
   private emailsCollection: string
+  private liquid: Liquid | null | false = null
+  private transporterInitialized = false
 
   constructor(payload: Payload, config: MailingPluginConfig) {
     this.payload = payload
     this.config = config
-    
+
     const templatesConfig = config.collections?.templates
     this.templatesCollection = typeof templatesConfig === 'string' ? templatesConfig : 'email-templates'
-    
+
     const emailsConfig = config.collections?.emails
     this.emailsCollection = typeof emailsConfig === 'string' ? emailsConfig : 'emails'
-    
-    this.initializeTransporter()
-    this.registerHandlebarsHelpers()
+
+    // Only initialize transporter if payload is properly set
+    if (payload && payload.db) {
+      this.initializeTransporter()
+    }
   }
 
   private initializeTransporter(): void {
+    if (this.transporterInitialized) return
+
     if (this.config.transport) {
       if ('sendMail' in this.config.transport) {
         this.transporter = this.config.transport
@@ -46,6 +52,17 @@ export class MailingService implements IMailingService {
     } else {
       throw new Error('Email transport configuration is required either in plugin config or Payload config')
     }
+
+    this.transporterInitialized = true
+  }
+
+  private ensureInitialized(): void {
+    if (!this.payload || !this.payload.db) {
+      throw new Error('MailingService payload not properly initialized')
+    }
+    if (!this.transporterInitialized) {
+      this.initializeTransporter()
+    }
   }
 
   private getDefaultFrom(): string {
@@ -62,109 +79,73 @@ export class MailingService implements IMailingService {
     return fromEmail || ''
   }
 
-  private registerHandlebarsHelpers(): void {
-    Handlebars.registerHelper('formatDate', (date: Date, format?: string) => {
-      if (!date) return ''
-      const d = new Date(date)
-      if (format === 'short') {
-        return d.toLocaleDateString()
-      }
-      if (format === 'long') {
-        return d.toLocaleDateString('en-US', { 
-          year: 'numeric', 
-          month: 'long', 
-          day: 'numeric' 
+  private async ensureLiquidJSInitialized(): Promise<void> {
+    if (this.liquid !== null) return // Already initialized or failed
+
+    try {
+      const liquidModule = await import('liquidjs')
+      const { Liquid: LiquidEngine } = liquidModule
+      this.liquid = new LiquidEngine()
+
+      // Register custom filters (equivalent to Handlebars helpers)
+      if (this.liquid && typeof this.liquid !== 'boolean') {
+        this.liquid.registerFilter('formatDate', (date: any, format?: string) => {
+          if (!date) return ''
+          const d = new Date(date)
+          if (format === 'short') {
+            return d.toLocaleDateString()
+          }
+          if (format === 'long') {
+            return d.toLocaleDateString('en-US', {
+              year: 'numeric',
+              month: 'long',
+              day: 'numeric'
+            })
+          }
+          return d.toLocaleString()
+        })
+
+        this.liquid.registerFilter('formatCurrency', (amount: any, currency = 'USD') => {
+          if (typeof amount !== 'number') return amount
+          return new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: currency
+          }).format(amount)
+        })
+
+        this.liquid.registerFilter('capitalize', (str: any) => {
+          if (typeof str !== 'string') return str
+          return str.charAt(0).toUpperCase() + str.slice(1)
         })
       }
-      return d.toLocaleString()
-    })
-
-    Handlebars.registerHelper('formatCurrency', (amount: number, currency = 'USD') => {
-      if (typeof amount !== 'number') return amount
-      return new Intl.NumberFormat('en-US', {
-        style: 'currency',
-        currency: currency
-      }).format(amount)
-    })
-
-    Handlebars.registerHelper('ifEquals', function(this: any, arg1: any, arg2: any, options: any) {
-      return (arg1 === arg2) ? options.fn(this) : options.inverse(this)
-    })
-
-    Handlebars.registerHelper('capitalize', (str: string) => {
-      if (typeof str !== 'string') return str
-      return str.charAt(0).toUpperCase() + str.slice(1)
-    })
+    } catch (error) {
+      console.warn('LiquidJS not available. Falling back to simple variable replacement. Install liquidjs or use a different templateEngine.')
+      this.liquid = false // Mark as failed to avoid retries
+    }
   }
 
-  async sendEmail(options: SendEmailOptions): Promise<string> {
-    const emailId = await this.scheduleEmail({
-      ...options,
-      scheduledAt: new Date()
-    })
+  async renderTemplate(templateSlug: string, variables: TemplateVariables): Promise<{ html: string; text: string; subject: string }> {
+    this.ensureInitialized()
+    const template = await this.getTemplateBySlug(templateSlug)
 
-    await this.processEmailItem(emailId)
-    
-    return emailId
-  }
-
-  async scheduleEmail(options: SendEmailOptions): Promise<string> {
-    let html = options.html || ''
-    let text = options.text || ''
-    let subject = options.subject || ''
-    let templateId: string | undefined = undefined
-
-    if (options.templateSlug) {
-      const template = await this.getTemplateBySlug(options.templateSlug)
-      
-      if (template) {
-        templateId = template.id
-        const variables = options.variables || {}
-        const renderedContent = await this.renderEmailTemplate(template, variables)
-        html = renderedContent.html
-        text = renderedContent.text
-        subject = this.renderHandlebarsTemplate(template.subject, variables)
-      } else {
-        throw new Error(`Email template not found: ${options.templateSlug}`)
-      }
+    if (!template) {
+      throw new Error(`Email template not found: ${templateSlug}`)
     }
 
-    if (!subject && !options.subject) {
-      throw new Error('Email subject is required')
+    const emailContent = await this.renderEmailTemplate(template, variables)
+    const subject = await this.renderTemplateString(template.subject, variables)
+
+    return {
+      html: emailContent.html,
+      text: emailContent.text,
+      subject
     }
-
-    if (!html && !options.html) {
-      throw new Error('Email HTML content is required')
-    }
-
-    const queueData = {
-      template: templateId,
-      to: Array.isArray(options.to) ? options.to : [options.to],
-      cc: options.cc ? (Array.isArray(options.cc) ? options.cc : [options.cc]) : undefined,
-      bcc: options.bcc ? (Array.isArray(options.bcc) ? options.bcc : [options.bcc]) : undefined,
-      from: options.from || this.getDefaultFrom(),
-      replyTo: options.replyTo,
-      subject: subject || options.subject,
-      html,
-      text,
-      variables: options.variables,
-      scheduledAt: options.scheduledAt?.toISOString(),
-      status: 'pending' as const,
-      attempts: 0,
-      priority: options.priority || 5,
-    }
-
-    const result = await this.payload.create({
-      collection: this.emailsCollection as any,
-      data: queueData,
-    })
-
-    return result.id as string
   }
 
   async processEmails(): Promise<void> {
+    this.ensureInitialized()
     const currentTime = new Date().toISOString()
-    
+
     const { docs: pendingEmails } = await this.payload.find({
       collection: this.emailsCollection as any,
       where: {
@@ -200,6 +181,7 @@ export class MailingService implements IMailingService {
   }
 
   async retryFailedEmails(): Promise<void> {
+    this.ensureInitialized()
     const maxAttempts = this.config.retryAttempts || 3
     const retryDelay = this.config.retryDelay || 300000 // 5 minutes
     const retryTime = new Date(Date.now() - retryDelay).toISOString()
@@ -348,7 +330,7 @@ export class MailingService implements IMailingService {
         },
         limit: 1,
       })
-      
+
       return docs.length > 0 ? docs[0] as EmailTemplate : null
     } catch (error) {
       console.error(`Template with slug '${templateSlug}' not found:`, error)
@@ -356,14 +338,62 @@ export class MailingService implements IMailingService {
     }
   }
 
-  private renderHandlebarsTemplate(template: string, variables: Record<string, any>): string {
-    try {
-      const compiled = Handlebars.compile(template)
-      return compiled(variables)
-    } catch (error) {
-      console.error('Handlebars template rendering error:', error)
-      return template
+  private async renderTemplateString(template: string, variables: Record<string, any>): Promise<string> {
+    // Use custom template renderer if provided
+    if (this.config.templateRenderer) {
+      try {
+        return await this.config.templateRenderer(template, variables)
+      } catch (error) {
+        console.error('Custom template renderer error:', error)
+        return template
+      }
     }
+
+    const engine = this.config.templateEngine || 'liquidjs'
+
+    // Use LiquidJS if configured
+    if (engine === 'liquidjs') {
+      try {
+        await this.ensureLiquidJSInitialized()
+        if (this.liquid && typeof this.liquid !== 'boolean') {
+          return await this.liquid.parseAndRender(template, variables)
+        }
+      } catch (error) {
+        console.error('LiquidJS template rendering error:', error)
+      }
+    }
+
+    // Use Mustache if configured
+    if (engine === 'mustache') {
+      try {
+        const mustacheResult = await this.renderWithMustache(template, variables)
+        if (mustacheResult !== null) {
+          return mustacheResult
+        }
+      } catch (error) {
+        console.warn('Mustache not available. Falling back to simple variable replacement. Install mustache package.')
+      }
+    }
+
+    // Fallback to simple variable replacement
+    return this.simpleVariableReplacement(template, variables)
+  }
+
+  private async renderWithMustache(template: string, variables: Record<string, any>): Promise<string | null> {
+    try {
+      const mustacheModule = await import('mustache')
+      const Mustache = mustacheModule.default || mustacheModule
+      return Mustache.render(template, variables)
+    } catch (error) {
+      return null
+    }
+  }
+
+  private simpleVariableReplacement(template: string, variables: Record<string, any>): string {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+      const value = variables[key]
+      return value !== undefined ? String(value) : match
+    })
   }
 
   private async renderEmailTemplate(template: EmailTemplate, variables: Record<string, any> = {}): Promise<{ html: string; text: string }> {
@@ -375,11 +405,11 @@ export class MailingService implements IMailingService {
     let html = serializeRichTextToHTML(template.content)
     let text = serializeRichTextToText(template.content)
 
-    // Apply Handlebars variables to the rendered content
-    html = this.renderHandlebarsTemplate(html, variables)
-    text = this.renderHandlebarsTemplate(text, variables)
+    // Apply template variables to the rendered content
+    html = await this.renderTemplateString(html, variables)
+    text = await this.renderTemplateString(text, variables)
 
     return { html, text }
   }
 
-}
+}

src/types/index.ts

@@ -1,5 +1,5 @@
 import { Payload } from 'payload'
-import type { CollectionConfig, RichTextField } from 'payload'
+import type { CollectionConfig, RichTextField, TypedCollection } from 'payload'
 import { Transporter } from 'nodemailer'
 
 export interface EmailObject {
@@ -16,6 +16,10 @@ export interface EmailObject {
 
 export type EmailWrapperHook = (email: EmailObject) => EmailObject | Promise<EmailObject>
 
+export type TemplateRendererHook = (template: string, variables: Record<string, any>) => string | Promise<string>
+
+export type TemplateEngine = 'liquidjs' | 'mustache' | 'simple'
+
 export interface MailingPluginConfig {
   collections?: {
     templates?: string | Partial<CollectionConfig>
@@ -28,6 +32,8 @@ export interface MailingPluginConfig {
   retryAttempts?: number
   retryDelay?: number
   emailWrapper?: EmailWrapperHook
+  templateRenderer?: TemplateRendererHook
+  templateEngine?: TemplateEngine
   richTextEditor?: RichTextField['editor']
   onReady?: (payload: any) => Promise<void>
   initOrder?: 'before' | 'after'
@@ -77,26 +83,15 @@ export interface QueuedEmail {
   updatedAt: string
 }
 
-export interface SendEmailOptions {
-  templateSlug?: string
-  to: string | string[]
-  cc?: string | string[]
-  bcc?: string | string[]
-  from?: string
-  replyTo?: string
-  subject?: string
-  html?: string
-  text?: string
-  variables?: Record<string, any>
-  scheduledAt?: Date
-  priority?: number
+// Simple helper type for template variables
+export interface TemplateVariables {
+  [key: string]: any
 }
 
 export interface MailingService {
-  sendEmail(options: SendEmailOptions): Promise<string>
-  scheduleEmail(options: SendEmailOptions): Promise<string>
   processEmails(): Promise<void>
   retryFailedEmails(): Promise<void>
+  renderTemplate(templateSlug: string, variables: TemplateVariables): Promise<{ html: string; text: string; subject: string }>
 }
 
 export interface MailingContext {

src/types/mustache.d.ts

@@ -0,0 +1,7 @@
+declare module 'mustache' {
+  interface MustacheStatic {
+    render(template: string, view?: any, partials?: any, tags?: string[]): string
+  }
+  const mustache: MustacheStatic
+  export = mustache
+}

src/utils/helpers.ts

@@ -1,5 +1,55 @@
 import { Payload } from 'payload'
-import { SendEmailOptions } from '../types/index.js'
+import { TemplateVariables } from '../types/index.js'
+
+// Base type for email data that all emails must have
+export interface BaseEmailData {
+  to: string | string[]
+  cc?: string | string[]
+  bcc?: string | string[]
+  subject?: string
+  html?: string
+  text?: string
+  scheduledAt?: string | Date
+  priority?: number
+  [key: string]: any
+}
+
+// Options for sending emails
+export interface SendEmailOptions<T extends BaseEmailData = BaseEmailData> {
+  // Template-based email
+  template?: {
+    slug: string
+    variables?: Record<string, any>
+  }
+  // Direct email data
+  data?: Partial<T>
+  // Common options
+  collectionSlug?: string // defaults to 'emails'
+}
+
+/**
+ * Parse and validate email addresses
+ * @internal
+ */
+export const parseAndValidateEmails = (emails: string | string[] | undefined): string[] | undefined => {
+  if (!emails) return undefined
+
+  let emailList: string[]
+  if (Array.isArray(emails)) {
+    emailList = emails
+  } else {
+    emailList = emails.split(',').map(email => email.trim()).filter(Boolean)
+  }
+
+  // Basic email validation
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  const invalidEmails = emailList.filter(email => !emailRegex.test(email))
+  if (invalidEmails.length > 0) {
+    throw new Error(`Invalid email addresses: ${invalidEmails.join(', ')}`)
+  }
+
+  return emailList
+}
 
 export const getMailing = (payload: Payload) => {
   const mailing = (payload as any).mailing
@@ -9,14 +59,9 @@ export const getMailing = (payload: Payload) => {
   return mailing
 }
 
-export const sendEmail = async (payload: Payload, options: SendEmailOptions): Promise<string> => {
+export const renderTemplate = async (payload: Payload, templateSlug: string, variables: TemplateVariables): Promise<{ html: string; text: string; subject: string }> => {
   const mailing = getMailing(payload)
-  return mailing.service.sendEmail(options)
-}
-
-export const scheduleEmail = async (payload: Payload, options: SendEmailOptions): Promise<string> => {
-  const mailing = getMailing(payload)
-  return mailing.service.scheduleEmail(options)
+  return mailing.service.renderTemplate(templateSlug, variables)
 }
 
 export const processEmails = async (payload: Payload): Promise<void> => {
@@ -27,4 +72,84 @@ export const processEmails = async (payload: Payload): Promise<void> => {
 export const retryFailedEmails = async (payload: Payload): Promise<void> => {
   const mailing = getMailing(payload)
   return mailing.service.retryFailedEmails()
+}
+
+/**
+ * Send an email with full type safety
+ *
+ * @example
+ * ```typescript
+ * // With your generated Email type
+ * import { Email } from './payload-types'
+ *
+ * const email = await sendEmail<Email>(payload, {
+ *   template: {
+ *     slug: 'welcome',
+ *     variables: { name: 'John' }
+ *   },
+ *   data: {
+ *     to: 'user@example.com',
+ *     customField: 'value' // Your custom fields are type-safe!
+ *   }
+ * })
+ * ```
+ */
+export const sendEmail = async <T extends BaseEmailData = BaseEmailData>(
+  payload: Payload,
+  options: SendEmailOptions<T>
+): Promise<T> => {
+  const mailing = getMailing(payload)
+  const collectionSlug = options.collectionSlug || mailing.collections.emails || 'emails'
+
+  let emailData: Partial<T> = { ...options.data } as Partial<T>
+
+  // If using a template, render it first
+  if (options.template) {
+    const { html, text, subject } = await renderTemplate(
+      payload,
+      options.template.slug,
+      options.template.variables || {}
+    )
+
+    // Template values take precedence over data values
+    emailData = {
+      ...emailData,
+      subject,
+      html,
+      text,
+    } as Partial<T>
+  }
+
+  // Validate required fields
+  if (!emailData.to) {
+    throw new Error('Field "to" is required for sending emails')
+  }
+
+  if (!emailData.subject || !emailData.html) {
+    throw new Error('Fields "subject" and "html" are required when not using a template')
+  }
+
+  // Process email addresses using shared validation
+  if (emailData.to) {
+    emailData.to = parseAndValidateEmails(emailData.to as string | string[])
+  }
+  if (emailData.cc) {
+    emailData.cc = parseAndValidateEmails(emailData.cc as string | string[])
+  }
+  if (emailData.bcc) {
+    emailData.bcc = parseAndValidateEmails(emailData.bcc as string | string[])
+  }
+
+  // Convert scheduledAt to ISO string if it's a Date
+  if (emailData.scheduledAt instanceof Date) {
+    emailData.scheduledAt = emailData.scheduledAt.toISOString()
+  }
+
+  // Create the email in the collection
+  const email = await payload.create({
+    collection: collectionSlug as any,
+    data: emailData as any
+  })
+
+  return email as unknown as T
 }