From a835b3f379b9a0549f8b383de15a06df9a0369d8 Mon Sep 17 00:00:00 2001
From: Michael Bromley <michael@michaelbromley.co.uk>
Date: Mon, 22 Jul 2024 10:53:37 +0200
Subject: [PATCH] docs(email-plugin): Add example for new `setMetadata` method

---
 .../email-plugin/src/handler/event-handler.ts | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/email-plugin/src/handler/event-handler.ts b/packages/email-plugin/src/handler/event-handler.ts
index 7a19276503..88ea8be077 100644
--- a/packages/email-plugin/src/handler/event-handler.ts
+++ b/packages/email-plugin/src/handler/event-handler.ts
@@ -250,7 +250,27 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
 
     /**
      * @description
-     * A function which allows {@link EmailMetadata} to be specified for the email.
+     * A function which allows {@link EmailMetadata} to be specified for the email. This can be used
+     * to store arbitrary data about the email which can be used for tracking or other purposes.
+     *
+     * It will be exposed in the {@link EmailSendEvent} as `event.metadata`. Here's an example of usage:
+     *
+     * - An {@link OrderStateTransitionEvent} occurs, and the EmailEventListener starts processing it.
+     * - The EmailEventHandler attaches metadata to the email:
+     *    ```ts
+     *    new EmailEventListener(EventType.ORDER_CONFIRMATION)
+     *      .on(OrderStateTransitionEvent)
+     *      .setMetadata(event => ({
+     *        type: EventType.ORDER_CONFIRMATION,
+     *        orderId: event.order.id,
+     *      }));
+     *   ```
+     * - Then, the EmailPlugin tries to send the email and publishes {@link EmailSendEvent},
+     *   passing ctx, emailDetails, error or success, and this metadata.
+     * - In another part of the server, we have an eventBus that subscribes to EmailSendEvent. We can use
+     *   `metadata.type` and `metadata.orderId` to identify the related order. For example, we can indicate on the
+     *    order that the email was successfully sent, or in case of an error, send a notification confirming
+     *    the order in another available way.
      *
      * @since 3.1.0
      */