mirror of
https://github.com/xtr-dev/payload-mailing.git
synced 2025-12-10 16:23:23 +00:00
Compare commits
36 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
f12ac8172e | ||
| 347cd33e13 | |||
|
|
672ab3236a | ||
| c7db65980a | |||
| 624dc12471 | |||
| e20ebe27bf | |||
|
|
7f04275d39 | ||
| 20afe30e88 | |||
| 02b3fecadf | |||
|
|
ea87f14308 | ||
| 6886027727 | |||
| 965569be06 | |||
|
|
ff788c1ecf | ||
| c12438aaa2 | |||
| 4dcbc1446a | |||
|
|
72f3d7f66d | ||
| ecc0b0a73e | |||
| a959673fc1 | |||
| 8809db6aff | |||
|
|
5905f732de | ||
| 4c495a72b0 | |||
| 8518c716e8 | |||
| 570190be01 | |||
|
|
685875d1b9 | ||
| 79044b7bc3 | |||
| e7304fe1a2 | |||
| 790eedfee7 | |||
| 9520ec5ed1 | |||
|
|
768b70a003 | ||
| e91ab7e54e | |||
| 06f9c2cb5b | |||
|
|
21b22a033a | ||
| 6ad90874cf | |||
|
|
03f1f62fbf | ||
| e55e4197d3 | |||
| 2e6feccf54 |
282
README.md
282
README.md
@@ -139,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!')
|
||||
@@ -227,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"}}.
|
||||
@@ -238,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:
|
||||
|
||||
@@ -282,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,6 +1,6 @@
|
||||
{
|
||||
"name": "@xtr-dev/payload-mailing",
|
||||
"version": "0.1.8",
|
||||
"version": "0.1.19",
|
||||
"description": "Template-based email system with scheduling and job processing for PayloadCMS",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
|
||||
@@ -49,6 +49,13 @@ const Emails: CollectionConfig = {
|
||||
description: 'Sender email address (optional, uses default if not provided)',
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'fromName',
|
||||
type: 'text',
|
||||
admin: {
|
||||
description: 'Sender display name (optional, e.g., "John Doe" for "John Doe <john@example.com>")',
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'replyTo',
|
||||
type: 'text',
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { sendEmail } from '../sendEmail.js'
|
||||
import { Email } from '../payload-types.js'
|
||||
import { BaseEmailDocument } from '../types/index.js'
|
||||
|
||||
export interface SendEmailTaskInput {
|
||||
// Template mode fields
|
||||
@@ -15,13 +15,55 @@ export interface SendEmailTaskInput {
|
||||
to: string | string[]
|
||||
cc?: string | string[]
|
||||
bcc?: string | string[]
|
||||
scheduledAt?: string // ISO date string
|
||||
from?: string
|
||||
fromName?: string
|
||||
replyTo?: string
|
||||
scheduledAt?: string | Date // ISO date string or Date object
|
||||
priority?: number
|
||||
|
||||
// Allow any additional fields that users might have in their email collection
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
/**
|
||||
* Transforms task input into sendEmail options by separating template and data fields
|
||||
*/
|
||||
function transformTaskInputToSendEmailOptions(taskInput: SendEmailTaskInput) {
|
||||
const sendEmailOptions: any = {
|
||||
data: {}
|
||||
}
|
||||
|
||||
// If using template mode, set template options
|
||||
if (taskInput.templateSlug) {
|
||||
sendEmailOptions.template = {
|
||||
slug: taskInput.templateSlug,
|
||||
variables: taskInput.variables || {}
|
||||
}
|
||||
}
|
||||
|
||||
// Standard email fields that should be copied to data
|
||||
const standardFields = ['to', 'cc', 'bcc', 'from', 'fromName', 'replyTo', 'subject', 'html', 'text', 'scheduledAt', 'priority']
|
||||
|
||||
// Template-specific fields that should not be copied to data
|
||||
const templateFields = ['templateSlug', 'variables']
|
||||
|
||||
// Copy standard fields to data
|
||||
standardFields.forEach(field => {
|
||||
if (taskInput[field] !== undefined) {
|
||||
sendEmailOptions.data[field] = taskInput[field]
|
||||
}
|
||||
})
|
||||
|
||||
// Copy any additional custom fields that aren't template or standard fields
|
||||
Object.keys(taskInput).forEach(key => {
|
||||
if (!templateFields.includes(key) && !standardFields.includes(key)) {
|
||||
sendEmailOptions.data[key] = taskInput[key]
|
||||
}
|
||||
})
|
||||
|
||||
return sendEmailOptions
|
||||
}
|
||||
|
||||
export const sendEmailJob = {
|
||||
slug: 'send-email',
|
||||
label: 'Send Email',
|
||||
@@ -96,6 +138,30 @@ export const sendEmailJob = {
|
||||
description: 'Optional comma-separated list of BCC email addresses'
|
||||
}
|
||||
},
|
||||
{
|
||||
name: 'from',
|
||||
type: 'text' as const,
|
||||
label: 'From Email',
|
||||
admin: {
|
||||
description: 'Optional sender email address (uses default if not provided)'
|
||||
}
|
||||
},
|
||||
{
|
||||
name: 'fromName',
|
||||
type: 'text' as const,
|
||||
label: 'From Name',
|
||||
admin: {
|
||||
description: 'Optional sender display name (e.g., "John Doe")'
|
||||
}
|
||||
},
|
||||
{
|
||||
name: 'replyTo',
|
||||
type: 'text' as const,
|
||||
label: 'Reply To',
|
||||
admin: {
|
||||
description: 'Optional reply-to email address'
|
||||
}
|
||||
},
|
||||
{
|
||||
name: 'scheduledAt',
|
||||
type: 'date' as const,
|
||||
@@ -116,62 +182,40 @@ export const sendEmailJob = {
|
||||
}
|
||||
}
|
||||
],
|
||||
outputSchema: [
|
||||
{
|
||||
name: 'id',
|
||||
type: 'text' as const
|
||||
}
|
||||
],
|
||||
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)
|
||||
}
|
||||
})
|
||||
// Transform task input into sendEmail options using helper function
|
||||
const sendEmailOptions = transformTaskInputToSendEmailOptions(taskInput)
|
||||
|
||||
// Use the sendEmail helper to create the email
|
||||
const email = await sendEmail<Email>(payload, sendEmailOptions)
|
||||
const email = await sendEmail<BaseEmailDocument>(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
|
||||
id: email.id,
|
||||
}
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : 'Unknown error'
|
||||
throw new Error(`Failed to queue email: ${errorMessage}`)
|
||||
if (error instanceof Error) {
|
||||
// Preserve original error and stack trace
|
||||
const wrappedError = new Error(`Failed to queue email: ${error.message}`)
|
||||
wrappedError.stack = error.stack
|
||||
wrappedError.cause = error
|
||||
throw wrappedError
|
||||
} else {
|
||||
throw new Error(`Failed to queue email: ${String(error)}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -143,6 +143,10 @@ export interface Email {
|
||||
* Sender email address (optional, uses default if not provided)
|
||||
*/
|
||||
from?: string | null;
|
||||
/**
|
||||
* Sender display name (optional, e.g., "John Doe" for "John Doe <john@example.com>")
|
||||
*/
|
||||
fromName?: string | null;
|
||||
/**
|
||||
* Reply-to email address
|
||||
*/
|
||||
@@ -336,6 +340,7 @@ export interface EmailsSelect<T extends boolean = true> {
|
||||
cc?: T;
|
||||
bcc?: T;
|
||||
from?: T;
|
||||
fromName?: T;
|
||||
replyTo?: T;
|
||||
subject?: T;
|
||||
html?: T;
|
||||
|
||||
@@ -74,10 +74,15 @@ export const mailingPlugin = (pluginConfig: MailingPluginConfig) => (config: Con
|
||||
}),
|
||||
} satisfies CollectionConfig
|
||||
|
||||
// Filter out any existing collections with the same slugs to prevent duplicates
|
||||
const existingCollections = (config.collections || []).filter(
|
||||
(collection) => collection.slug !== templatesSlug && collection.slug !== emailsSlug
|
||||
)
|
||||
|
||||
return {
|
||||
...config,
|
||||
collections: [
|
||||
...(config.collections || []),
|
||||
...existingCollections,
|
||||
templatesCollection,
|
||||
emailsCollection,
|
||||
],
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
import { Payload } from 'payload'
|
||||
import { getMailing, renderTemplate, parseAndValidateEmails } from './utils/helpers.js'
|
||||
import {Email} from "./payload-types.js"
|
||||
import { BaseEmailDocument } from './types/index.js'
|
||||
|
||||
// Options for sending emails
|
||||
export interface SendEmailOptions<T extends Email = Email> {
|
||||
export interface SendEmailOptions<T extends BaseEmailDocument = BaseEmailDocument> {
|
||||
// Template-based email
|
||||
template?: {
|
||||
slug: string
|
||||
@@ -35,14 +35,14 @@ export interface SendEmailOptions<T extends Email = Email> {
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
export const sendEmail = async <T extends Email = Email>(
|
||||
export const sendEmail = async <TEmail extends BaseEmailDocument = BaseEmailDocument>(
|
||||
payload: Payload,
|
||||
options: SendEmailOptions<T>
|
||||
): Promise<T> => {
|
||||
options: SendEmailOptions<TEmail>
|
||||
): Promise<TEmail> => {
|
||||
const mailing = getMailing(payload)
|
||||
const collectionSlug = options.collectionSlug || mailing.collections.emails || 'emails'
|
||||
|
||||
let emailData: Partial<T> = { ...options.data } as Partial<T>
|
||||
let emailData: Partial<TEmail> = { ...options.data } as Partial<TEmail>
|
||||
|
||||
// If using a template, render it first
|
||||
if (options.template) {
|
||||
@@ -58,7 +58,7 @@ export const sendEmail = async <T extends Email = Email>(
|
||||
subject,
|
||||
html,
|
||||
text,
|
||||
} as Partial<T>
|
||||
} as Partial<TEmail>
|
||||
}
|
||||
|
||||
// Validate required fields
|
||||
@@ -83,12 +83,50 @@ export const sendEmail = async <T extends Email = Email>(
|
||||
if (emailData.to) {
|
||||
emailData.to = parseAndValidateEmails(emailData.to as string | string[])
|
||||
}
|
||||
if (emailData.cc) {
|
||||
if (emailData.cc && emailData.cc !== null) {
|
||||
emailData.cc = parseAndValidateEmails(emailData.cc as string | string[])
|
||||
}
|
||||
if (emailData.bcc) {
|
||||
if (emailData.bcc && emailData.bcc !== null) {
|
||||
emailData.bcc = parseAndValidateEmails(emailData.bcc as string | string[])
|
||||
}
|
||||
if (emailData.replyTo && emailData.replyTo !== null) {
|
||||
const validated = parseAndValidateEmails(emailData.replyTo as string | string[])
|
||||
// replyTo should be a single email, so take the first one if array
|
||||
emailData.replyTo = validated && validated.length > 0 ? validated[0] : undefined
|
||||
}
|
||||
if (emailData.from && emailData.from !== null) {
|
||||
const validated = parseAndValidateEmails(emailData.from as string | string[])
|
||||
// from should be a single email, so take the first one if array
|
||||
emailData.from = validated && validated.length > 0 ? validated[0] : undefined
|
||||
}
|
||||
|
||||
// Sanitize fromName to prevent header injection
|
||||
if (emailData.fromName && emailData.fromName !== null) {
|
||||
emailData.fromName = emailData.fromName
|
||||
.trim()
|
||||
// Remove/replace newlines and carriage returns to prevent header injection
|
||||
.replace(/[\r\n]/g, ' ')
|
||||
// Remove control characters (except space and printable characters)
|
||||
.replace(/[\x00-\x1F\x7F-\x9F]/g, '')
|
||||
// Note: We don't escape quotes here as that's handled in MailingService
|
||||
}
|
||||
|
||||
// Normalize Date objects to ISO strings for consistent database storage
|
||||
if (emailData.scheduledAt instanceof Date) {
|
||||
emailData.scheduledAt = emailData.scheduledAt.toISOString()
|
||||
}
|
||||
if (emailData.sentAt instanceof Date) {
|
||||
emailData.sentAt = emailData.sentAt.toISOString()
|
||||
}
|
||||
if (emailData.lastAttemptAt instanceof Date) {
|
||||
emailData.lastAttemptAt = emailData.lastAttemptAt.toISOString()
|
||||
}
|
||||
if (emailData.createdAt instanceof Date) {
|
||||
emailData.createdAt = emailData.createdAt.toISOString()
|
||||
}
|
||||
if (emailData.updatedAt instanceof Date) {
|
||||
emailData.updatedAt = emailData.updatedAt.toISOString()
|
||||
}
|
||||
|
||||
// Create the email in the collection with proper typing
|
||||
const email = await payload.create({
|
||||
@@ -96,7 +134,12 @@ export const sendEmail = async <T extends Email = Email>(
|
||||
data: emailData
|
||||
})
|
||||
|
||||
return email as T
|
||||
// Validate that the created email has the expected structure
|
||||
if (!email || typeof email !== 'object' || !email.id) {
|
||||
throw new Error('Failed to create email: invalid response from database')
|
||||
}
|
||||
|
||||
return email as TEmail
|
||||
}
|
||||
|
||||
export default sendEmail
|
||||
|
||||
@@ -5,10 +5,8 @@ import {
|
||||
MailingPluginConfig,
|
||||
TemplateVariables,
|
||||
MailingService as IMailingService,
|
||||
EmailTemplate,
|
||||
QueuedEmail,
|
||||
MailingTransportConfig,
|
||||
EmailObject
|
||||
BaseEmail, BaseEmailTemplate, BaseEmailDocument, BaseEmailTemplateDocument
|
||||
} from '../types/index.js'
|
||||
import { serializeRichTextToHTML, serializeRichTextToText } from '../utils/richTextSerializer.js'
|
||||
|
||||
@@ -65,15 +63,39 @@ export class MailingService implements IMailingService {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Sanitizes a display name for use in email headers to prevent header injection
|
||||
* and ensure proper formatting
|
||||
*/
|
||||
private sanitizeDisplayName(name: string): string {
|
||||
return name
|
||||
.trim()
|
||||
// Remove/replace newlines and carriage returns to prevent header injection
|
||||
.replace(/[\r\n]/g, ' ')
|
||||
// Remove control characters (except space and printable characters)
|
||||
.replace(/[\x00-\x1F\x7F-\x9F]/g, '')
|
||||
// Escape quotes to prevent malformed headers
|
||||
.replace(/"/g, '\\"')
|
||||
}
|
||||
|
||||
/**
|
||||
* Formats an email address with optional display name
|
||||
*/
|
||||
private formatEmailAddress(email: string, displayName?: string | null): string {
|
||||
if (displayName && displayName.trim()) {
|
||||
const sanitizedName = this.sanitizeDisplayName(displayName)
|
||||
return `"${sanitizedName}" <${email}>`
|
||||
}
|
||||
return email
|
||||
}
|
||||
|
||||
private getDefaultFrom(): string {
|
||||
const fromEmail = this.config.defaultFrom
|
||||
const fromName = this.config.defaultFromName
|
||||
|
||||
// Check if fromName exists, is not empty after trimming, and fromEmail exists
|
||||
if (fromName && fromName.trim() && fromEmail) {
|
||||
// Escape quotes in the display name to prevent malformed headers
|
||||
const escapedName = fromName.replace(/"/g, '\\"')
|
||||
return `"${escapedName}" <${fromEmail}>`
|
||||
return this.formatEmailAddress(fromEmail, fromName)
|
||||
}
|
||||
|
||||
return fromEmail || ''
|
||||
@@ -133,7 +155,7 @@ export class MailingService implements IMailingService {
|
||||
}
|
||||
|
||||
const emailContent = await this.renderEmailTemplate(template, variables)
|
||||
const subject = await this.renderTemplateString(template.subject, variables)
|
||||
const subject = await this.renderTemplateString(template.subject || '', variables)
|
||||
|
||||
return {
|
||||
html: emailContent.html,
|
||||
@@ -238,10 +260,18 @@ export class MailingService implements IMailingService {
|
||||
const email = await this.payload.findByID({
|
||||
collection: this.emailsCollection as any,
|
||||
id: emailId,
|
||||
}) as QueuedEmail
|
||||
}) as BaseEmailDocument
|
||||
|
||||
let emailObject: EmailObject = {
|
||||
from: email.from || this.getDefaultFrom(),
|
||||
// Combine from and fromName for nodemailer using proper sanitization
|
||||
let fromField: string
|
||||
if (email.from) {
|
||||
fromField = this.formatEmailAddress(email.from, email.fromName)
|
||||
} else {
|
||||
fromField = this.getDefaultFrom()
|
||||
}
|
||||
|
||||
const mailOptions = {
|
||||
from: fromField,
|
||||
to: email.to,
|
||||
cc: email.cc || undefined,
|
||||
bcc: email.bcc || undefined,
|
||||
@@ -249,23 +279,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)
|
||||
@@ -304,7 +317,7 @@ export class MailingService implements IMailingService {
|
||||
const email = await this.payload.findByID({
|
||||
collection: this.emailsCollection as any,
|
||||
id: emailId,
|
||||
}) as QueuedEmail
|
||||
}) as BaseEmail
|
||||
|
||||
const newAttempts = (email.attempts || 0) + 1
|
||||
|
||||
@@ -319,7 +332,7 @@ export class MailingService implements IMailingService {
|
||||
return newAttempts
|
||||
}
|
||||
|
||||
private async getTemplateBySlug(templateSlug: string): Promise<EmailTemplate | null> {
|
||||
private async getTemplateBySlug(templateSlug: string): Promise<BaseEmailTemplateDocument | null> {
|
||||
try {
|
||||
const { docs } = await this.payload.find({
|
||||
collection: this.templatesCollection as any,
|
||||
@@ -331,7 +344,7 @@ export class MailingService implements IMailingService {
|
||||
limit: 1,
|
||||
})
|
||||
|
||||
return docs.length > 0 ? docs[0] as EmailTemplate : null
|
||||
return docs.length > 0 ? docs[0] as BaseEmailTemplateDocument : null
|
||||
} catch (error) {
|
||||
console.error(`Template with slug '${templateSlug}' not found:`, error)
|
||||
return null
|
||||
@@ -396,7 +409,7 @@ export class MailingService implements IMailingService {
|
||||
})
|
||||
}
|
||||
|
||||
private async renderEmailTemplate(template: EmailTemplate, variables: Record<string, any> = {}): Promise<{ html: string; text: string }> {
|
||||
private async renderEmailTemplate(template: BaseEmailTemplateDocument, variables: Record<string, any> = {}): Promise<{ html: string; text: string }> {
|
||||
if (!template.content) {
|
||||
return { html: '', text: '' }
|
||||
}
|
||||
|
||||
@@ -1,20 +1,48 @@
|
||||
import { Payload } from 'payload'
|
||||
import type { CollectionConfig, RichTextField, TypedCollection } from 'payload'
|
||||
import type { CollectionConfig, RichTextField } from 'payload'
|
||||
import { Transporter } from 'nodemailer'
|
||||
|
||||
export interface EmailObject {
|
||||
to: string | string[]
|
||||
cc?: string | string[]
|
||||
bcc?: string | string[]
|
||||
from?: string
|
||||
replyTo?: string
|
||||
// JSON value type that matches Payload's JSON field type
|
||||
export type JSONValue = string | number | boolean | { [k: string]: unknown } | unknown[] | null | undefined
|
||||
|
||||
// Generic base interfaces that work with any ID type and null values
|
||||
export interface BaseEmailDocument {
|
||||
id: string | number
|
||||
template?: any
|
||||
to: string[]
|
||||
cc?: string[] | null
|
||||
bcc?: string[] | null
|
||||
from?: string | null
|
||||
fromName?: string | null
|
||||
replyTo?: string | null
|
||||
subject: string
|
||||
html: string
|
||||
text?: string
|
||||
variables?: Record<string, any>
|
||||
text?: string | null
|
||||
variables?: JSONValue
|
||||
scheduledAt?: string | Date | null
|
||||
sentAt?: string | Date | null
|
||||
status?: 'pending' | 'processing' | 'sent' | 'failed' | null
|
||||
attempts?: number | null
|
||||
lastAttemptAt?: string | Date | null
|
||||
error?: string | null
|
||||
priority?: number | null
|
||||
createdAt?: string | Date | null
|
||||
updatedAt?: string | Date | null
|
||||
}
|
||||
|
||||
export type EmailWrapperHook = (email: EmailObject) => EmailObject | Promise<EmailObject>
|
||||
export interface BaseEmailTemplateDocument {
|
||||
id: string | number
|
||||
name: string
|
||||
slug: string
|
||||
subject?: string | null
|
||||
content?: any
|
||||
createdAt?: string | Date | null
|
||||
updatedAt?: string | Date | null
|
||||
}
|
||||
|
||||
export type BaseEmail<TEmail extends BaseEmailDocument = BaseEmailDocument, TEmailTemplate extends BaseEmailTemplateDocument = BaseEmailTemplateDocument> = Omit<TEmail, 'id' | 'template'> & {template: Omit<TEmailTemplate, 'id'> | TEmailTemplate['id'] | undefined | null}
|
||||
|
||||
export type BaseEmailTemplate<TEmailTemplate extends BaseEmailTemplateDocument = BaseEmailTemplateDocument> = Omit<TEmailTemplate, 'id'>
|
||||
|
||||
export type TemplateRendererHook = (template: string, variables: Record<string, any>) => string | Promise<string>
|
||||
|
||||
@@ -31,7 +59,6 @@ export interface MailingPluginConfig {
|
||||
queue?: string
|
||||
retryAttempts?: number
|
||||
retryDelay?: number
|
||||
emailWrapper?: EmailWrapperHook
|
||||
templateRenderer?: TemplateRendererHook
|
||||
templateEngine?: TemplateEngine
|
||||
richTextEditor?: RichTextField['editor']
|
||||
@@ -49,36 +76,27 @@ export interface MailingTransportConfig {
|
||||
}
|
||||
}
|
||||
|
||||
export interface EmailTemplate {
|
||||
id: string
|
||||
name: string
|
||||
slug: string
|
||||
subject: string
|
||||
content: any // Lexical editor state
|
||||
createdAt: string
|
||||
updatedAt: string
|
||||
}
|
||||
|
||||
|
||||
export interface QueuedEmail {
|
||||
id: string
|
||||
template?: string
|
||||
template?: string | null
|
||||
to: string[]
|
||||
cc?: string[]
|
||||
bcc?: string[]
|
||||
from?: string
|
||||
replyTo?: string
|
||||
cc?: string[] | null
|
||||
bcc?: string[] | null
|
||||
from?: string | null
|
||||
fromName?: string | null
|
||||
replyTo?: string | null
|
||||
subject: string
|
||||
html: string
|
||||
text?: string
|
||||
variables?: Record<string, any>
|
||||
scheduledAt?: string
|
||||
sentAt?: string
|
||||
text?: string | null
|
||||
variables?: JSONValue
|
||||
scheduledAt?: string | Date | null
|
||||
sentAt?: string | Date | null
|
||||
status: 'pending' | 'processing' | 'sent' | 'failed'
|
||||
attempts: number
|
||||
lastAttemptAt?: string
|
||||
error?: string
|
||||
priority?: number
|
||||
lastAttemptAt?: string | Date | null
|
||||
error?: string | null
|
||||
priority?: number | null
|
||||
createdAt: string
|
||||
updatedAt: string
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user