mirror of
https://github.com/xtr-dev/payload-mailing.git
synced 2025-12-10 08:13:23 +00:00
Compare commits
8 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
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.11",
|
||||
"description": "Template-based email system with scheduling and job processing for PayloadCMS",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { sendEmail } from '../sendEmail.js'
|
||||
import { Email } from '../payload-types.js'
|
||||
import {BaseEmail} from "../types/index.js"
|
||||
|
||||
export interface SendEmailTaskInput {
|
||||
// Template mode fields
|
||||
@@ -116,6 +117,12 @@ 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
|
||||
@@ -154,18 +161,12 @@ export const sendEmailJob = {
|
||||
})
|
||||
|
||||
// Use the sendEmail helper to create the email
|
||||
const email = await sendEmail<Email>(payload, sendEmailOptions)
|
||||
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: email.subject,
|
||||
recipients: Array.isArray(email.to) ? email.to.length : 1,
|
||||
scheduledAt: email.scheduledAt || null
|
||||
id: email.id,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
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 Email = Email> {
|
||||
export interface SendEmailOptions<T extends BaseEmail = BaseEmail> {
|
||||
// Template-based email
|
||||
template?: {
|
||||
slug: string
|
||||
@@ -35,10 +36,10 @@ export interface SendEmailOptions<T extends Email = Email> {
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
export const sendEmail = async <T extends Email = Email>(
|
||||
export const sendEmail = async <T extends BaseEmail = BaseEmail, ID = string | number>(
|
||||
payload: Payload,
|
||||
options: SendEmailOptions<T>
|
||||
): Promise<T> => {
|
||||
): Promise<T & {id: ID}> => {
|
||||
const mailing = getMailing(payload)
|
||||
const collectionSlug = options.collectionSlug || mailing.collections.emails || 'emails'
|
||||
|
||||
@@ -96,7 +97,7 @@ export const sendEmail = async <T extends Email = Email>(
|
||||
data: emailData
|
||||
})
|
||||
|
||||
return email as T
|
||||
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']
|
||||
|
||||
Reference in New Issue
Block a user