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
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.
The string argument passed into the EmailEventListener constructor is used to identify the handler, and
also to locate the directory of the email template files. So in the example above, there should be a directory
<app root>/static/email/templates/order-confirmation which contains a Handlebars template named body.hbs.
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.
Since v2.0 the .addTemplate() method has been deprecated. To serve different templates — for example, based on the current
languageCode — implement a custom TemplateLoader and pass it to EmailPlugin.init({ templateLoader: new MyTemplateLoader() }).
The language is typically determined by the languageCode property of the event's ctx (RequestContext) object, so the
loadTemplate() method can use that to locate the correct template file.
Example
Let's say you have a plugin which defines a new event type, QuoteRequestedEvent. In your plugin you have defined a mutation
which is executed when the customer requests a quote in your storefront, and in your resolver, you use the EventBus to publish a
new QuoteRequestedEvent.
You now want to email the customer with their quote. Here are the steps you would take to set this up:
Next you need to make sure there is a template defined at <app root>/static/email/templates/quote-requested/body.hbs. The path
segment quote-requested must match the string passed to the EmailEventListener constructor.
The template would look something like this:
You can find pre-made templates on the MJML website.
Finally, you need to register the handler with the EmailPlugin:
(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.
(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>'
A function which defines the plain-text body of the email, used by clients which do not render HTML. If not defined, the email is sent without a plain-text part.
(setLanguageCodeFn: (event: Event) => LanguageCode | undefined) => EmailEventHandler<T, Event>v1.8.0A function which allows to override the language of the email. If not defined, the language from the context will be used.
(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.
(defaultSubject: string | SetSubjectFn<Event>) => EmailEventHandler<T, Event>Sets the default subject of the email. The subject string may use Handlebars variables defined by the setTemplateVars() method.
(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.
A function which allows OptionalAddressFields to be specified such as "cc" and "bcc".
A function which allows 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 EmailSendEvent as event.metadata. Here's an example of usage:
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.(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
(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.
(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
(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.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team