Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

8.0 KB
Raw Blame
import { createLogger } from "@rallly/logger";
import { render } from "@react-email/render";
import type Mail from "nodemailer/lib/mailer";

import { getTransport } from "./transport";
import type { EmailBranding } from "./types";

const logger = createLogger("emails");

export type EmailAttachments = Mail.Options["attachments"];
export type IcalEvent = Mail.Options["icalEvent"];
type From = { name: string; address: string };

/** Args every `sendXEmail(...)` accepts. `props` are the template's own fields. */
export type SendArgs<P> = {
  to: string;
  locale?: string;
  branding: EmailBranding;
  props: Omit<P, "locale" | "chrome">;
  from?: From;
  replyTo?: string;
  attachments?: EmailAttachments;
  icalEvent?: IcalEvent;
  /**
   * HTTPS URL that mutes this kind of mail for the recipient. Emitted as
   * `List-Unsubscribe` + `List-Unsubscribe-Post` (RFC 8058 one-click), which
   * Gmail and Yahoo expect on recurring notification mail. The URL must
   * accept an unauthenticated POST.
   */
  listUnsubscribeUrl?: string;
};

function resolveFrom(from?: From): From {
  return (
    from ?? {
      name: process.env.NOREPLY_EMAIL_NAME ?? "Rallly",
      address: process.env.NOREPLY_EMAIL || process.env.SUPPORT_EMAIL || "",
    }
  );
}

type DispatchOptions = {
  to: string;
  from?: From;
  replyTo?: string;
  subject?: string;
  html?: string;
  text?: string;
  attachments?: EmailAttachments;
  icalEvent?: IcalEvent;
  listUnsubscribeUrl?: string;
  errorLabel: string;
};

