import { MiddlewareConsumer, NestModule, OnApplicationBootstrap } from '@nestjs/common'; import { ModuleRef } from '@nestjs/core'; import { EventBus, Injector, JobQueue, JobQueueService, Logger, PluginCommonModule, ProcessContext, registerPluginStartupMessage, Type, VendurePlugin, } from '@vendure/core'; import { isDevModeOptions } from './common'; import { EMAIL_PLUGIN_OPTIONS, loggerCtx } from './constants'; import { DevMailbox } from './dev-mailbox'; import { EmailProcessor } from './email-processor'; import { EmailEventHandler, EmailEventHandlerWithAsyncData } from './event-handler'; import { EmailPluginDevModeOptions, EmailPluginOptions, EventWithContext, IntermediateEmailDetails, } from './types'; /** * @description * The EmailPlugin creates and sends transactional emails based on Vendure events. By default it uses an [MJML](https://mjml.io/)-based * email generator to generate the email body and [Nodemailer](https://nodemailer.com/about/) to send the emails. * * ## Installation * * `yarn add \@vendure/email-plugin` * * or * * `npm install \@vendure/email-plugin` * * @example * ```ts * import { defaultEmailHandlers, EmailPlugin } from '\@vendure/email-plugin'; * * const config: VendureConfig = { * // Add an instance of the plugin to the plugins array * plugins: [ * EmailPlugin.init({ * handlers: defaultEmailHandlers, * templatePath: path.join(__dirname, 'vendure/email/templates'), * transport: { * type: 'smtp', * host: 'smtp.example.com', * port: 587, * auth: { * user: 'username', * pass: 'password', * } * }, * }), * ], * }; * ``` * * ## Email templates * * In the example above, the plugin has been configured to look in `/vendure/email/templates` * for the email template files. If you used `\@vendure/create` to create your application, the templates will have * been copied to that location during setup. * * If you are installing the EmailPlugin separately, then you'll need to copy the templates manually from * `node_modules/\@vendure/email-plugin/templates` to a location of your choice, and then point the `templatePath` config * property at that directory. * * ## Customizing templates * * Emails are generated from templates which use [MJML](https://mjml.io/) syntax. MJML is an open-source HTML-like markup * language which makes the task of creating responsive email markup simple. By default, the templates are installed to * `/vendure/email/templates` and can be freely edited. * * Dynamic data such as the recipient's name or order items are specified using [Handlebars syntax](https://handlebarsjs.com/): * * ```HTML *

Dear {{ order.customer.firstName }} {{ order.customer.lastName }},

* *

Thank you for your order!

* * * {{#each order.lines }} * * {{ quantity }} x {{ productVariant.name }} * {{ productVariant.quantity }} * {{ formatMoney totalPrice }} * * {{/each}} * * ``` * * ### Handlebars helpers * * The following helper functions are available for use in email templates: * * * `formatMoney`: Formats an amount of money (which are always stored as integers in Vendure) as a decimal, e.g. `123` => `1.23` * * `formatDate`: Formats a Date value with the [dateformat](https://www.npmjs.com/package/dateformat) package. * * ## Extending the default email handlers * * The `defaultEmailHandlers` array defines the default handlers such as for handling new account registration, order confirmation, password reset * etc. These defaults can be extended by adding custom templates for languages other than the default, or even completely new types of emails * which respond to any of the available [VendureEvents](/docs/typescript-api/events/). See the {@link EmailEventHandler} documentation for * details on how to do so. * * ## Dev mode * * For development, the `transport` option can be replaced by `devMode: true`. Doing so configures Vendure to use the * file transport (See {@link FileTransportOptions}) and outputs emails as rendered HTML files in the directory specified by the * `outputPath` property. * * ```ts * EmailPlugin.init({ * devMode: true, * route: 'mailbox', * handlers: defaultEmailHandlers, * templatePath: path.join(__dirname, 'vendure/email/templates'), * outputPath: path.join(__dirname, 'test-emails'), * }) * ``` * * ### Dev mailbox * * In dev mode, a webmail-like interface available at the `/mailbox` path, e.g. * http://localhost:3000/mailbox. This is a simple way to view the output of all emails generated by the EmailPlugin while in dev mode. * * ## Troubleshooting SMTP Connections * * If you are having trouble sending email over and SMTP connection, set the `logging` and `debug` options to `true`. This will * send detailed information from the SMTP transporter to the configured logger (defaults to console). For maximum detail combine * this with a detail log level in the configured VendureLogger: * * ```TypeScript * const config: VendureConfig = { * logger: new DefaultLogger({ level: LogLevel.Debug }) * // ... * plugins: [ * EmailPlugin.init({ * // ... * transport: { * type: 'smtp', * host: 'smtp.example.com', * port: 587, * auth: { * user: 'username', * pass: 'password', * }, * logging: true, * debug: true, * }, * }), * ], * }; * ``` * * @docsCategory EmailPlugin */ @VendurePlugin({ imports: [PluginCommonModule], providers: [{ provide: EMAIL_PLUGIN_OPTIONS, useFactory: () => EmailPlugin.options }, EmailProcessor], }) export class EmailPlugin implements OnApplicationBootstrap, NestModule { private static options: EmailPluginOptions | EmailPluginDevModeOptions; private devMailbox: DevMailbox | undefined; private jobQueue: JobQueue | undefined; private testingProcessor: EmailProcessor | undefined; /** @internal */ constructor( private eventBus: EventBus, private moduleRef: ModuleRef, private emailProcessor: EmailProcessor, private jobQueueService: JobQueueService, private processContext: ProcessContext, ) {} /** * Set the plugin options. */ static init(options: EmailPluginOptions | EmailPluginDevModeOptions): Type { this.options = options; return EmailPlugin; } /** @internal */ async onApplicationBootstrap(): Promise { const options = EmailPlugin.options; await this.setupEventSubscribers(); if (!isDevModeOptions(options) && options.transport.type === 'testing') { // When running tests, we don't want to go through the JobQueue system, // so we just call the email sending logic directly. this.testingProcessor = new EmailProcessor(options); await this.testingProcessor.init(); } else { await this.emailProcessor.init(); this.jobQueue = await this.jobQueueService.createQueue({ name: 'send-email', process: job => { return this.emailProcessor.process(job.data); }, }); } } configure(consumer: MiddlewareConsumer) { const options = EmailPlugin.options; if (isDevModeOptions(options) && this.processContext.isServer) { Logger.info('Creating dev mailbox middleware', loggerCtx); this.devMailbox = new DevMailbox(); consumer.apply(this.devMailbox.serve(options)).forRoutes(options.route); this.devMailbox.handleMockEvent((handler, event) => this.handleEvent(handler, event)); registerPluginStartupMessage('Dev mailbox', options.route); } } private async setupEventSubscribers() { for (const handler of EmailPlugin.options.handlers) { this.eventBus.ofType(handler.event).subscribe(event => { return this.handleEvent(handler, event); }); } } private async handleEvent( handler: EmailEventHandler | EmailEventHandlerWithAsyncData, event: EventWithContext, ) { Logger.debug(`Handling event "${handler.type}"`, loggerCtx); const { type } = handler; try { const injector = new Injector(this.moduleRef); const result = await handler.handle( event as any, EmailPlugin.options.globalTemplateVars, injector, ); if (!result) { return; } if (this.jobQueue) { await this.jobQueue.add(result, { retries: 5 }); } else if (this.testingProcessor) { await this.testingProcessor.process(result); } } catch (e) { Logger.error(e.message, loggerCtx, e.stack); } } }