mirror of
https://github.com/xtr-dev/payload-mailing.git
synced 2025-12-10 00:03:23 +00:00
### 📚 Documentation
- Enhanced email customization documentation for the `emailWrapper` hook.
- Added examples for basic, advanced, and dynamic email layouts.
- Included guidelines for leveraging external CSS, assets, and template-specific layouts.
### 🔧 Improvements
- Updated `README.md` with detailed usage for consistent branding and responsive design in emails.
- Refined HTML structure and inline styles for improved readability and accessibility.
### 🛠 Maintenance
- Bumped version in `package.json` from `0.0.2` to `0.0.3`.
This commit is contained in:
247
README.md
247
README.md
@@ -158,9 +158,11 @@ The {{siteName}} Team
|
|||||||
|
|
||||||
## Advanced Features
|
## Advanced Features
|
||||||
|
|
||||||
### Email Wrapper Hook
|
### Custom HTML Layouts with Email Wrapper Hook
|
||||||
|
|
||||||
Use the `emailWrapper` hook to apply consistent layouts to all emails:
|
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
|
```typescript
|
||||||
mailingPlugin({
|
mailingPlugin({
|
||||||
@@ -171,13 +173,20 @@ mailingPlugin({
|
|||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<meta charset="utf-8">
|
<meta charset="utf-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
<title>${email.subject}</title>
|
<title>${email.subject}</title>
|
||||||
<style>
|
<style>
|
||||||
body { font-family: Arial, sans-serif; margin: 0; padding: 20px; }
|
body { font-family: Arial, sans-serif; margin: 0; padding: 20px; background-color: #f4f4f4; }
|
||||||
.container { max-width: 600px; margin: 0 auto; background: white; }
|
.container { max-width: 600px; margin: 0 auto; background: white; border-radius: 8px; overflow: hidden; }
|
||||||
.header { background: #007bff; color: white; padding: 20px; }
|
.header { background: #007bff; color: white; padding: 20px; text-align: center; }
|
||||||
.content { padding: 30px; }
|
.content { padding: 30px; line-height: 1.6; }
|
||||||
.footer { background: #f8f9fa; padding: 15px; text-align: center; }
|
.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>
|
</style>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
@@ -189,7 +198,9 @@ mailingPlugin({
|
|||||||
${email.html}
|
${email.html}
|
||||||
</div>
|
</div>
|
||||||
<div class="footer">
|
<div class="footer">
|
||||||
© 2024 My Company. All rights reserved.
|
© 2024 My Company. All rights reserved.<br>
|
||||||
|
<a href="#" style="color: #007bff;">Unsubscribe</a> |
|
||||||
|
<a href="#" style="color: #007bff;">Contact Support</a>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</body>
|
</body>
|
||||||
@@ -199,12 +210,230 @@ mailingPlugin({
|
|||||||
return {
|
return {
|
||||||
...email,
|
...email,
|
||||||
html: wrappedHtml,
|
html: wrappedHtml,
|
||||||
text: `MY COMPANY\n\n${email.text}\n\n© 2024 My Company`
|
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
|
### Custom Rich Text Editor
|
||||||
|
|
||||||
Override the rich text editor used for templates:
|
Override the rich text editor used for templates:
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "@xtr-dev/payload-mailing",
|
"name": "@xtr-dev/payload-mailing",
|
||||||
"version": "0.0.2",
|
"version": "0.0.3",
|
||||||
"description": "Template-based email system with scheduling and job processing for PayloadCMS",
|
"description": "Template-based email system with scheduling and job processing for PayloadCMS",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"main": "dist/index.js",
|
"main": "dist/index.js",
|
||||||
|
|||||||
Reference in New Issue
Block a user