### 📚 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`.
2025-12-10 00:03:23 +00:00 · 2025-09-13 14:57:25 +02:00
parent d632a8686a
commit aac6554a40
2 changed files with 239 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -158,9 +158,11 @@ The {{siteName}} Team

 ## 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
 mailingPlugin({
@@ -171,13 +173,20 @@ mailingPlugin({
      <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; }
-          .container { max-width: 600px; margin: 0 auto; background: white; }
-          .header { background: #007bff; color: white; padding: 20px; }
-          .content { padding: 30px; }
-          .footer { background: #f8f9fa; padding: 15px; text-align: center; }
+          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>
@@ -189,7 +198,9 @@ mailingPlugin({
            ${email.html}
          </div>
          <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>
      </body>
@@ -199,12 +210,230 @@ mailingPlugin({
    return {
      ...email,
      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

 Override the rich text editor used for templates:
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "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",
  "type": "module",
  "main": "dist/index.js",