Add beforeSend hook for email customization

- Add BeforeSendHook type and BeforeSendMailOptions interface
- Implement hook execution in MailingService before sending emails
- Hook allows adding attachments, headers, and modifying email options
- Add comprehensive documentation with examples
- Bump version to 0.1.20

src/sendEmail.ts

@@ -83,25 +83,25 @@ export const sendEmail = async <TEmail extends BaseEmailDocument = BaseEmailDocu
   if (emailData.to) {
     emailData.to = parseAndValidateEmails(emailData.to as string | string[])
   }
-  if (emailData.cc && emailData.cc !== null) {
+  if (emailData.cc) {
     emailData.cc = parseAndValidateEmails(emailData.cc as string | string[])
   }
-  if (emailData.bcc && emailData.bcc !== null) {
+  if (emailData.bcc) {
     emailData.bcc = parseAndValidateEmails(emailData.bcc as string | string[])
   }
-  if (emailData.replyTo && emailData.replyTo !== null) {
+  if (emailData.replyTo) {
     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) {
+  if (emailData.from) {
     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) {
+  if (emailData.fromName) {
     emailData.fromName = emailData.fromName
       .trim()
       // Remove/replace newlines and carriage returns to prevent header injection

src/services/MailingService.ts

@@ -270,7 +270,7 @@ export class MailingService implements IMailingService {
         fromField = this.getDefaultFrom()
       }
 
-      const mailOptions = {
+      let mailOptions: any = {
         from: fromField,
         to: email.to,
         cc: email.cc || undefined,
@@ -281,6 +281,16 @@ export class MailingService implements IMailingService {
         text: email.text || undefined,
       }
 
+      // Call beforeSend hook if configured
+      if (this.config.beforeSend) {
+        try {
+          mailOptions = await this.config.beforeSend(mailOptions, email)
+        } catch (error) {
+          console.error('Error in beforeSend hook:', error)
+          throw new Error(`beforeSend hook failed: ${error instanceof Error ? error.message : 'Unknown error'}`)
+        }
+      }
+
       await this.transporter.sendMail(mailOptions)
 
       await this.payload.update({

src/types/index.ts

@@ -48,6 +48,21 @@ export type TemplateRendererHook = (template: string, variables: Record<string,
 
 export type TemplateEngine = 'liquidjs' | 'mustache' | 'simple'
 
+export interface BeforeSendMailOptions {
+  from: string
+  to: string[]
+  cc?: string[]
+  bcc?: string[]
+  replyTo?: string
+  subject: string
+  html: string
+  text?: string
+  attachments?: any[]
+  [key: string]: any
+}
+
+export type BeforeSendHook = (options: BeforeSendMailOptions, email: BaseEmailDocument) => BeforeSendMailOptions | Promise<BeforeSendMailOptions>
+
 export interface MailingPluginConfig {
   collections?: {
     templates?: string | Partial<CollectionConfig>
@@ -62,6 +77,7 @@ export interface MailingPluginConfig {
   templateRenderer?: TemplateRendererHook
   templateEngine?: TemplateEngine
   richTextEditor?: RichTextField['editor']
+  beforeSend?: BeforeSendHook
   onReady?: (payload: any) => Promise<void>
   initOrder?: 'before' | 'after'
 }