EmailEventHandler

Package: @vendure/email-plugin File: event-handler.ts

The EmailEventHandler defines how the EmailPlugin will respond to a given event.

A handler is created by creating a new EmailEventListener and calling the .on() method to specify which event to respond to.

Example

const confirmationHandler = new EmailEventListener('order-confirmation')
  .on(OrderStateTransitionEvent)
  .filter(event => event.toState === 'PaymentSettled')
  .setRecipient(event => event.order.customer.emailAddress)
  .setSubject(`Order confirmation for #{{ order.code }}`)
  .setTemplateVars(event => ({ order: event.order }));

This example creates a handler which listens for the OrderStateTransitionEvent and if the Order has transitioned to the 'PaymentSettled' state, it will generate and send an email.

Handling other languages

By default, the handler will respond to all events on all channels and use the same subject (“Order confirmation for #12345” above) and body template. Where the server is intended to support multiple languages, the .addTemplate() method may be used to defined the subject and body template for specific language and channel combinations.

Example

const extendedConfirmationHandler = confirmationHandler
  .addTemplate({
    channelCode: 'default',
    languageCode: LanguageCode.de,
    templateFile: 'body.de.hbs',
    subject: 'Bestellbestätigung für #{{ order.code }}',
  })

Signature

class EmailEventHandler<T extends string = string, Event extends EventWithContext = EventWithContext> {
  constructor(listener: EmailEventListener<T>, event: Type<Event>)
  filter(filterFn: (event: Event) => boolean) => EmailEventHandler<T, Event>;
  setRecipient(setRecipientFn: (event: Event) => string) => EmailEventHandler<T, Event>;
  setTemplateVars(templateVarsFn: SetTemplateVarsFn<Event>) => EmailEventHandler<T, Event>;
  setSubject(defaultSubject: string) => EmailEventHandler<T, Event>;
  setFrom(from: string) => EmailEventHandler<T, Event>;
  setAttachments(setAttachmentsFn: SetAttachmentsFn<Event>) => ;
  addTemplate(config: EmailTemplateConfig) => EmailEventHandler<T, Event>;
  loadData(loadDataFn: LoadDataFn<Event, R>) => EmailEventHandlerWithAsyncData<R, T, Event, EventWithAsyncData<Event, R>>;
  setMockEvent(event: Omit<Event, 'ctx' | 'data'>) => EmailEventHandler<T, Event>;
}

Members

constructor

method

type:

(listener: EmailEventListener<T>, event: Type<Event>) => EmailEventHandler

filter

method

type:

(filterFn: (event: Event) => boolean) => EmailEventHandler<T, Event>

Defines a predicate function which is used to determine whether the event will trigger an email. Multiple filter functions may be defined.

setRecipient

method

type:

(setRecipientFn: (event: Event) => string) => EmailEventHandler<T, Event>

A function which defines how the recipient email address should be extracted from the incoming event.

setTemplateVars

method

type:

(templateVarsFn: SetTemplateVarsFn<Event>) => EmailEventHandler<T, Event>

A function which returns an object hash of variables which will be made available to the Handlebars template and subject line for interpolation.

setSubject

method

type:

(defaultSubject: string) => EmailEventHandler<T, Event>

Sets the default subject of the email. The subject string may use Handlebars variables defined by the setTemplateVars() method.

setFrom

method

type:

(from: string) => EmailEventHandler<T, Event>

Sets the default from field of the email. The from string may use Handlebars variables defined by the setTemplateVars() method.

setAttachments

method

type:

(setAttachmentsFn: SetAttachmentsFn<Event>) =>

Defines one or more files to be attached to the email. An attachment must specify a path property which can be either a file system path or a URL to the file.

Example

const testAttachmentHandler = new EmailEventListener('activate-voucher')
  .on(ActivateVoucherEvent)
  // ... omitted some steps for brevity
  .setAttachments(async (event) => {
    const { imageUrl, voucherCode } = await getVoucherDataForUser(event.user.id);
    return [
      {
        filename: `voucher-${voucherCode}.jpg`,
        path: imageUrl,
      },
    ];
  });

addTemplate

method

type:

(config: EmailTemplateConfig) => EmailEventHandler<T, Event>

Add configuration for another template other than the default "body.hbs". Use this method to define specific templates for channels or languageCodes other than the default.

loadData

method

type:

(loadDataFn: LoadDataFn<Event, R>) => EmailEventHandlerWithAsyncData<R, T, Event, EventWithAsyncData<Event, R>>

Allows data to be loaded asynchronously which can then be used as template variables. The loadDataFn has access to the event, the TypeORM Connection object, and an inject() function which can be used to inject any of the providers exported by the PluginCommonModule. The return value of the loadDataFn will be added to the event as the data property.

Example

new EmailEventListener('order-confirmation')
  .on(OrderStateTransitionEvent)
  .filter(event => event.toState === 'PaymentSettled' && !!event.order.customer)
  .loadData(({ event, inject}) => {
    const orderService = inject(OrderService);
    return orderService.getOrderPayments(event.order.id);
  })
  .setTemplateVars(event => ({
    order: event.order,
    payments: event.data,
  }));

setMockEvent

method

type:

(event: Omit<Event, 'ctx' | 'data'>) => EmailEventHandler<T, Event>

Optionally define a mock Event which is used by the dev mode mailbox app for generating mock emails from this handler, which is useful when developing the email templates.