feat(email-plugin): Allow specifying metadata for EmailSendEvent (#2963)

packages/email-plugin/src/email-processor.ts

@@ -75,7 +75,9 @@ export class EmailProcessor {
             };
             const transportSettings = await this.getTransportSettings(ctx);
             await this.emailSender.send(emailDetails, transportSettings);
-            await this.eventBus.publish(new EmailSendEvent(ctx, emailDetails, true));
+            await this.eventBus.publish(
+                new EmailSendEvent(ctx, emailDetails, true, undefined, data.metadata),
+            );
             return true;
         } catch (err: unknown) {
             if (err instanceof Error) {
@@ -84,7 +86,9 @@ export class EmailProcessor {
                 Logger.error(String(err), loggerCtx);
             }
 
-            await this.eventBus.publish(new EmailSendEvent(ctx, emailDetails, false, err as Error));
+            await this.eventBus.publish(
+                new EmailSendEvent(ctx, emailDetails, false, err as Error, data.metadata),
+            );
             throw err;
         }
     }

packages/email-plugin/src/email-send-event.ts

@@ -1,6 +1,6 @@
 import { RequestContext, VendureEvent } from '@vendure/core';
 
-import { EmailDetails } from './types';
+import { EmailDetails, EmailMetadata } from './types';
 
 /**
  * @description
@@ -17,6 +17,7 @@ export class EmailSendEvent extends VendureEvent {
         public readonly details: EmailDetails,
         public readonly success: boolean,
         public readonly error?: Error,
+        public readonly metadata?: EmailMetadata,
     ) {
         super();
     }

packages/email-plugin/src/handler/event-handler.ts

@@ -13,6 +13,7 @@ import {
     IntermediateEmailDetails,
     LoadDataFn,
     SetAttachmentsFn,
+    SetMetadataFn,
     SetOptionalAddressFieldsFn,
     SetSubjectFn,
     SetTemplateVarsFn,
@@ -140,6 +141,7 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
     private setTemplateVarsFn: SetTemplateVarsFn<Event>;
     private setAttachmentsFn?: SetAttachmentsFn<Event>;
     private setOptionalAddressFieldsFn?: SetOptionalAddressFieldsFn<Event>;
+    private setMetadataFn?: SetMetadataFn<Event>;
     private filterFns: Array<(event: Event) => boolean> = [];
     private configurations: EmailTemplateConfig[] = [];
     private defaultSubject: string;
@@ -246,6 +248,17 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
         return this;
     }
 
+    /**
+     * @description
+     * A function which allows {@link EmailMetadata} to be specified for the email.
+     *
+     * @since 3.1.0
+     */
+    setMetadata(optionalSetMetadataFn: SetMetadataFn<Event>) {
+        this.setMetadataFn = optionalSetMetadataFn;
+        return this;
+    }
+
     /**
      * @description
      * Defines one or more files to be attached to the email. An attachment can be specified
@@ -322,6 +335,7 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
         asyncHandler.setTemplateVarsFn = this.setTemplateVarsFn;
         asyncHandler.setAttachmentsFn = this.setAttachmentsFn;
         asyncHandler.setOptionalAddressFieldsFn = this.setOptionalAddressFieldsFn;
+        asyncHandler.setMetadataFn = this.setMetadataFn;
         asyncHandler.filterFns = this.filterFns;
         asyncHandler.configurations = this.configurations;
         asyncHandler.defaultSubject = this.defaultSubject;
@@ -397,6 +411,8 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
         }
         const attachments = await serializeAttachments(attachmentsArray);
         const optionalAddressFields = (await this.setOptionalAddressFieldsFn?.(event)) ?? {};
+        const metadata = this.setMetadataFn ? await this.setMetadataFn(event) : {};
+
         return {
             ctx: event.ctx.serialize(),
             type: this.type,
@@ -406,6 +422,7 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
             subject,
             templateFile: configuration ? configuration.templateFile : 'body.hbs',
             attachments,
+            metadata,
             ...optionalAddressFields,
         };
     }

packages/email-plugin/src/types.ts

@@ -356,6 +356,7 @@ export type IntermediateEmailDetails = {
     cc?: string;
     bcc?: string;
     replyTo?: string;
+    metadata?: EmailMetadata;
 };
 
 /**
@@ -475,3 +476,16 @@ export interface OptionalAddressFields {
 export type SetOptionalAddressFieldsFn<Event> = (
     event: Event,
 ) => OptionalAddressFields | Promise<OptionalAddressFields>;
+
+/**
+ * @description
+ * A function used to set the {@link EmailMetadata}.
+ *
+ * @since 3.1.0
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage Email Plugin Types
+ *
+ */
+export type SetMetadataFn<Event> = (event: Event) => EmailMetadata | Promise<EmailMetadata>;
+
+export type EmailMetadata = Record<string, any>;