mirror of
https://github.com/xtr-dev/payload-mailing.git
synced 2025-12-10 08:13:23 +00:00
Compare commits
29 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
768b70a003 | ||
| e91ab7e54e | |||
| 06f9c2cb5b | |||
|
|
21b22a033a | ||
| 6ad90874cf | |||
|
|
03f1f62fbf | ||
| e55e4197d3 | |||
| 2e6feccf54 | |||
|
|
e38b63d814 | ||
| 31721dc110 | |||
| 6e4f754306 | |||
| 45559804b0 | |||
| 934b7c2de7 | |||
|
|
c78a8c2480 | ||
| a27481c818 | |||
| b342f32d97 | |||
| e1800f5a6e | |||
|
|
0c4d894f51 | ||
| 1af54c6573 | |||
| 24f1f4c5a4 | |||
| de41f4ecb2 | |||
|
|
6d4e020133 | ||
| 25838bcba4 | |||
| dfa833fa5e | |||
| cb5ce2e720 | |||
| f8b7dd8f4c | |||
|
|
b3de54b953 | ||
| 186c340d96 | |||
| 08b4d49019 |
387
README.md
387
README.md
@@ -56,53 +56,55 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
### 2. Send emails using Payload collections
|
||||
### 2. Send emails with type-safe helper
|
||||
|
||||
```typescript
|
||||
import { renderTemplate } from '@xtr-dev/payload-mailing'
|
||||
// sendEmail is a primary export for easy access
|
||||
import { sendEmail } from '@xtr-dev/payload-mailing'
|
||||
import { Email } from './payload-types' // Your generated types
|
||||
|
||||
// Option 1: Using templates with variables
|
||||
const { html, text, subject } = await renderTemplate(payload, 'welcome-email', {
|
||||
// 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'
|
||||
})
|
||||
|
||||
// Create email using Payload's collection API (full type safety!)
|
||||
const email = await payload.create({
|
||||
collection: 'emails',
|
||||
}
|
||||
},
|
||||
data: {
|
||||
to: ['user@example.com'],
|
||||
subject,
|
||||
html,
|
||||
text,
|
||||
to: 'user@example.com',
|
||||
// Schedule for later (optional)
|
||||
scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
|
||||
// Add any custom fields you've defined
|
||||
priority: 1,
|
||||
customField: 'your-value', // Your custom collection fields work!
|
||||
// Your custom fields are type-safe!
|
||||
customField: 'your-value',
|
||||
}
|
||||
})
|
||||
|
||||
// Option 2: Direct HTML email (no template needed)
|
||||
const directEmail = await payload.create({
|
||||
collection: 'emails',
|
||||
// Option 2: Direct HTML email (no template)
|
||||
const directEmail = await sendEmail<Email>(payload, {
|
||||
data: {
|
||||
to: ['user@example.com'],
|
||||
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>',
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Why This Approach is Better
|
||||
|
||||
- ✅ **Full Type Safety**: Use your generated Payload types
|
||||
- ✅ **No Learning Curve**: Just use `payload.create()` like any collection
|
||||
- ✅ **Maximum Flexibility**: Add any custom fields to your email collection
|
||||
- ✅ **Payload Integration**: Leverage validation, hooks, access control
|
||||
- ✅ **Consistent API**: One way to create data in Payload
|
||||
|
||||
## Configuration
|
||||
|
||||
### Plugin Options
|
||||
@@ -137,10 +139,6 @@ mailingPlugin({
|
||||
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!')
|
||||
@@ -225,7 +223,7 @@ Thanks for joining {{siteName}}. We're excited to have you!
|
||||
|
||||
**What you can do:**
|
||||
• Create beautiful emails with rich text formatting
|
||||
• Use the emailWrapper hook to add custom layouts
|
||||
|
||||
• Queue and schedule emails effortlessly
|
||||
|
||||
Your account was created on {{formatDate createdAt "long"}}.
|
||||
@@ -236,282 +234,6 @@ The {{siteName}} Team
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Custom HTML Layouts with Email Wrapper Hook
|
||||
|
||||
The `emailWrapper` hook allows you to apply consistent HTML layouts and styling to all emails sent through the plugin. This is perfect for adding company branding, headers, footers, and responsive styling.
|
||||
|
||||
#### Basic Email Wrapper
|
||||
|
||||
```typescript
|
||||
mailingPlugin({
|
||||
// ... other config
|
||||
emailWrapper: (email) => {
|
||||
const wrappedHtml = `
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>${email.subject}</title>
|
||||
<style>
|
||||
body { font-family: Arial, sans-serif; margin: 0; padding: 20px; background-color: #f4f4f4; }
|
||||
.container { max-width: 600px; margin: 0 auto; background: white; border-radius: 8px; overflow: hidden; }
|
||||
.header { background: #007bff; color: white; padding: 20px; text-align: center; }
|
||||
.content { padding: 30px; line-height: 1.6; }
|
||||
.footer { background: #f8f9fa; padding: 15px; text-align: center; color: #6c757d; font-size: 14px; }
|
||||
|
||||
/* Responsive styles */
|
||||
@media only screen and (max-width: 600px) {
|
||||
.container { margin: 0 10px; }
|
||||
.content { padding: 20px; }
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<div class="header">
|
||||
<h1>My Company</h1>
|
||||
</div>
|
||||
<div class="content">
|
||||
${email.html}
|
||||
</div>
|
||||
<div class="footer">
|
||||
© 2024 My Company. All rights reserved.<br>
|
||||
<a href="#" style="color: #007bff;">Unsubscribe</a> |
|
||||
<a href="#" style="color: #007bff;">Contact Support</a>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
return {
|
||||
...email,
|
||||
html: wrappedHtml,
|
||||
text: `MY COMPANY\n\n${email.text}\n\n© 2024 My Company\nUnsubscribe: [link] | Contact Support: [link]`
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Advanced Email Wrapper with Dynamic Content
|
||||
|
||||
```typescript
|
||||
mailingPlugin({
|
||||
// ... other config
|
||||
emailWrapper: (email) => {
|
||||
// You can access email properties and customize based on content
|
||||
const isTransactional = email.subject?.includes('Receipt') || email.subject?.includes('Confirmation');
|
||||
const headerColor = isTransactional ? '#28a745' : '#007bff';
|
||||
const headerText = isTransactional ? 'Order Confirmation' : 'My Company';
|
||||
|
||||
const wrappedHtml = `
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<title>${email.subject}</title>
|
||||
<!--[if mso]>
|
||||
<noscript>
|
||||
<xml>
|
||||
<o:OfficeDocumentSettings>
|
||||
<o:PixelsPerInch>96</o:PixelsPerInch>
|
||||
</o:OfficeDocumentSettings>
|
||||
</xml>
|
||||
</noscript>
|
||||
<![endif]-->
|
||||
<style>
|
||||
/* Reset styles */
|
||||
body, table, td, a { -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
|
||||
table, td { mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
|
||||
img { -ms-interpolation-mode: bicubic; border: 0; outline: none; text-decoration: none; }
|
||||
|
||||
/* Base styles */
|
||||
body {
|
||||
margin: 0 !important;
|
||||
padding: 0 !important;
|
||||
background-color: #f4f4f4;
|
||||
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
|
||||
}
|
||||
|
||||
.email-container {
|
||||
max-width: 600px;
|
||||
margin: 0 auto;
|
||||
background-color: #ffffff;
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
.email-header {
|
||||
background: linear-gradient(135deg, ${headerColor}, ${headerColor}dd);
|
||||
color: white;
|
||||
padding: 30px 20px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.email-content {
|
||||
padding: 30px;
|
||||
color: #333333;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.email-footer {
|
||||
background-color: #f8f9fa;
|
||||
padding: 20px;
|
||||
text-align: center;
|
||||
color: #6c757d;
|
||||
font-size: 14px;
|
||||
border-top: 1px solid #e9ecef;
|
||||
}
|
||||
|
||||
.email-footer a {
|
||||
color: ${headerColor};
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
/* Responsive */
|
||||
@media only screen and (max-width: 600px) {
|
||||
.email-container {
|
||||
margin: 0 10px !important;
|
||||
}
|
||||
.email-header, .email-content {
|
||||
padding: 20px !important;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="email-container">
|
||||
<div class="email-header">
|
||||
<h1 style="margin: 0; font-size: 24px;">${headerText}</h1>
|
||||
</div>
|
||||
<div class="email-content">
|
||||
${email.html}
|
||||
</div>
|
||||
<div class="email-footer">
|
||||
<p style="margin: 0 0 10px;">© ${new Date().getFullYear()} My Company. All rights reserved.</p>
|
||||
<p style="margin: 0;">
|
||||
<a href="mailto:support@mycompany.com">Contact Support</a> |
|
||||
<a href="#">Privacy Policy</a> |
|
||||
<a href="#">Unsubscribe</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
// Also enhance the plain text version
|
||||
const wrappedText = `
|
||||
${headerText.toUpperCase()}
|
||||
${'='.repeat(headerText.length)}
|
||||
|
||||
${email.text || email.html?.replace(/<[^>]*>/g, '')}
|
||||
|
||||
---
|
||||
© ${new Date().getFullYear()} My Company. All rights reserved.
|
||||
Contact Support: support@mycompany.com
|
||||
Privacy Policy: [link]
|
||||
Unsubscribe: [link]
|
||||
`.trim();
|
||||
|
||||
return {
|
||||
...email,
|
||||
html: wrappedHtml,
|
||||
text: wrappedText
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### External CSS and Assets
|
||||
|
||||
You can also reference external stylesheets and assets:
|
||||
|
||||
```typescript
|
||||
mailingPlugin({
|
||||
emailWrapper: (email) => {
|
||||
const wrappedHtml = `
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>${email.subject}</title>
|
||||
<!-- External CSS -->
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body { font-family: 'Inter', sans-serif; }
|
||||
/* Your custom styles here */
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="max-width: 600px; margin: 0 auto;">
|
||||
<img src="https://mycompany.com/email-header.png" alt="My Company" style="width: 100%; height: auto;">
|
||||
<div style="padding: 20px;">
|
||||
${email.html}
|
||||
</div>
|
||||
<img src="https://mycompany.com/email-footer.png" alt="Footer" style="width: 100%; height: auto;">
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
`;
|
||||
|
||||
return { ...email, html: wrappedHtml };
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Template-Specific Layouts
|
||||
|
||||
You can customize layouts based on email templates:
|
||||
|
||||
```typescript
|
||||
mailingPlugin({
|
||||
emailWrapper: (email, context) => {
|
||||
// Access template information if available
|
||||
const templateSlug = context?.templateSlug;
|
||||
|
||||
let layoutClass = 'default-layout';
|
||||
let headerColor = '#007bff';
|
||||
|
||||
if (templateSlug === 'welcome-email') {
|
||||
layoutClass = 'welcome-layout';
|
||||
headerColor = '#28a745';
|
||||
} else if (templateSlug === 'invoice-email') {
|
||||
layoutClass = 'invoice-layout';
|
||||
headerColor = '#dc3545';
|
||||
}
|
||||
|
||||
const wrappedHtml = `
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>${email.subject}</title>
|
||||
<style>
|
||||
.${layoutClass} { /* template-specific styles */ }
|
||||
.header { background-color: ${headerColor}; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="${layoutClass}">
|
||||
${email.html}
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
`;
|
||||
|
||||
return { ...email, html: wrappedHtml };
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The `emailWrapper` hook receives the email object with `html`, `text`, and `subject` properties, and should return the modified email object with your custom layout applied.
|
||||
|
||||
### Custom Rich Text Editor
|
||||
|
||||
Override the rich text editor used for templates:
|
||||
@@ -848,6 +570,55 @@ 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.
|
||||
|
||||
@@ -184,25 +184,43 @@ The plugin automatically processes the outbox every 5 minutes and retries failed
|
||||
## Plugin API Usage
|
||||
|
||||
```javascript
|
||||
import { sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
|
||||
import { sendEmail } from '@xtr-dev/payload-mailing'
|
||||
|
||||
// Send immediate email
|
||||
const emailId = await sendEmail(payload, {
|
||||
templateId: 'welcome-template-id',
|
||||
to: 'user@example.com',
|
||||
// Send immediate email with template
|
||||
const email = await sendEmail(payload, {
|
||||
template: {
|
||||
slug: 'welcome-email',
|
||||
variables: {
|
||||
firstName: 'John',
|
||||
siteName: 'My App'
|
||||
}
|
||||
},
|
||||
data: {
|
||||
to: 'user@example.com',
|
||||
}
|
||||
})
|
||||
|
||||
// Schedule email
|
||||
const scheduledId = await scheduleEmail(payload, {
|
||||
templateId: 'reminder-template-id',
|
||||
to: 'user@example.com',
|
||||
scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
|
||||
// Schedule email for later
|
||||
const scheduledEmail = await sendEmail(payload, {
|
||||
template: {
|
||||
slug: 'reminder',
|
||||
variables: {
|
||||
eventName: 'Product Launch'
|
||||
}
|
||||
},
|
||||
data: {
|
||||
to: 'user@example.com',
|
||||
scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
|
||||
}
|
||||
})
|
||||
|
||||
// Send direct HTML email (no template)
|
||||
const directEmail = await sendEmail(payload, {
|
||||
data: {
|
||||
to: 'user@example.com',
|
||||
subject: 'Direct Email',
|
||||
html: '<h1>Hello World</h1>',
|
||||
text: 'Hello World'
|
||||
}
|
||||
})
|
||||
```
|
||||
@@ -1,37 +1,50 @@
|
||||
import { getPayload } from 'payload'
|
||||
import config from '@payload-config'
|
||||
import { sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
|
||||
import { sendEmail } from '@xtr-dev/payload-mailing'
|
||||
|
||||
export async function POST(request: Request) {
|
||||
try {
|
||||
const payload = await getPayload({ config })
|
||||
const body = await request.json()
|
||||
const { type = 'send', templateSlug, to, variables, scheduledAt } = body
|
||||
const { type = 'send', templateSlug, to, variables, scheduledAt, subject, html, text } = body
|
||||
|
||||
let result
|
||||
if (type === 'send') {
|
||||
// Send immediately
|
||||
result = await sendEmail(payload, {
|
||||
templateSlug,
|
||||
// Use the new sendEmail API
|
||||
const emailOptions: any = {
|
||||
data: {
|
||||
to,
|
||||
variables,
|
||||
})
|
||||
} else if (type === 'schedule') {
|
||||
// Schedule for later
|
||||
result = await scheduleEmail(payload, {
|
||||
templateSlug,
|
||||
to,
|
||||
variables,
|
||||
scheduledAt: scheduledAt ? new Date(scheduledAt) : new Date(Date.now() + 60000), // Default to 1 minute
|
||||
})
|
||||
} else {
|
||||
return Response.json({ error: 'Invalid type. Use "send" or "schedule"' }, { status: 400 })
|
||||
}
|
||||
}
|
||||
|
||||
// Add template if provided
|
||||
if (templateSlug) {
|
||||
emailOptions.template = {
|
||||
slug: templateSlug,
|
||||
variables: variables || {}
|
||||
}
|
||||
} else if (subject && html) {
|
||||
// Direct email without template
|
||||
emailOptions.data.subject = subject
|
||||
emailOptions.data.html = html
|
||||
if (text) {
|
||||
emailOptions.data.text = text
|
||||
}
|
||||
} else {
|
||||
return Response.json({
|
||||
error: 'Either templateSlug or subject+html must be provided'
|
||||
}, { status: 400 })
|
||||
}
|
||||
|
||||
// Add scheduling if needed
|
||||
if (type === 'schedule' || scheduledAt) {
|
||||
emailOptions.data.scheduledAt = scheduledAt ? new Date(scheduledAt) : new Date(Date.now() + 60000)
|
||||
}
|
||||
|
||||
const result = await sendEmail(payload, emailOptions)
|
||||
|
||||
return Response.json({
|
||||
success: true,
|
||||
emailId: result,
|
||||
message: type === 'send' ? 'Email sent successfully' : 'Email scheduled successfully',
|
||||
emailId: result.id,
|
||||
message: scheduledAt ? 'Email scheduled successfully' : 'Email queued successfully',
|
||||
})
|
||||
} catch (error) {
|
||||
console.error('Test email error:', error)
|
||||
|
||||
@@ -100,7 +100,8 @@ export interface Config {
|
||||
};
|
||||
jobs: {
|
||||
tasks: {
|
||||
'process-email-queue': ProcessEmailQueueJob;
|
||||
processEmails: ProcessEmailsJob;
|
||||
'send-email': TaskSendEmail;
|
||||
inline: {
|
||||
input: unknown;
|
||||
output: unknown;
|
||||
@@ -232,21 +233,17 @@ export interface Email {
|
||||
*/
|
||||
template?: (string | null) | EmailTemplate;
|
||||
/**
|
||||
* Template slug used for this email
|
||||
* Recipient email addresses
|
||||
*/
|
||||
templateSlug?: string | null;
|
||||
to: string[];
|
||||
/**
|
||||
* Recipient email address(es), comma-separated
|
||||
* CC email addresses
|
||||
*/
|
||||
to: string;
|
||||
cc?: string[] | null;
|
||||
/**
|
||||
* CC email address(es), comma-separated
|
||||
* BCC email addresses
|
||||
*/
|
||||
cc?: string | null;
|
||||
/**
|
||||
* BCC email address(es), comma-separated
|
||||
*/
|
||||
bcc?: string | null;
|
||||
bcc?: string[] | null;
|
||||
/**
|
||||
* Sender email address (optional, uses default if not provided)
|
||||
*/
|
||||
@@ -362,7 +359,7 @@ export interface PayloadJob {
|
||||
| {
|
||||
executedAt: string;
|
||||
completedAt: string;
|
||||
taskSlug: 'inline' | 'process-email-queue';
|
||||
taskSlug: 'inline' | 'processEmails' | 'send-email';
|
||||
taskID: string;
|
||||
input?:
|
||||
| {
|
||||
@@ -395,7 +392,7 @@ export interface PayloadJob {
|
||||
id?: string | null;
|
||||
}[]
|
||||
| null;
|
||||
taskSlug?: ('inline' | 'process-email-queue') | null;
|
||||
taskSlug?: ('inline' | 'processEmails' | 'send-email') | null;
|
||||
queue?: string | null;
|
||||
waitUntil?: string | null;
|
||||
processing?: boolean | null;
|
||||
@@ -542,7 +539,6 @@ export interface EmailTemplatesSelect<T extends boolean = true> {
|
||||
*/
|
||||
export interface EmailsSelect<T extends boolean = true> {
|
||||
template?: T;
|
||||
templateSlug?: T;
|
||||
to?: T;
|
||||
cc?: T;
|
||||
bcc?: T;
|
||||
@@ -627,12 +623,69 @@ export interface PayloadMigrationsSelect<T extends boolean = true> {
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "ProcessEmailQueueJob".
|
||||
* via the `definition` "ProcessEmailsJob".
|
||||
*/
|
||||
export interface ProcessEmailQueueJob {
|
||||
export interface ProcessEmailsJob {
|
||||
input?: unknown;
|
||||
output?: unknown;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "TaskSend-email".
|
||||
*/
|
||||
export interface TaskSendEmail {
|
||||
input: {
|
||||
/**
|
||||
* Use a template (leave empty for direct email)
|
||||
*/
|
||||
templateSlug?: string | null;
|
||||
/**
|
||||
* JSON object with variables for template rendering
|
||||
*/
|
||||
variables?:
|
||||
| {
|
||||
[k: string]: unknown;
|
||||
}
|
||||
| unknown[]
|
||||
| string
|
||||
| number
|
||||
| boolean
|
||||
| null;
|
||||
/**
|
||||
* Email subject (required if not using template)
|
||||
*/
|
||||
subject?: string | null;
|
||||
/**
|
||||
* HTML email content (required if not using template)
|
||||
*/
|
||||
html?: string | null;
|
||||
/**
|
||||
* Plain text email content (optional)
|
||||
*/
|
||||
text?: string | null;
|
||||
/**
|
||||
* Comma-separated list of email addresses
|
||||
*/
|
||||
to: string;
|
||||
/**
|
||||
* Optional comma-separated list of CC email addresses
|
||||
*/
|
||||
cc?: string | null;
|
||||
/**
|
||||
* Optional comma-separated list of BCC email addresses
|
||||
*/
|
||||
bcc?: string | null;
|
||||
/**
|
||||
* Optional date/time to schedule email for future delivery
|
||||
*/
|
||||
scheduledAt?: string | null;
|
||||
/**
|
||||
* Email priority (1 = highest, 10 = lowest)
|
||||
*/
|
||||
priority?: number | null;
|
||||
};
|
||||
output?: unknown;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "auth".
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
import { mongooseAdapter } from '@payloadcms/db-mongodb'
|
||||
import { lexicalEditor } from '@payloadcms/richtext-lexical'
|
||||
import {
|
||||
BlocksFeature,
|
||||
FixedToolbarFeature,
|
||||
HeadingFeature,
|
||||
HorizontalRuleFeature,
|
||||
InlineToolbarFeature,
|
||||
lexicalHTML,
|
||||
} from '@payloadcms/richtext-lexical'
|
||||
import { MongoMemoryReplSet } from 'mongodb-memory-server'
|
||||
import path from 'path'
|
||||
@@ -17,7 +15,7 @@ import { fileURLToPath } from 'url'
|
||||
import { testEmailAdapter } from './helpers/testEmailAdapter.js'
|
||||
import { seed, seedUser } from './seed.js'
|
||||
import mailingPlugin from "../src/plugin.js"
|
||||
import { sendEmail } from "../src/utils/helpers.js"
|
||||
import {sendEmail} from "@xtr-dev/payload-mailing"
|
||||
|
||||
const filename = fileURLToPath(import.meta.url)
|
||||
const dirname = path.dirname(filename)
|
||||
@@ -85,8 +83,8 @@ const buildConfigWithMemoryDB = async () => {
|
||||
|
||||
// Queue the welcome email using template slug
|
||||
const emailId = await sendEmail(req.payload, {
|
||||
templateSlug: 'welcome-email',
|
||||
to: doc.email,
|
||||
template: {
|
||||
slug: 'welcome-email',
|
||||
variables: {
|
||||
firstName: doc.firstName || doc.email?.split('@')?.[0],
|
||||
siteName: 'PayloadCMS Mailing Demo',
|
||||
@@ -94,6 +92,10 @@ const buildConfigWithMemoryDB = async () => {
|
||||
isPremium: false,
|
||||
dashboardUrl: 'http://localhost:3000/admin',
|
||||
},
|
||||
},
|
||||
data: {
|
||||
to: doc.email,
|
||||
}
|
||||
})
|
||||
|
||||
console.log('✅ Welcome email queued successfully. Email ID:', emailId)
|
||||
@@ -280,56 +282,6 @@ const buildConfigWithMemoryDB = async () => {
|
||||
],
|
||||
}),
|
||||
|
||||
emailWrapper: (email) => {
|
||||
// Example: wrap email content in a custom layout
|
||||
const wrappedHtml = `
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>${email.subject}</title>
|
||||
<style>
|
||||
body { font-family: Arial, sans-serif; margin: 0; padding: 20px; background-color: #f5f5f5; }
|
||||
.container { max-width: 600px; margin: 0 auto; background: white; border-radius: 8px; overflow: hidden; }
|
||||
.header { background: #007bff; color: white; padding: 20px; text-align: center; }
|
||||
.content { padding: 30px; }
|
||||
.footer { background: #f8f9fa; padding: 15px; text-align: center; font-size: 12px; color: #6c757d; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<div class="header">
|
||||
<h1>My Company</h1>
|
||||
</div>
|
||||
<div class="content">
|
||||
${email.html}
|
||||
</div>
|
||||
<div class="footer">
|
||||
This email was sent from My Company. If you have questions, contact support@mycompany.com
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
const wrappedText = `
|
||||
MY COMPANY
|
||||
==========
|
||||
|
||||
${email.text || email.html?.replace(/<[^>]*>/g, '')}
|
||||
|
||||
---
|
||||
This email was sent from My Company.
|
||||
If you have questions, contact support@mycompany.com
|
||||
`
|
||||
|
||||
return {
|
||||
...email,
|
||||
html: wrappedHtml,
|
||||
text: wrappedText.trim(),
|
||||
}
|
||||
},
|
||||
|
||||
// Called after mailing plugin is fully initialized
|
||||
onReady: async (payload) => {
|
||||
|
||||
@@ -102,7 +102,7 @@ export const seed = async (payload: Payload) => {
|
||||
format: 0,
|
||||
mode: 'normal',
|
||||
style: '',
|
||||
text: 'Use the emailWrapper hook to add custom layouts',
|
||||
text: 'Create beautiful emails with rich text formatting',
|
||||
type: 'text',
|
||||
version: 1,
|
||||
},
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
// Simple test to verify plugin can be imported and initialized
|
||||
import { mailingPlugin, sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
|
||||
import { mailingPlugin, sendEmail, renderTemplate } from '@xtr-dev/payload-mailing'
|
||||
|
||||
console.log('✅ Plugin imports successfully')
|
||||
console.log('✅ mailingPlugin:', typeof mailingPlugin)
|
||||
console.log('✅ sendEmail:', typeof sendEmail)
|
||||
console.log('✅ scheduleEmail:', typeof scheduleEmail)
|
||||
console.log('✅ renderTemplate:', typeof renderTemplate)
|
||||
|
||||
// Test plugin configuration
|
||||
try {
|
||||
|
||||
@@ -19,13 +19,13 @@
|
||||
"@payload-config": [
|
||||
"./payload.config.ts"
|
||||
],
|
||||
"temp-project": [
|
||||
"@xtr-dev/payload-mailing": [
|
||||
"../src/index.ts"
|
||||
],
|
||||
"temp-project/client": [
|
||||
"@xtr-dev/payload-mailing/client": [
|
||||
"../src/exports/client.ts"
|
||||
],
|
||||
"temp-project/rsc": [
|
||||
"@xtr-dev/payload-mailing/rsc": [
|
||||
"../src/exports/rsc.ts"
|
||||
]
|
||||
},
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@xtr-dev/payload-mailing",
|
||||
"version": "0.1.3",
|
||||
"version": "0.1.11",
|
||||
"description": "Template-based email system with scheduling and job processing for PayloadCMS",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
@@ -23,8 +23,9 @@
|
||||
"dev:generate-importmap": "npm run dev:payload generate:importmap",
|
||||
"dev:generate-types": "npm run dev:payload generate:types",
|
||||
"dev:payload": "cross-env PAYLOAD_CONFIG_PATH=./dev/payload.config.ts payload",
|
||||
"generate:importmap": "npm run dev:generate-importmap",
|
||||
"generate:types": "npm run dev:generate-types",
|
||||
"payload": "cross-env NODE_OPTIONS=--no-deprecation payload",
|
||||
"generate:importmap": "npm run payload generate:importmap",
|
||||
"generate:types": "npm run payload generate:types",
|
||||
"lint": "eslint",
|
||||
"lint:fix": "eslint ./src --fix",
|
||||
"prepublishOnly": "npm run clean && npm run build",
|
||||
|
||||
31
payload.config.ts
Normal file
31
payload.config.ts
Normal file
@@ -0,0 +1,31 @@
|
||||
/**
|
||||
* This config is only used to generate types.
|
||||
*/
|
||||
|
||||
import { BaseDatabaseAdapter, buildConfig, Payload} from 'payload'
|
||||
import Emails from "./src/collections/Emails.js"
|
||||
import {createEmailTemplatesCollection} from "./src/collections/EmailTemplates.js"
|
||||
import path from "path"
|
||||
import { fileURLToPath } from 'url'
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url)
|
||||
const __dirname = path.dirname(__filename)
|
||||
|
||||
export default buildConfig({
|
||||
collections: [
|
||||
Emails,
|
||||
createEmailTemplatesCollection()
|
||||
],
|
||||
db: {
|
||||
allowIDOnCreate: undefined,
|
||||
defaultIDType: 'number',
|
||||
init: function (args: { payload: Payload; }): BaseDatabaseAdapter {
|
||||
throw new Error('Function not implemented.');
|
||||
},
|
||||
name: undefined
|
||||
},
|
||||
secret: '',
|
||||
typescript: {
|
||||
outputFile: path.resolve(__dirname, 'src/payload-types.ts'),
|
||||
}
|
||||
});
|
||||
@@ -12,13 +12,18 @@ export { default as EmailTemplates, createEmailTemplatesCollection } from './col
|
||||
export { default as Emails } from './collections/Emails.js'
|
||||
|
||||
// Jobs (includes the send email task)
|
||||
export { createMailingJobs, sendEmailJob } from './jobs/index.js'
|
||||
export { mailingJobs, sendEmailJob } from './jobs/index.js'
|
||||
export type { SendEmailTaskInput } from './jobs/sendEmailTask.js'
|
||||
|
||||
// Main email sending function
|
||||
export { sendEmail, type SendEmailOptions } from './sendEmail.js'
|
||||
export { default as sendEmailDefault } from './sendEmail.js'
|
||||
|
||||
// Utility functions for developers
|
||||
export {
|
||||
getMailing,
|
||||
renderTemplate,
|
||||
processEmails,
|
||||
retryFailedEmails,
|
||||
parseAndValidateEmails,
|
||||
} from './utils/helpers.js'
|
||||
@@ -2,21 +2,34 @@ import { processEmailsJob, ProcessEmailsJobData } from './processEmailsJob.js'
|
||||
import { sendEmailJob } from './sendEmailTask.js'
|
||||
import { MailingService } from '../services/MailingService.js'
|
||||
|
||||
export const createMailingJobs = (mailingService: MailingService): any[] => {
|
||||
return [
|
||||
export const mailingJobs = [
|
||||
{
|
||||
slug: 'processEmails',
|
||||
handler: async ({ job, req }: { job: any; req: any }) => {
|
||||
return processEmailsJob(
|
||||
// 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')
|
||||
}
|
||||
|
||||
// Use the existing mailing service from context
|
||||
await processEmailsJob(
|
||||
job as { data: ProcessEmailsJobData },
|
||||
{ req, mailingService }
|
||||
{ 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'
|
||||
@@ -1,4 +1,6 @@
|
||||
import { renderTemplate } from '../utils/helpers.js'
|
||||
import { sendEmail } from '../sendEmail.js'
|
||||
import { Email } from '../payload-types.js'
|
||||
import {BaseEmail} from "../types/index.js"
|
||||
|
||||
export interface SendEmailTaskInput {
|
||||
// Template mode fields
|
||||
@@ -115,118 +117,62 @@ export const sendEmailJob = {
|
||||
}
|
||||
}
|
||||
],
|
||||
handler: async ({ input, payload }: any) => {
|
||||
// Get mailing context from payload
|
||||
const mailingContext = (payload as any).mailing
|
||||
if (!mailingContext) {
|
||||
throw new Error('Mailing plugin not properly initialized')
|
||||
outputSchema: [
|
||||
{
|
||||
name: 'id',
|
||||
type: 'text' as const
|
||||
}
|
||||
|
||||
// Cast input to our expected type with validation
|
||||
],
|
||||
handler: async ({ input, payload }: any) => {
|
||||
// Cast input to our expected type
|
||||
const taskInput = input as SendEmailTaskInput
|
||||
|
||||
// Validate required fields
|
||||
if (!taskInput.to) {
|
||||
throw new Error('Field "to" is required')
|
||||
}
|
||||
|
||||
try {
|
||||
let html: string
|
||||
let text: string | undefined
|
||||
let subject: string
|
||||
// Prepare options for sendEmail based on task input
|
||||
const sendEmailOptions: any = {
|
||||
data: {}
|
||||
}
|
||||
|
||||
// Check if using template or direct email
|
||||
// If using template mode
|
||||
if (taskInput.templateSlug) {
|
||||
// Template mode: render the template
|
||||
const rendered = await renderTemplate(
|
||||
payload,
|
||||
taskInput.templateSlug,
|
||||
taskInput.variables || {}
|
||||
)
|
||||
html = rendered.html
|
||||
text = rendered.text
|
||||
subject = rendered.subject
|
||||
} else {
|
||||
// Direct email mode: use provided content
|
||||
if (!taskInput.subject || !taskInput.html) {
|
||||
throw new Error('Subject and HTML content are required when not using a template')
|
||||
sendEmailOptions.template = {
|
||||
slug: taskInput.templateSlug,
|
||||
variables: taskInput.variables || {}
|
||||
}
|
||||
subject = taskInput.subject
|
||||
html = taskInput.html
|
||||
text = taskInput.text
|
||||
}
|
||||
|
||||
// Parse and validate email addresses
|
||||
const parseEmails = (emails: string | string[] | undefined): string[] | undefined => {
|
||||
if (!emails) return undefined
|
||||
// Build data object from task input
|
||||
const dataFields = ['to', 'cc', 'bcc', 'subject', 'html', 'text', 'scheduledAt', 'priority']
|
||||
const additionalFields: string[] = []
|
||||
|
||||
let emailList: string[]
|
||||
if (Array.isArray(emails)) {
|
||||
emailList = emails
|
||||
} else {
|
||||
emailList = emails.split(',').map(email => email.trim()).filter(Boolean)
|
||||
// Copy standard fields
|
||||
dataFields.forEach(field => {
|
||||
if (taskInput[field] !== undefined) {
|
||||
sendEmailOptions.data[field] = taskInput[field]
|
||||
}
|
||||
})
|
||||
|
||||
// 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
|
||||
}
|
||||
|
||||
// Prepare email data
|
||||
const emailData: any = {
|
||||
to: parseEmails(taskInput.to),
|
||||
cc: parseEmails(taskInput.cc),
|
||||
bcc: parseEmails(taskInput.bcc),
|
||||
subject,
|
||||
html,
|
||||
text,
|
||||
priority: taskInput.priority || 5,
|
||||
}
|
||||
|
||||
// Add scheduled date if provided
|
||||
if (taskInput.scheduledAt) {
|
||||
emailData.scheduledAt = new Date(taskInput.scheduledAt).toISOString()
|
||||
}
|
||||
|
||||
// Add any additional fields from input (excluding the ones we've already handled)
|
||||
const handledFields = ['templateSlug', 'to', 'cc', 'bcc', 'variables', 'scheduledAt', 'priority']
|
||||
// Copy any additional custom fields
|
||||
Object.keys(taskInput).forEach(key => {
|
||||
if (!handledFields.includes(key)) {
|
||||
emailData[key] = taskInput[key]
|
||||
if (!['templateSlug', 'variables', ...dataFields].includes(key)) {
|
||||
sendEmailOptions.data[key] = taskInput[key]
|
||||
additionalFields.push(key)
|
||||
}
|
||||
})
|
||||
|
||||
// Create the email in the collection using configurable collection name
|
||||
const email = await payload.create({
|
||||
collection: mailingContext.collections.emails,
|
||||
data: emailData
|
||||
})
|
||||
// Use the sendEmail helper to create the email
|
||||
const email = await sendEmail<BaseEmail>(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: subject,
|
||||
recipients: emailData.to?.length || 0,
|
||||
scheduledAt: emailData.scheduledAt || null
|
||||
id: email.id,
|
||||
}
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : 'Unknown error'
|
||||
|
||||
return {
|
||||
success: false,
|
||||
error: errorMessage,
|
||||
templateSlug: taskInput.templateSlug,
|
||||
message: `Failed to queue email: ${errorMessage}`
|
||||
}
|
||||
throw new Error(`Failed to queue email: ${errorMessage}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
431
src/payload-types.ts
Normal file
431
src/payload-types.ts
Normal file
@@ -0,0 +1,431 @@
|
||||
/* tslint:disable */
|
||||
/* eslint-disable */
|
||||
/**
|
||||
* This file was automatically generated by Payload.
|
||||
* DO NOT MODIFY IT BY HAND. Instead, modify your source Payload config,
|
||||
* and re-run `payload generate:types` to regenerate this file.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Supported timezones in IANA format.
|
||||
*
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "supportedTimezones".
|
||||
*/
|
||||
export type SupportedTimezones =
|
||||
| 'Pacific/Midway'
|
||||
| 'Pacific/Niue'
|
||||
| 'Pacific/Honolulu'
|
||||
| 'Pacific/Rarotonga'
|
||||
| 'America/Anchorage'
|
||||
| 'Pacific/Gambier'
|
||||
| 'America/Los_Angeles'
|
||||
| 'America/Tijuana'
|
||||
| 'America/Denver'
|
||||
| 'America/Phoenix'
|
||||
| 'America/Chicago'
|
||||
| 'America/Guatemala'
|
||||
| 'America/New_York'
|
||||
| 'America/Bogota'
|
||||
| 'America/Caracas'
|
||||
| 'America/Santiago'
|
||||
| 'America/Buenos_Aires'
|
||||
| 'America/Sao_Paulo'
|
||||
| 'Atlantic/South_Georgia'
|
||||
| 'Atlantic/Azores'
|
||||
| 'Atlantic/Cape_Verde'
|
||||
| 'Europe/London'
|
||||
| 'Europe/Berlin'
|
||||
| 'Africa/Lagos'
|
||||
| 'Europe/Athens'
|
||||
| 'Africa/Cairo'
|
||||
| 'Europe/Moscow'
|
||||
| 'Asia/Riyadh'
|
||||
| 'Asia/Dubai'
|
||||
| 'Asia/Baku'
|
||||
| 'Asia/Karachi'
|
||||
| 'Asia/Tashkent'
|
||||
| 'Asia/Calcutta'
|
||||
| 'Asia/Dhaka'
|
||||
| 'Asia/Almaty'
|
||||
| 'Asia/Jakarta'
|
||||
| 'Asia/Bangkok'
|
||||
| 'Asia/Shanghai'
|
||||
| 'Asia/Singapore'
|
||||
| 'Asia/Tokyo'
|
||||
| 'Asia/Seoul'
|
||||
| 'Australia/Brisbane'
|
||||
| 'Australia/Sydney'
|
||||
| 'Pacific/Guam'
|
||||
| 'Pacific/Noumea'
|
||||
| 'Pacific/Auckland'
|
||||
| 'Pacific/Fiji';
|
||||
|
||||
export interface Config {
|
||||
auth: {
|
||||
users: UserAuthOperations;
|
||||
};
|
||||
blocks: {};
|
||||
collections: {
|
||||
emails: Email;
|
||||
'email-templates': EmailTemplate;
|
||||
users: User;
|
||||
'payload-locked-documents': PayloadLockedDocument;
|
||||
'payload-preferences': PayloadPreference;
|
||||
'payload-migrations': PayloadMigration;
|
||||
};
|
||||
collectionsJoins: {};
|
||||
collectionsSelect: {
|
||||
emails: EmailsSelect<false> | EmailsSelect<true>;
|
||||
'email-templates': EmailTemplatesSelect<false> | EmailTemplatesSelect<true>;
|
||||
users: UsersSelect<false> | UsersSelect<true>;
|
||||
'payload-locked-documents': PayloadLockedDocumentsSelect<false> | PayloadLockedDocumentsSelect<true>;
|
||||
'payload-preferences': PayloadPreferencesSelect<false> | PayloadPreferencesSelect<true>;
|
||||
'payload-migrations': PayloadMigrationsSelect<false> | PayloadMigrationsSelect<true>;
|
||||
};
|
||||
db: {
|
||||
defaultIDType: number;
|
||||
};
|
||||
globals: {};
|
||||
globalsSelect: {};
|
||||
locale: null;
|
||||
user: User & {
|
||||
collection: 'users';
|
||||
};
|
||||
jobs: {
|
||||
tasks: unknown;
|
||||
workflows: unknown;
|
||||
};
|
||||
}
|
||||
export interface UserAuthOperations {
|
||||
forgotPassword: {
|
||||
email: string;
|
||||
password: string;
|
||||
};
|
||||
login: {
|
||||
email: string;
|
||||
password: string;
|
||||
};
|
||||
registerFirstUser: {
|
||||
email: string;
|
||||
password: string;
|
||||
};
|
||||
unlock: {
|
||||
email: string;
|
||||
password: string;
|
||||
};
|
||||
}
|
||||
/**
|
||||
* Email delivery and status tracking
|
||||
*
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "emails".
|
||||
*/
|
||||
export interface Email {
|
||||
id: number;
|
||||
/**
|
||||
* Email template used (optional if custom content provided)
|
||||
*/
|
||||
template?: (number | null) | EmailTemplate;
|
||||
/**
|
||||
* Recipient email addresses
|
||||
*/
|
||||
to: string[];
|
||||
/**
|
||||
* CC email addresses
|
||||
*/
|
||||
cc?: string[] | null;
|
||||
/**
|
||||
* BCC email addresses
|
||||
*/
|
||||
bcc?: string[] | null;
|
||||
/**
|
||||
* Sender email address (optional, uses default if not provided)
|
||||
*/
|
||||
from?: string | null;
|
||||
/**
|
||||
* Reply-to email address
|
||||
*/
|
||||
replyTo?: string | null;
|
||||
/**
|
||||
* Email subject line
|
||||
*/
|
||||
subject: string;
|
||||
/**
|
||||
* Rendered HTML content of the email
|
||||
*/
|
||||
html: string;
|
||||
/**
|
||||
* Plain text version of the email
|
||||
*/
|
||||
text?: string | null;
|
||||
/**
|
||||
* Template variables used to render this email
|
||||
*/
|
||||
variables?:
|
||||
| {
|
||||
[k: string]: unknown;
|
||||
}
|
||||
| unknown[]
|
||||
| string
|
||||
| number
|
||||
| boolean
|
||||
| null;
|
||||
/**
|
||||
* When this email should be sent (leave empty for immediate)
|
||||
*/
|
||||
scheduledAt?: string | null;
|
||||
/**
|
||||
* When this email was actually sent
|
||||
*/
|
||||
sentAt?: string | null;
|
||||
/**
|
||||
* Current status of this email
|
||||
*/
|
||||
status: 'pending' | 'processing' | 'sent' | 'failed';
|
||||
/**
|
||||
* Number of send attempts made
|
||||
*/
|
||||
attempts?: number | null;
|
||||
/**
|
||||
* When the last send attempt was made
|
||||
*/
|
||||
lastAttemptAt?: string | null;
|
||||
/**
|
||||
* Last error message if send failed
|
||||
*/
|
||||
error?: string | null;
|
||||
/**
|
||||
* Email priority (1=highest, 10=lowest)
|
||||
*/
|
||||
priority?: number | null;
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "email-templates".
|
||||
*/
|
||||
export interface EmailTemplate {
|
||||
id: number;
|
||||
/**
|
||||
* A descriptive name for this email template
|
||||
*/
|
||||
name: string;
|
||||
/**
|
||||
* Unique identifier for this template (e.g., "welcome-email", "password-reset")
|
||||
*/
|
||||
slug: string;
|
||||
/**
|
||||
* Email subject line. You can use Handlebars variables like {{firstName}} or {{siteName}}.
|
||||
*/
|
||||
subject: string;
|
||||
/**
|
||||
* Email content with rich text formatting. Supports Handlebars variables like {{firstName}} and helpers like {{formatDate createdAt "long"}}. Content is converted to HTML and plain text automatically.
|
||||
*/
|
||||
content: {
|
||||
root: {
|
||||
type: string;
|
||||
children: {
|
||||
type: string;
|
||||
version: number;
|
||||
[k: string]: unknown;
|
||||
}[];
|
||||
direction: ('ltr' | 'rtl') | null;
|
||||
format: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | '';
|
||||
indent: number;
|
||||
version: number;
|
||||
};
|
||||
[k: string]: unknown;
|
||||
};
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "users".
|
||||
*/
|
||||
export interface User {
|
||||
id: number;
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
email: string;
|
||||
resetPasswordToken?: string | null;
|
||||
resetPasswordExpiration?: string | null;
|
||||
salt?: string | null;
|
||||
hash?: string | null;
|
||||
loginAttempts?: number | null;
|
||||
lockUntil?: string | null;
|
||||
sessions?:
|
||||
| {
|
||||
id: string;
|
||||
createdAt?: string | null;
|
||||
expiresAt: string;
|
||||
}[]
|
||||
| null;
|
||||
password?: string | null;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-locked-documents".
|
||||
*/
|
||||
export interface PayloadLockedDocument {
|
||||
id: number;
|
||||
document?:
|
||||
| ({
|
||||
relationTo: 'emails';
|
||||
value: number | Email;
|
||||
} | null)
|
||||
| ({
|
||||
relationTo: 'email-templates';
|
||||
value: number | EmailTemplate;
|
||||
} | null)
|
||||
| ({
|
||||
relationTo: 'users';
|
||||
value: number | User;
|
||||
} | null);
|
||||
globalSlug?: string | null;
|
||||
user: {
|
||||
relationTo: 'users';
|
||||
value: number | User;
|
||||
};
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-preferences".
|
||||
*/
|
||||
export interface PayloadPreference {
|
||||
id: number;
|
||||
user: {
|
||||
relationTo: 'users';
|
||||
value: number | User;
|
||||
};
|
||||
key?: string | null;
|
||||
value?:
|
||||
| {
|
||||
[k: string]: unknown;
|
||||
}
|
||||
| unknown[]
|
||||
| string
|
||||
| number
|
||||
| boolean
|
||||
| null;
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-migrations".
|
||||
*/
|
||||
export interface PayloadMigration {
|
||||
id: number;
|
||||
name?: string | null;
|
||||
batch?: number | null;
|
||||
updatedAt: string;
|
||||
createdAt: string;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "emails_select".
|
||||
*/
|
||||
export interface EmailsSelect<T extends boolean = true> {
|
||||
template?: T;
|
||||
to?: T;
|
||||
cc?: T;
|
||||
bcc?: T;
|
||||
from?: T;
|
||||
replyTo?: T;
|
||||
subject?: T;
|
||||
html?: T;
|
||||
text?: T;
|
||||
variables?: T;
|
||||
scheduledAt?: T;
|
||||
sentAt?: T;
|
||||
status?: T;
|
||||
attempts?: T;
|
||||
lastAttemptAt?: T;
|
||||
error?: T;
|
||||
priority?: T;
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "email-templates_select".
|
||||
*/
|
||||
export interface EmailTemplatesSelect<T extends boolean = true> {
|
||||
name?: T;
|
||||
slug?: T;
|
||||
subject?: T;
|
||||
content?: T;
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "users_select".
|
||||
*/
|
||||
export interface UsersSelect<T extends boolean = true> {
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
email?: T;
|
||||
resetPasswordToken?: T;
|
||||
resetPasswordExpiration?: T;
|
||||
salt?: T;
|
||||
hash?: T;
|
||||
loginAttempts?: T;
|
||||
lockUntil?: T;
|
||||
sessions?:
|
||||
| T
|
||||
| {
|
||||
id?: T;
|
||||
createdAt?: T;
|
||||
expiresAt?: T;
|
||||
};
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-locked-documents_select".
|
||||
*/
|
||||
export interface PayloadLockedDocumentsSelect<T extends boolean = true> {
|
||||
document?: T;
|
||||
globalSlug?: T;
|
||||
user?: T;
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-preferences_select".
|
||||
*/
|
||||
export interface PayloadPreferencesSelect<T extends boolean = true> {
|
||||
user?: T;
|
||||
key?: T;
|
||||
value?: T;
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "payload-migrations_select".
|
||||
*/
|
||||
export interface PayloadMigrationsSelect<T extends boolean = true> {
|
||||
name?: T;
|
||||
batch?: T;
|
||||
updatedAt?: T;
|
||||
createdAt?: T;
|
||||
}
|
||||
/**
|
||||
* This interface was referenced by `Config`'s JSON-Schema
|
||||
* via the `definition` "auth".
|
||||
*/
|
||||
export interface Auth {
|
||||
[k: string]: unknown;
|
||||
}
|
||||
|
||||
|
||||
declare module 'payload' {
|
||||
export interface GeneratedTypes extends Config {}
|
||||
}
|
||||
@@ -3,7 +3,7 @@ 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 { createMailingJobs, scheduleEmailsJob } from './jobs/index.js'
|
||||
import { mailingJobs, scheduleEmailsJob } from './jobs/index.js'
|
||||
|
||||
|
||||
export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Config): Config => {
|
||||
@@ -14,14 +14,6 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
|
||||
throw new Error('Invalid queue configuration: queue must be a non-empty string')
|
||||
}
|
||||
|
||||
// Create a factory function that will provide the mailing service once initialized
|
||||
const getMailingService = () => {
|
||||
if (!mailingService) {
|
||||
throw new Error('MailingService not yet initialized - this should only be called after plugin initialization')
|
||||
}
|
||||
return mailingService
|
||||
}
|
||||
let mailingService: MailingService
|
||||
|
||||
// Handle templates collection configuration
|
||||
const templatesConfig = pluginConfig.collections?.templates
|
||||
@@ -93,7 +85,7 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
|
||||
...(config.jobs || {}),
|
||||
tasks: [
|
||||
...(config.jobs?.tasks || []),
|
||||
// Jobs will be properly added after initialization
|
||||
...mailingJobs,
|
||||
],
|
||||
},
|
||||
onInit: async (payload: any) => {
|
||||
@@ -102,13 +94,7 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
|
||||
}
|
||||
|
||||
// Initialize mailing service with proper payload instance
|
||||
mailingService = new MailingService(payload, pluginConfig)
|
||||
|
||||
// Add mailing jobs to payload's job system
|
||||
const mailingJobs = createMailingJobs(mailingService)
|
||||
mailingJobs.forEach(job => {
|
||||
payload.jobs.tasks.push(job)
|
||||
})
|
||||
const mailingService = new MailingService(payload, pluginConfig)
|
||||
|
||||
// Add mailing context to payload for developer access
|
||||
;(payload as any).mailing = {
|
||||
|
||||
103
src/sendEmail.ts
Normal file
103
src/sendEmail.ts
Normal file
@@ -0,0 +1,103 @@
|
||||
import { Payload } from 'payload'
|
||||
import { getMailing, renderTemplate, parseAndValidateEmails } from './utils/helpers.js'
|
||||
import {Email} from "./payload-types.js"
|
||||
import {BaseEmail} from "./types/index.js"
|
||||
|
||||
// Options for sending emails
|
||||
export interface SendEmailOptions<T extends BaseEmail = BaseEmail> {
|
||||
// Template-based email
|
||||
template?: {
|
||||
slug: string
|
||||
variables?: Record<string, any>
|
||||
}
|
||||
// Direct email data
|
||||
data?: Partial<T>
|
||||
// Common options
|
||||
collectionSlug?: string // defaults to 'emails'
|
||||
}
|
||||
|
||||
/**
|
||||
* 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 BaseEmail = BaseEmail, ID = string | number>(
|
||||
payload: Payload,
|
||||
options: SendEmailOptions<T>
|
||||
): Promise<T & {id: ID}> => {
|
||||
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')
|
||||
}
|
||||
|
||||
// Validate required fields based on whether template was used
|
||||
if (options.template) {
|
||||
// When using template, subject and html should have been set by renderTemplate
|
||||
if (!emailData.subject || !emailData.html) {
|
||||
throw new Error(`Template rendering failed: template "${options.template.slug}" did not provide required subject and html content`)
|
||||
}
|
||||
} else {
|
||||
// When not using template, user must provide subject and html directly
|
||||
if (!emailData.subject || !emailData.html) {
|
||||
throw new Error('Fields "subject" and "html" are required when sending direct emails without a template')
|
||||
}
|
||||
}
|
||||
|
||||
// Process email addresses using shared validation (handle null values)
|
||||
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[])
|
||||
}
|
||||
|
||||
// Create the email in the collection with proper typing
|
||||
const email = await payload.create({
|
||||
collection: collectionSlug,
|
||||
data: emailData
|
||||
})
|
||||
|
||||
return email as T & {id: ID}
|
||||
}
|
||||
|
||||
export default sendEmail
|
||||
@@ -8,7 +8,7 @@ import {
|
||||
EmailTemplate,
|
||||
QueuedEmail,
|
||||
MailingTransportConfig,
|
||||
EmailObject
|
||||
BaseEmail
|
||||
} from '../types/index.js'
|
||||
import { serializeRichTextToHTML, serializeRichTextToText } from '../utils/richTextSerializer.js'
|
||||
|
||||
@@ -238,10 +238,10 @@ export class MailingService implements IMailingService {
|
||||
const email = await this.payload.findByID({
|
||||
collection: this.emailsCollection as any,
|
||||
id: emailId,
|
||||
}) as QueuedEmail
|
||||
}) as BaseEmail
|
||||
|
||||
let emailObject: EmailObject = {
|
||||
from: email.from || this.getDefaultFrom(),
|
||||
const mailOptions = {
|
||||
from: email.from,
|
||||
to: email.to,
|
||||
cc: email.cc || undefined,
|
||||
bcc: email.bcc || undefined,
|
||||
@@ -249,23 +249,6 @@ export class MailingService implements IMailingService {
|
||||
subject: email.subject,
|
||||
html: email.html,
|
||||
text: email.text || undefined,
|
||||
variables: email.variables,
|
||||
}
|
||||
|
||||
// Apply emailWrapper hook if configured
|
||||
if (this.config.emailWrapper) {
|
||||
emailObject = await this.config.emailWrapper(emailObject)
|
||||
}
|
||||
|
||||
const mailOptions = {
|
||||
from: emailObject.from,
|
||||
to: emailObject.to,
|
||||
cc: emailObject.cc || undefined,
|
||||
bcc: emailObject.bcc || undefined,
|
||||
replyTo: emailObject.replyTo || undefined,
|
||||
subject: emailObject.subject,
|
||||
html: emailObject.html,
|
||||
text: emailObject.text || undefined,
|
||||
}
|
||||
|
||||
await this.transporter.sendMail(mailOptions)
|
||||
|
||||
@@ -1,20 +1,9 @@
|
||||
import { Payload } from 'payload'
|
||||
import type { CollectionConfig, RichTextField, TypedCollection } from 'payload'
|
||||
import type { CollectionConfig, RichTextField } from 'payload'
|
||||
import { Transporter } from 'nodemailer'
|
||||
import {Email} from "../payload-types.js"
|
||||
|
||||
export interface EmailObject {
|
||||
to: string | string[]
|
||||
cc?: string | string[]
|
||||
bcc?: string | string[]
|
||||
from?: string
|
||||
replyTo?: string
|
||||
subject: string
|
||||
html: string
|
||||
text?: string
|
||||
variables?: Record<string, any>
|
||||
}
|
||||
|
||||
export type EmailWrapperHook = (email: EmailObject) => EmailObject | Promise<EmailObject>
|
||||
export type BaseEmail<TEmail = Email, TEmailTemplate = EmailTemplate> = Omit<TEmail, 'id' | 'template'> & {template: Omit<TEmailTemplate, 'id'>}
|
||||
|
||||
export type TemplateRendererHook = (template: string, variables: Record<string, any>) => string | Promise<string>
|
||||
|
||||
@@ -31,7 +20,6 @@ export interface MailingPluginConfig {
|
||||
queue?: string
|
||||
retryAttempts?: number
|
||||
retryDelay?: number
|
||||
emailWrapper?: EmailWrapperHook
|
||||
templateRenderer?: TemplateRendererHook
|
||||
templateEngine?: TemplateEngine
|
||||
richTextEditor?: RichTextField['editor']
|
||||
|
||||
@@ -1,6 +1,41 @@
|
||||
import { Payload } from 'payload'
|
||||
import { TemplateVariables } from '../types/index.js'
|
||||
|
||||
/**
|
||||
* Parse and validate email addresses
|
||||
* @internal
|
||||
*/
|
||||
export const parseAndValidateEmails = (emails: string | string[] | null | undefined): string[] | undefined => {
|
||||
if (!emails || emails === null) return undefined
|
||||
|
||||
let emailList: string[]
|
||||
if (Array.isArray(emails)) {
|
||||
emailList = emails
|
||||
} else {
|
||||
emailList = emails.split(',').map(email => email.trim()).filter(Boolean)
|
||||
}
|
||||
|
||||
// RFC 5322 compliant email validation
|
||||
const emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
|
||||
const invalidEmails = emailList.filter(email => {
|
||||
// Check basic format
|
||||
if (!emailRegex.test(email)) return true
|
||||
// Check for common invalid patterns
|
||||
if (email.includes('..') || email.startsWith('.') || email.endsWith('.')) return true
|
||||
if (email.includes('@.') || email.includes('.@')) return true
|
||||
// Check domain has at least one dot
|
||||
const parts = email.split('@')
|
||||
if (parts.length !== 2 || !parts[1].includes('.')) return true
|
||||
return false
|
||||
})
|
||||
|
||||
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
|
||||
if (!mailing) {
|
||||
|
||||
Reference in New Issue
Block a user