docs(email-plugin): Improve email plugin docs

packages/email-plugin/index.ts

@@ -1,5 +1,5 @@
 export * from './src/default-email-handlers';
-export * from './src/email-sender';
+export * from './src/nodemailer-email-sender';
 export * from './src/event-handler';
 export * from './src/event-listener';
 export * from './src/handlebars-mjml-generator';

packages/email-plugin/src/email-processor.ts

@@ -4,8 +4,8 @@ import fs from 'fs-extra';
 import { deserializeAttachments } from './attachment-utils';
 import { isDevModeOptions } from './common';
 import { loggerCtx } from './constants';
-import { DefaultEmailSender } from './email-sender';
 import { HandlebarsMjmlGenerator } from './handlebars-mjml-generator';
+import { NodemailerEmailSender } from './nodemailer-email-sender';
 import { TemplateLoader } from './template-loader';
 import {
     EmailGenerator,
@@ -17,7 +17,7 @@ import {
 
 /**
  * This class combines the template loading, generation, and email sending - the actual "work" of
- * the EmailPlugin. It is arranged this way primarily to accomodate easier testing, so that the
+ * the EmailPlugin. It is arranged this way primarily to accommodate easier testing, so that the
  * tests can be run without needing all the JobQueue stuff which would require a full e2e test.
  */
 export class EmailProcessor {
@@ -30,7 +30,7 @@ export class EmailProcessor {
 
     async init() {
         this.templateLoader = new TemplateLoader(this.options.templatePath);
-        this.emailSender = this.options.emailSender ? this.options.emailSender : new DefaultEmailSender();
+        this.emailSender = this.options.emailSender ? this.options.emailSender : new NodemailerEmailSender();
         this.generator = this.options.emailGenerator
             ? this.options.emailGenerator
             : new HandlebarsMjmlGenerator();

packages/email-plugin/src/handlebars-mjml-generator.ts

@@ -7,8 +7,12 @@ import path from 'path';
 import { EmailGenerator, EmailPluginDevModeOptions, EmailPluginOptions } from './types';
 
 /**
+ * @description
  * Uses Handlebars (https://handlebarsjs.com/) to output MJML (https://mjml.io) which is then
  * compiled down to responsive email HTML.
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage EmailGenerator
  */
 export class HandlebarsMjmlGenerator implements EmailGenerator {
     onInit(options: EmailPluginOptions | EmailPluginDevModeOptions) {

packages/email-plugin/src/email-sender.ts → packages/email-plugin/src/nodemailer-email-sender.ts

@@ -4,9 +4,7 @@ import { Logger } from '@vendure/core';
 import fs from 'fs-extra';
 import { createTransport } from 'nodemailer';
 import { default as Mail } from 'nodemailer/lib/mailer';
-import SendmailTransport from 'nodemailer/lib/sendmail-transport';
 import { LoggerLevel } from 'nodemailer/lib/shared';
-import SMTPTransport from 'nodemailer/lib/smtp-transport';
 import path from 'path';
 import { Stream } from 'stream';
 import { format } from 'util';
@@ -30,9 +28,13 @@ export type StreamTransportInfo = {
 };
 
 /**
+ * @description
  * Uses the configured transport to send the generated email.
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage EmailSender
  */
-export class DefaultEmailSender implements EmailSender {
+export class NodemailerEmailSender implements EmailSender {
     private _smtpTransport: Mail | undefined;
     private _sendMailTransport: Mail | undefined;
 

packages/email-plugin/src/plugin.ts

@@ -32,8 +32,8 @@ import {
 
 /**
  * @description
- * The EmailPlugin creates and sends transactional emails based on Vendure events. It uses an [MJML](https://mjml.io/)-based
- * email generator to generate the email body and [Nodemailer](https://nodemailer.com/about/) to send the emais.
+ * 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
  *

packages/email-plugin/src/types.ts

@@ -63,12 +63,16 @@ export interface EmailPluginOptions {
      * @description
      * An optional allowed EmailSender, used to allow custom implementations of the send functionality
      * while still utilizing the existing emailPlugin functionality.
+     *
+     * @default NodemailerEmailSender
      */
     emailSender?: EmailSender;
     /**
      * @description
      * An optional allowed EmailGenerator, used to allow custom email generation functionality to
      * better match with custom email sending functionality.
+     *
+     * @default HandlebarsMjmlGenerator
      */
     emailGenerator?: EmailGenerator;
 }
@@ -234,7 +238,8 @@ export interface FileTransportOptions {
 
 /**
  * @description
- * Does nothing with the generated email. Mainly intended for use in testing where we don't care about the email transport.
+ * Does nothing with the generated email. Intended for use in testing where we don't care about the email transport,
+ * or when using a custom {@link EmailSender} which does not require transport options.
  *
  * @docsCategory EmailPlugin
  * @docsPage Transport Options
@@ -274,13 +279,57 @@ export interface TestingTransportOptions {
     onSend: (details: EmailDetails) => void;
 }
 
+/**
+ * @description
+ * An EmailSender is responsible for sending the email, e.g. via an SMTP connection
+ * or using some other mail-sending API. By default, the EmailPlugin uses the
+ * {@link NodemailerEmailSender}, but it is also possible to supply a custom implementation:
+ *
+ * @example
+ * ```TypeScript
+ * const sgMail = require('\@sendgrid/mail');
+ *
+ * sgMail.setApiKey(process.env.SENDGRID_API_KEY);
+ *
+ * class SendgridEmailSender implements EmailSender {
+ *   async send(email: EmailDetails) {
+ *     await sgMail.send({
+ *       to: email.recipient,
+ *       from: email.from,
+ *       subject: email.subject,
+ *       html: email.body,
+ *     });
+ *   }
+ * }
+ *
+ * const config: VendureConfig = {
+ *   logger: new DefaultLogger({ level: LogLevel.Debug })
+ *   // ...
+ *   plugins: [
+ *     EmailPlugin.init({
+ *        // ... template, handlers config omitted
+ *       transport: { type: 'none' },
+ *        emailSender: new SendgridEmailSender(),
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage EmailSender
+ * @docsWeight 0
+ */
 export interface EmailSender {
-    send: (email: EmailDetails, options: EmailTransportOptions) => void;
+    send: (email: EmailDetails, options: EmailTransportOptions) => void | Promise<void>;
 }
 
 /**
  * @description
  * An EmailGenerator generates the subject and body details of an email.
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage EmailGenerator
+ * @docsWeight 0
  */
 export interface EmailGenerator<T extends string = any, E extends VendureEvent = any> {
     /**
@@ -307,6 +356,7 @@ export interface EmailGenerator<T extends string = any, E extends VendureEvent =
  * A function used to load async data for use by an {@link EmailEventHandler}.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
  */
 export type LoadDataFn<Event extends EventWithContext, R> = (context: {
     event: Event;
@@ -351,6 +401,7 @@ export class EmailWorkerMessage extends WorkerMessage<IntermediateEmailDetails,
  * combination.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
  */
 export interface EmailTemplateConfig {
     /**