EmailEventHandler
EmailEventHandler
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>;
setOptionalAddressFields(optionalAddressFieldsFn: SetOptionalAddressFieldsFn<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
(listener: EmailEventListener<T>, event: Type<Event>) => EmailEventHandler
filter
(filterFn: (event: Event) => boolean) => EmailEventHandler<T, Event>
setRecipient
(setRecipientFn: (event: Event) => string) => EmailEventHandler<T, Event>
A function which defines how the recipient email address should be extracted from the incoming event.
The recipient can be a plain email address: 'foobar@example.com'
Or with a formatted name (includes unicode support): 'Ноде Майлер <foobar@example.com>'
Or a comma-separated list of addresses: 'foobar@example.com, "Ноде Майлер" <bar@example.com>'
setTemplateVars
(templateVarsFn: SetTemplateVarsFn<Event>) => EmailEventHandler<T, Event>
setSubject
(defaultSubject: string) => EmailEventHandler<T, Event>
setFrom
(from: string) => EmailEventHandler<T, Event>
setOptionalAddressFields
setAttachments
(setAttachmentsFn: SetAttachmentsFn<Event>) =>
Defines one or more files to be attached to the email. An attachment can be specified
as either a path (to a file or URL) or as content which can be a string, Buffer or Stream.
Note: When using the content to pass a Buffer or Stream, the raw data will get serialized
into the job queue. For this reason the total size of all attachments passed as content should kept to
less than ~50k. If the attachments are greater than that limit, a warning will be logged and
errors may result if using the DefaultJobQueuePlugin with certain DBs such as MySQL/MariaDB.
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
(config: EmailTemplateConfig) => EmailEventHandler<T, Event>
"body.hbs". Use this method to define specific
templates for channels or languageCodes other than the default.
loadData
(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, injector }) => {
const orderService = injector.get(OrderService);
return orderService.getOrderPayments(event.order.id);
})
.setTemplateVars(event => ({
order: event.order,
payments: event.data,
}));
setMockEvent
(event: Omit<Event, 'ctx' | 'data'>) => EmailEventHandler<T, Event>