Add SMTP email option to Medplum server (medplum#2530)

* Update packages/server/src/config.ts

* Update packages/server/src/email/email.ts

* Update packages/server/src/config.ts

* Cleanup

* Docs

---------

Co-authored-by: sweep-ai[bot] <128439645+sweep-ai[bot]@users.noreply.github.com>
Co-authored-by: Cody Ebberson <[email protected]>

Author: sweep-ai-deprecated[bot]

packages/docs/docs/self-hosting/config-settings.md

@@ -138,3 +138,4 @@ You will also be prompted for a parameter "Type". The default option is "String"
 | `auditEventLogStream`  | Optional AWS CloudWatch Log Stream name for `AuditEvent` logs. Only applies if `auditEventLogGroup` is set. Uses `os.hostname()` as the default.                                                      |          |            | `os.hostname()`                     |
 | `registerEnabled`      | Optional flag whether new user registration is enabled.                                                                                                                                               |          |            | `true`                              |
 | `maxJsonSize`          | Maximum JSON size for API calls. String is parsed with the [bytes](https://www.npmjs.com/package/bytes) library. Default is `1mb`.                                                                    |          |            | `1mb`                               |
+| `smtp`                 | Optional SMTP email settings to use SMTP for email. See [Sending SMTP Emails](/docs/self-hosting/sendgrid) for more details.                                                                          |          |            |

packages/docs/docs/self-hosting/sendgrid.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1100
+---
+
+# Send SMTP Emails with SendGrid
+
+This page describes how to use [SendGrid](https://app.sendgrid.com/) as an [SMTP Relay](https://sendgrid.com/blog/smtp-relay-service-basics/) to send emails from Medplum.
+
+:::note
+
+SMTP email is only available when self-hosting Medplum.
+
+Medplum's hosted environment uses [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/). Amazon SES is the default Medplum email provider.
+
+:::
+
+## Prerequisites
+
+Be sure to perform the following prerequisites to complete this tutorial.
+
+1. Sign up for a [SendGrid account](https://signup.sendgrid.com/)
+2. Create and store a [SendGrid API key](https://app.sendgrid.com/settings/api_keys) with full access "Mail Send" permissions.
+3. Verify your [SendGrid Sender Identity](https://docs.sendgrid.com/for-developers/sending-email/sender-identity/)
+
+See the SendGrid [How to Send an SMTP Email](https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp) guide for step by step instructions.
+
+## Configuring Medplum Server for SMTP
+
+Open your Medplum server config file. When developing on localhost, the default config file location is `packages/server/medplum.config.json`.
+
+Change the `supportEmail` to your Sender Identity email address:
+
+```json
+"supportEmail": "[email protected]",
+```
+
+Add a new `smtp` section for the SendGrid SMTP settings. Use your API key as the SMTP password:
+
+```json
+"smtp": {
+  "host": "smtp.sendgrid.net",
+  "port": 587,
+  "username": "apikey",
+  "password": "YOUR_API_KEY"
+}
+```
+
+## Testing
+
+Once your configuration settings are saved, restart the Medplum server. All subsequent emails will be sent via SendGrid SMTP Relay. For example, you can [invite a new user](/docs/app/invite) or reset your password to send a new email.
+
+:::tip
+
+If your SendGrid account is new, email delivery may be slow for the first 24 hours.
+
+:::

packages/server/src/config.ts

@@ -23,6 +23,7 @@ export interface MedplumServerConfig {
   supportEmail: string;
   database: MedplumDatabaseConfig;
   redis: MedplumRedisConfig;
+  smtp?: MedplumSmtpConfig;
   googleClientId?: string;
   googleClientSecret?: string;
   recaptchaSiteKey?: string;
@@ -61,6 +62,13 @@ export interface MedplumRedisConfig {
   password?: string;
 }
 
+export interface MedplumSmtpConfig {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+}
+
 let cachedConfig: MedplumServerConfig | undefined = undefined;
 
 /**

packages/server/src/email/email.test.ts

@@ -6,11 +6,12 @@ import { randomUUID } from 'crypto';
 import { Request } from 'express';
 import { mkdtempSync, rmSync } from 'fs';
 import { simpleParser } from 'mailparser';
+import nodemailer, { Transporter } from 'nodemailer';
 import Mail from 'nodemailer/lib/mailer';
 import { sep } from 'path';
 import { Readable } from 'stream';
 import { initAppServices, shutdownApp } from '../app';
-import { loadTestConfig } from '../config';
+import { getConfig, loadTestConfig } from '../config';
 import { systemRepo } from '../fhir/repo';
 import { getBinaryStorage } from '../fhir/storage';
 import { sendEmail } from './email';
@@ -244,4 +245,32 @@ describe('Email', () => {
     expect(mockSESv2Client.send.callCount).toBe(0);
     expect(mockSESv2Client).toHaveReceivedCommandTimes(SendEmailCommand, 0);
   });
+
+  test('Send via SMTP', async () => {
+    const config = getConfig();
+    config.smtp = {
+      host: 'smtp.example.com',
+      port: 587,
+      username: 'user',
+      password: 'pass',
+    };
+
+    const sendMail = jest.fn().mockResolvedValue({ messageId: '123' });
+    const createTransportSpy = jest.spyOn(nodemailer, 'createTransport');
+    createTransportSpy.mockReturnValue({ sendMail } as unknown as Transporter);
+
+    const toAddresses = '[email protected]';
+    await sendEmail(systemRepo, {
+      to: toAddresses,
+      cc: '[email protected]',
+      subject: 'Hello',
+      text: 'Hello Alice',
+    });
+
+    expect(createTransportSpy).toBeCalledTimes(1);
+    expect(sendMail).toBeCalledTimes(1);
+    expect(mockSESv2Client.send.callCount).toBe(0);
+
+    config.smtp = undefined;
+  });
 });

packages/server/src/email/email.ts

@@ -1,9 +1,10 @@
 import { SendEmailCommand, SESv2Client } from '@aws-sdk/client-sesv2';
 import { badRequest, normalizeErrorString, OperationOutcomeError } from '@medplum/core';
 import { Binary } from '@medplum/fhirtypes';
+import { createTransport } from 'nodemailer';
 import MailComposer from 'nodemailer/lib/mail-composer';
 import Mail, { Address } from 'nodemailer/lib/mailer';
-import { getConfig } from '../config';
+import { getConfig, MedplumSmtpConfig } from '../config';
 import { Repository } from '../fhir/repo';
 import { getBinaryStorage } from '../fhir/storage';
 import { logger } from '../logger';
@@ -16,11 +17,9 @@ import { logger } from '../logger';
  * @param options The MailComposer options.
  */
 export async function sendEmail(repo: Repository, options: Mail.Options): Promise<void> {
-  const sesClient = new SESv2Client({ region: getConfig().awsRegion });
-  const fromAddress = getConfig().supportEmail;
+  const config = getConfig();
+  const fromAddress = config.supportEmail;
   const toAddresses = buildAddresses(options.to);
-  const ccAddresses = buildAddresses(options.cc);
-  const bccAddresses = buildAddresses(options.bcc);
 
   // Always set the from and sender to the support email address
   options.from = fromAddress;
@@ -34,31 +33,20 @@ export async function sendEmail(repo: Repository, options: Mail.Options): Promis
   // "if set to true then fails with an error when a node tries to load content from a file"
   options.disableFileAccess = true;
 
-  let msg: Uint8Array;
-  try {
-    msg = await buildRawMessage(options);
-  } catch (err) {
-    throw new OperationOutcomeError(badRequest('Invalid email options: ' + normalizeErrorString(err)), err);
-  }
-
   logger.info('Sending email', { to: toAddresses?.join(', '), subject: options.subject });
-  await sesClient.send(
-    new SendEmailCommand({
-      FromEmailAddress: fromAddress,
-      Destination: {
-        ToAddresses: toAddresses,
-        CcAddresses: ccAddresses,
-        BccAddresses: bccAddresses,
-      },
-      Content: {
-        Raw: {
-          Data: msg,
-        },
-      },
-    })
-  );
+
+  if (config.smtp) {
+    await sendEmailViaSmpt(config.smtp, options);
+  } else {
+    await sendEmailViaSes(options);
+  }
 }
 
+/**
+ * Converts nodemailer addresses to an array of strings.
+ * @param input nodemailer address input.
+ * @returns Array of string addresses.
+ */
 function buildAddresses(input: string | Address | (string | Address)[] | undefined): string[] | undefined {
   if (!input) {
     return undefined;
@@ -69,6 +57,11 @@ function buildAddresses(input: string | Address | (string | Address)[] | undefin
   return [addressToString(input) as string];
 }
 
+/**
+ * Converts a nodemailer address to a string.
+ * @param address nodemailer address input.
+ * @returns String address.
+ */
 function addressToString(address: Address | string | undefined): string | undefined {
   if (address) {
     if (typeof address === 'string') {
@@ -81,6 +74,11 @@ function addressToString(address: Address | string | undefined): string | undefi
   return undefined;
 }
 
+/**
+ * Builds a raw email message using nodemailer MailComposer.
+ * @param options The nodemailer options.
+ * @returns The raw email message.
+ */
 function buildRawMessage(options: Mail.Options): Promise<Uint8Array> {
   const msg = new MailComposer(options);
   return new Promise((resolve, reject) => {
@@ -136,3 +134,56 @@ async function processAttachment(repo: Repository, attachment: Mail.Attachment):
     delete attachment.path;
   }
 }
+
+/**
+ * Sends an email via SMTP.
+ * @param smtpConfig The SMTP configuration.
+ * @param options The nodemailer options.
+ */
+async function sendEmailViaSmpt(smtpConfig: MedplumSmtpConfig, options: Mail.Options): Promise<void> {
+  const transport = createTransport({
+    host: smtpConfig.host,
+    port: smtpConfig.port,
+    auth: {
+      user: smtpConfig.username,
+      pass: smtpConfig.password,
+    },
+  });
+  await transport.sendMail(options);
+}
+
+/**
+ * Sends an email via AWS SES.
+ * @param options The nodemailer options.
+ */
+async function sendEmailViaSes(options: Mail.Options): Promise<void> {
+  const config = getConfig();
+  const fromAddress = config.supportEmail;
+  const toAddresses = buildAddresses(options.to);
+  const ccAddresses = buildAddresses(options.cc);
+  const bccAddresses = buildAddresses(options.bcc);
+
+  let msg: Uint8Array;
+  try {
+    msg = await buildRawMessage(options);
+  } catch (err) {
+    throw new OperationOutcomeError(badRequest('Invalid email options: ' + normalizeErrorString(err)), err);
+  }
+
+  const sesClient = new SESv2Client({ region: config.awsRegion });
+  await sesClient.send(
+    new SendEmailCommand({
+      FromEmailAddress: fromAddress,
+      Destination: {
+        ToAddresses: toAddresses,
+        CcAddresses: ccAddresses,
+        BccAddresses: bccAddresses,
+      },
+      Content: {
+        Raw: {
+          Data: msg,
+        },
+      },
+    })
+  );
+}