// Local part is either a quoted string with backslash escapes (RFC 5321
// §4.1.2) or a run of unquoted characters.
const ADDRESS_PATTERN = /(?:"(?:\\.|[^"\\])*"|[^\s<>,;:"]+)@[^\s<>,;:"]+/g;

/**
 * Domains of every address in a nodemailer `to` string (comma or semicolon
 * separated, display-name wrappers allowed), deduplicated and lowercased.
 * Enough to tell a misconfigured provider from a single bad mailbox without
 * putting an address in the log sink.
 */
export function recipientDomains(to: string) {
  const domains = new Set<string>();
  for (const address of to.match(ADDRESS_PATTERN) ?? []) {
    domains.add(address.slice(address.lastIndexOf("@") + 1).toLowerCase());
  }
  return [...domains];
}

/** Replaces anything address-shaped so SMTP replies can be logged verbatim. */
export function scrubAddresses(text: string) {
  return text.replace(ADDRESS_PATTERN, "[redacted]");
}

/**
 * Nodemailer rejections carry the recipient in `message`, `response`,
 * `rejected` and `rejectedErrors`, so the raw error must not be logged.
 * Keeps the fields an operator needs to diagnose a transport failure.
 */
/**
 * Nodemailer's send result. Only the SMTP transport fills `accepted`,
 * `rejected` and `response`; SES returns its own shape.
 */
function describeSendResult(info: unknown) {
  if (typeof info !== "object" || info === null) {
    return {};
  }
  const { messageId, accepted, rejected, response } = info as {
    messageId?: string;
    accepted?: unknown[];
    rejected?: unknown[];
    response?: string;
  };
  return {
    messageId,
    acceptedCount: Array.isArray(accepted) ? accepted.length : undefined,
    rejectedCount: Array.isArray(rejected) ? rejected.length : undefined,
    response: response ? scrubAddresses(response) : undefined,
  };
}

function describeTransportError(e: unknown) {
  if (!(e instanceof Error)) {
    return { errorMessage: scrubAddresses(String(e)) };
  }
  const { code, command, responseCode, response } = e as Error & {
    code?: string;
    command?: string;
    responseCode?: number;
    response?: string;
  };
  return {
    errorName: e.name,
    errorMessage: scrubAddresses(e.message),
    errorCode: code,
    errorCommand: command,
    errorResponseCode: responseCode,
    errorResponse: response ? scrubAddresses(response) : undefined,
  };
}

function buildHeaders(
  listUnsubscribeUrl?: string,
): Record<string, string> | undefined {
  if (!listUnsubscribeUrl) {
    return undefined;
  }
  // RFC 8058 one-click requires an https URI. A plain-http instance (local
  // dev, self-hosted on a LAN) still gets the mailto-style link header, just
  // not the one-click flag.
  if (!listUnsubscribeUrl.startsWith("https://")) {
    return { "List-Unsubscribe": `<${listUnsubscribeUrl}>` };
  }
  return {
    "List-Unsubscribe": `<${listUnsubscribeUrl}>`,
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  };
}

/**
 * SES forwards bounce and complaint reports to the From address unless told
 * otherwise. A From on the custom MAIL FROM subdomain cannot receive mail (its
 * MX belongs to SES), so the reports are redirected to a mailbox that can. The
 * address must belong to a verified SES identity. Ignored by the SMTP
 * transport.
 */
function buildSesOptions(): Record<string, unknown> | undefined {
  const feedbackAddress = process.env.SES_FEEDBACK_EMAIL;
  if (!feedbackAddress) {
    return undefined;
  }
  return { FeedbackForwardingEmailAddress: feedbackAddress };
}

/**
 * Resolves true once the transport accepted the message, or when the
 * instance has no email configured and there is nothing to send. False is a
 * transport failure, already logged; callers that keep delivery state retry
 * on it, everyone else can ignore it.
 */
async function dispatch(options: DispatchOptions) {
  if (!process.env.SUPPORT_EMAIL) {
    logger.info("SUPPORT_EMAIL not configured - skipping email send");
    return true;
  }

  try {
    const info = await getTransport().sendMail({
      from: resolveFrom(options.from),
      to: options.to,
      replyTo: options.replyTo,
      subject: options.subject,
      html: options.html,
      text: options.text,
      attachments: options.attachments,
      icalEvent: options.icalEvent,
      headers: buildHeaders(options.listUnsubscribeUrl),
      ses: buildSesOptions(),
    });
    // Proves the hand-off to the server, so "sent but never arrived" can be
    // separated from "never sent" without an SMTP transcript.
    logger.info(
      {
        ...describeSendResult(info),
        recipientDomains: recipientDomains(options.to),
        subject: options.subject,
      },
      `Sent email: ${options.errorLabel}`,
    );
    return true;
  } catch (e) {
    // Operational (SMTP/transport) failures are logged, not thrown — sending is
    // fire-and-forget. Render/template (code) errors are NOT caught here, so they
    // propagate to the caller's error reporting (Sentry via onRequestError).
    // Only the domain is logged: the log sink has its own retention and sits
    // outside the data map, so the address itself must never land there.
    logger.error(
      {
        ...describeTransportError(e),
        recipientDomains: recipientDomains(options.to),
        subject: options.subject,
      },
      `Failed to send email: ${options.errorLabel}`,
    );
    return false;
  }
}

/**
 * Renders a ready-built React element to html + plain text and dispatches.
 * Each template's `sendXEmail` builds its element (and subject) then calls this.
 */
export async function sendRenderedEmail(options: {
  to: string;
  element: React.ReactNode;
  subject: string;
  from?: From;
  replyTo?: string;
  attachments?: EmailAttachments;
  icalEvent?: IcalEvent;
  listUnsubscribeUrl?: string;
}) {
  const [html, text] = await Promise.all([
    render(options.element),
    render(options.element, { plainText: true }),
  ]);

  return dispatch({
    to: options.to,
    from: options.from,
    replyTo: options.replyTo,
    subject: options.subject,
    html,
    text,
    attachments: options.attachments,
    icalEvent: options.icalEvent,
    listUnsubscribeUrl: options.listUnsubscribeUrl,
    errorLabel: options.subject,
  });
}

export type SendRawEmailOptions = {
  to: string;
  subject: string;
  text?: string;
  html?: string;
  from?: From;
  replyTo?: string;
  attachments?: EmailAttachments;
  icalEvent?: IcalEvent;
  listUnsubscribeUrl?: string;
};

/**
 * Sends a plain (non-template) email — subject + text/html, no rendering.
 * For the rare app-specific cases that don't warrant a React template.
 */
export async function sendRawEmail(options: SendRawEmailOptions) {
  return dispatch({ ...options, errorLabel: options.subject });
}