From aac6554a40c912c87406bcab9a60b2766cf2243a Mon Sep 17 00:00:00 2001 From: Bas van den Aakster Date: Sat, 13 Sep 2025 14:57:25 +0200 Subject: [PATCH] =?UTF-8?q?###=20=F0=9F=93=9A=20Documentation=20-=20Enhanc?= =?UTF-8?q?ed=20email=20customization=20documentation=20for=20the=20`email?= =?UTF-8?q?Wrapper`=20hook.=20-=20Added=20examples=20for=20basic,=20advanc?= =?UTF-8?q?ed,=20and=20dynamic=20email=20layouts.=20-=20Included=20guideli?= =?UTF-8?q?nes=20for=20leveraging=20external=20CSS,=20assets,=20and=20temp?= =?UTF-8?q?late-specific=20layouts.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### 🔧 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`. --- README.md | 247 +++++++++++++++++++++++++++++++++++++++++++++++++-- package.json | 2 +- 2 files changed, 239 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4a1b760..abe6e84 100644 --- 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({ + ${email.subject} @@ -189,7 +198,9 @@ mailingPlugin({ ${email.html}
- © 2024 My Company. All rights reserved. + © 2024 My Company. All rights reserved.
+ Unsubscribe | + Contact Support
@@ -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 = ` + + + + + + + ${email.subject} + + + + +
+ + + +
+ + + ` + + // 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 = ` + + + + + + ${email.subject} + + + + + +
+ My Company +
+ ${email.html} +
+ Footer +
+ + + `; + + 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 = ` + + + + + ${email.subject} + + + +
+ ${email.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: diff --git a/package.json b/package.json index 2f3f60b..e9ef4b7 100644 --- 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",