@novahelm/email

Email provider for NovaHelm -- supports Resend, SMTP (Nodemailer), and direct MX lookup. Includes React Email template rendering, file attachments, and built-in drip sequences.

Quick Start

pnpm add @novahelm/email

import { createEmailProvider } from "@novahelm/email";
import { initNova } from "@novahelm/core";

// 1. Create the email provider
const email = createEmailProvider({
  resendApiKey: env.RESEND_API_KEY,
  from: "[email protected]",
});

// 2. Register with the Nova registry
initNova({ db, redis, auth, email, logger, config });

// 3. Send an email
await email.send({
  to: "[email protected]",
  subject: "Welcome!",
  html: "<h1>Hello</h1><p>Welcome to our app.</p>",
});

Provider Selection

createEmailProvider() automatically selects the best available transport (in priority order):

| Priority | Provider | Condition | Best For | |----------|----------|-----------|----------| | 1 | Resend | resendApiKey is set | Production | | 2 | SMTP (Nodemailer) | smtpHost is set | Self-hosted / custom SMTP | | 3 | Direct Send (MX lookup) | Fallback | Local development |

Resend

const email = createEmailProvider({
  resendApiKey: "re_123456789",
  from: "[email protected]",
});

SMTP

const email = createEmailProvider({
  smtpHost: "smtp.mailgun.org",
  smtpPort: 587,              // default: 587 (TLS), use 465 for SSL
  smtpUser: "[email protected]",
  smtpPass: "secret",
  from: "[email protected]",
});

Direct Send (Development)

// No config needed -- uses MX lookup to send directly
const email = createEmailProvider({
  from: "dev@localhost",
});

Sending Emails

await email.send({
  to: "[email protected]",          // string or string[]
  subject: "Your order is confirmed",
  html: "<p>Order #1234 confirmed.</p>",
  from: "[email protected]",        // optional override
  replyTo: "[email protected]",    // optional
  tags: [                          // optional (Resend tags)
    { name: "type", value: "transactional" },
  ],
});

Attachments

Attach files to outgoing emails (25MB total limit):

import type { EmailAttachment } from "@novahelm/email";

await email.send({
  to: "[email protected]",
  subject: "Your invoice",
  html: "<p>Please find your invoice attached.</p>",
  attachments: [
    {
      filename: "invoice-2024-001.pdf",
      content: pdfBuffer,                    // Buffer or base64 string
      contentType: "application/pdf",        // optional MIME type
    },
    {
      filename: "logo.png",
      content: base64EncodedString,
    },
  ],
});

| Constraint | Limit | |------------|-------| | Total attachment size | 25MB | | Filename | No path separators (/, \, ..) |

React Email Templates

Import templates from the /templates subpath:

import { WelcomeEmail, PasswordResetEmail } from "@novahelm/email/templates";
import { render } from "@react-email/render";

const html = await render(WelcomeEmail({ name: "Alice", loginUrl: "..." }));
await email.send({ to: "[email protected]", subject: "Welcome!", html });

Drip Sequences

Schedule multi-step email sequences with delays:

import { startDripSequence, builtInSequences } from "@novahelm/email";
import { enqueue } from "@novahelm/jobs";

// Start a welcome drip sequence for a new user
await startDripSequence("welcome", userId, enqueue);

Built-in Sequences

| Sequence | Emails | Description | |----------|--------|-------------| | welcome | welcome, getting-started (+1d), tips-and-tricks (+3d) | New user onboarding | | win-back-sequence | sorry-to-see-you-go, what-you-re-missing (+3d), special-offer (+7d, conditional) | Re-engagement | | trial-expiring | trial-3-days-left, trial-1-day-left (+2d), trial-expired (+3d) | Trial conversion |

Custom Sequences

import type { DripSequence } from "@novahelm/email";

const mySequence: DripSequence = {
  id: "onboarding-pro",
  emails: [
    { template: "pro-welcome", delayMs: 0 },
    { template: "pro-feature-tour", delayMs: 2 * 24 * 60 * 60 * 1000 }, // +2 days
    {
      template: "pro-advanced-tips",
      delayMs: 5 * 24 * 60 * 60 * 1000, // +5 days
      condition: (ctx) => ctx.user.loginCount > 3, // only if engaged
    },
  ],
};

Subpath Exports

| Import Path | Description | |-------------|-------------| | @novahelm/email | Main: createEmailProvider, drip sequences, types | | @novahelm/email/templates | React Email template components |

API Reference

| Export | Description | |--------|-------------| | createEmailProvider(config) | Create an email provider instance | | EmailProvider | Provider interface (send() method) | | EmailProviderConfig | Config type (Resend key, SMTP, from address) | | SendOptions | Options for send() (to, subject, html, attachments) | | EmailAttachment | Attachment type (filename, content, contentType) | | startDripSequence(id, userId, enqueue) | Start a multi-step drip sequence | | builtInSequences | Array of built-in drip sequence definitions | | DripSequence | Sequence definition type | | DripStep | Single step in a sequence (template, delay, condition) |