洪 民憙 (Hong Minhee)

There's already an answer to how you send email from Node.js. Node.js has Nodemailer, and it's been a solid choice for a long time. But the code people write today doesn't only run on Node.js anymore. It's common to see it running on Deno, Bun, or an edge runtime like Cloudflare Workers, and it's common to switch providers between development and production: send nothing locally, then use SES or Resend once deployed.

So I wanted to change the question a little. Not how do you send email from Node.js, but how does an application deliver email regardless of runtime or provider. That's the question Upyo started from.

Nodemailer is great; the landscape just got bigger

If you're sending email over SMTP from Node.js, Nodemailer is enough. Its SMTP implementation is mature, it supports OAuth 2.0, and it already handles DKIM signing and calendar invitations.

The catch is that Nodemailer runs on top of Node.js built-in modules like node:net, node:tls, and node:stream. That makes it hard to use on Cloudflare Workers, Vercel Edge Runtime, or Supabase Edge Functions. Its provider support centers on SMTP too, so using an HTTP API service like Resend or SendGrid means installing that service's own SDK or relying on a third-party transport. Switching providers usually means touching application code too.

The principle of universality

Upyo is built on web standard APIs like fetch(), Web Streams, and Web Crypto. Since it doesn't depend on Node.js specific modules, the same code runs unchanged on Node.js, Deno, Bun, and edge functions.

Every email service is handled through the same Transport interface: SMTP and JMAP, Resend, SendGrid, Mailgun, Amazon SES, Plunk, Lettermint. Swap out how the transport is constructed and the application code that sends mail stays the same, whether that's a local SMTP server or a mock transport in development, or SES in production.

Keeping dependencies minimal follows from the same goal. @upyo/ses implements AWS Signature v4 itself instead of pulling in the AWS SDK. The AWS SDK assumes Node.js, and using it as is would make the transport unusable on Deno, Bun, or an edge runtime.

Separating retry logic from application logic

The Transport interface itself is small. send() sends one message, sendMany() sends several, and cancellation goes through a standard AbortSignal.

How sendMany() is implemented differs by transport. The transport for a provider like Resend or SendGrid that exposes a batch endpoint calls that endpoint directly. SMTP, where reusing one connection for several messages is the natural approach, does that instead. A transport without either optimization might still run several send() calls concurrently instead of one after another, to cut down total time.

Because the interface is this small, the answer to where retry policy should live changes. Wrap a transport in RetryTransport and application code never needs its own retry logic.

That's possible because application code only knows the Transport interface type, not a concrete implementation. The function that sends mail takes a transport: Transport parameter, and the caller decides which transport gets injected.

Providers fail differently; what if that didn't matter?

import { MockTransport } from "@upyo/mock";
import { RetryTransport } from "@upyo/retry";

const provider = new MockTransport();

const transport = new RetryTransport(provider, {
  maxAttempts: 3,
  backoff: {
    baseDelayMilliseconds: 1000,
    maxDelayMilliseconds: 30000,
    factor: 2,
  },
});

RetryTransport implements the same Transport interface, so application code doesn't need to know whether it's talking to SMTP or SES, or whether retries are even happening. Wrap it in PoolTransport and a failing provider can fail over to the next one by priority, or traffic can be spread across several with round robin.

import { PoolTransport } from "@upyo/pool";

const pool = new PoolTransport({
  strategy: "priority",
  transports: [
    { transport: primaryProvider, priority: 100 },
    { transport: backupProvider, priority: 10 },
  ],
  maxRetries: 3,
});

The two can be stacked. Whether you retry per provider before failing over to the next, or retry the whole pool as a single operation, comes down to which one sits on the outside.

This composition works because every transport returns failures in the same shape. Upyo's Receipt is a discriminated union of success and failure, and a failure carries structured fields like retryable, category, and retryAfterMilliseconds. Once each transport translates a provider's error into these fields, RetryTransport can decide whether to retry a 429 from Resend or a transient SMTP error the same way.

Still waiting on magic links, even in development

The annoying part of building magic-link login was never the login itself. It was opening an inbox every time and waiting for the link to show up, when the link never needed to be delivered anywhere during development.

The function that sends mail was written to take a Transport from the start.

import { createMessage } from "@upyo/core";
import type { Transport } from "@upyo/core";

async function sendMagicLink(transport: Transport, email: string, link: string) {
  await transport.send(createMessage({
    from: "auth@example.com",
    to: email,
    subject: "Your login link",
    content: { text: `Click to log in: ${link}` },
  }));
}

@upyo/logtape wraps another transport and logs instead of sending. In development, that's what gets injected.

import { LogTapeTransport } from "@upyo/logtape";
import { SmtpTransport } from "@upyo/smtp";

const smtp = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  auth: { user: "smtp-user", pass: "smtp-password" },
});

const transport = process.env.NODE_ENV === "development"
  ? new LogTapeTransport({ category: ["app", "email"] })
  : new LogTapeTransport({ transport: smtp, category: ["app", "email"] });

Copy the link straight out of the server log and paste it into the browser. No refreshing an inbox.

Automated tests use the same injection point. This time, sendMagicLink() gets @upyo/mock's MockTransport instead.

import { MockTransport } from "@upyo/mock";
import assert from "node:assert/strict";

const transport = new MockTransport();

await sendMagicLink(transport, "user@example.com", "https://example.com/verify?token=...");

const sent = await transport.waitForMessage(
  (msg) => msg.subject.includes("login link"),
  1000,
);

assert.equal(sent.recipients[0].address, "user@example.com");

sendMagicLink() itself never changed. Only the Transport handed to it did.

A small API that still holds the complexity

A small Transport interface doesn't mean the messy parts of email got skipped. The SMTP transport handles internationalized addresses through SMTPUTF8 and requests delivery status notifications through DSN. Attachments stream, so even large files don't sit in memory. The Message.calendar field turns a message into a meeting invitation or cancellation, and messageId, inReplyTo, and references let outgoing mail be part of a conversation rather than a one-off notice.

Getting started

To send over SMTP, install these packages.

npm add @upyo/core @upyo/smtp

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";

const transport = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  auth: { user: "smtp-user", pass: "smtp-password" },
});

const message = createMessage({
  from: "sender@example.com",
  to: "recipient@example.com",
  subject: "Hello from Upyo",
  content: { text: "This is a test email." },
});

await transport.send(message);

Layer RetryTransport, PoolTransport, or LogTapeTransport on top as needed. Configuration for each transport is in the docs, the source is on GitHub, and packages are on npm and JSR.

That's the answer so far to the question I started with: how an application delivers email regardless of runtime or provider. There's still plenty to refine, so if something's broken or missing, an issue or a discussion is welcome.

There's already an answer to how you send email from Node.js. Node.js has Nodemailer, and it's been a solid choice for a long time. But the code people write today doesn't only run on Node.js anymore. It's common to see it running on Deno, Bun, or an edge runtime like Cloudflare Workers, and it's common to switch providers between development and production: send nothing locally, then use SES or Resend once deployed.

So I wanted to change the question a little. Not how do you send email from Node.js, but how does an application deliver email regardless of runtime or provider. That's the question Upyo started from.

Nodemailer is great; the landscape just got bigger

If you're sending email over SMTP from Node.js, Nodemailer is enough. Its SMTP implementation is mature, it supports OAuth 2.0, and it already handles DKIM signing and calendar invitations.

The catch is that Nodemailer runs on top of Node.js built-in modules like node:net, node:tls, and node:stream. That makes it hard to use on Cloudflare Workers, Vercel Edge Runtime, or Supabase Edge Functions. Its provider support centers on SMTP too, so using an HTTP API service like Resend or SendGrid means installing that service's own SDK or relying on a third-party transport. Switching providers usually means touching application code too.

The principle of universality

Upyo is built on web standard APIs like fetch(), Web Streams, and Web Crypto. Since it doesn't depend on Node.js specific modules, the same code runs unchanged on Node.js, Deno, Bun, and edge functions.

Every email service is handled through the same Transport interface: SMTP and JMAP, Resend, SendGrid, Mailgun, Amazon SES, Plunk, Lettermint. Swap out how the transport is constructed and the application code that sends mail stays the same, whether that's a local SMTP server or a mock transport in development, or SES in production.

Keeping dependencies minimal follows from the same goal. @upyo/ses implements AWS Signature v4 itself instead of pulling in the AWS SDK. The AWS SDK assumes Node.js, and using it as is would make the transport unusable on Deno, Bun, or an edge runtime.

Separating retry logic from application logic

The Transport interface itself is small. send() sends one message, sendMany() sends several, and cancellation goes through a standard AbortSignal.

How sendMany() is implemented differs by transport. The transport for a provider like Resend or SendGrid that exposes a batch endpoint calls that endpoint directly. SMTP, where reusing one connection for several messages is the natural approach, does that instead. A transport without either optimization might still run several send() calls concurrently instead of one after another, to cut down total time.

Because the interface is this small, the answer to where retry policy should live changes. Wrap a transport in RetryTransport and application code never needs its own retry logic.

That's possible because application code only knows the Transport interface type, not a concrete implementation. The function that sends mail takes a transport: Transport parameter, and the caller decides which transport gets injected.

Providers fail differently; what if that didn't matter?

import { MockTransport } from "@upyo/mock";
import { RetryTransport } from "@upyo/retry";

const provider = new MockTransport();

const transport = new RetryTransport(provider, {
  maxAttempts: 3,
  backoff: {
    baseDelayMilliseconds: 1000,
    maxDelayMilliseconds: 30000,
    factor: 2,
  },
});

RetryTransport implements the same Transport interface, so application code doesn't need to know whether it's talking to SMTP or SES, or whether retries are even happening. Wrap it in PoolTransport and a failing provider can fail over to the next one by priority, or traffic can be spread across several with round robin.

import { PoolTransport } from "@upyo/pool";

const pool = new PoolTransport({
  strategy: "priority",
  transports: [
    { transport: primaryProvider, priority: 100 },
    { transport: backupProvider, priority: 10 },
  ],
  maxRetries: 3,
});

The two can be stacked. Whether you retry per provider before failing over to the next, or retry the whole pool as a single operation, comes down to which one sits on the outside.

This composition works because every transport returns failures in the same shape. Upyo's Receipt is a discriminated union of success and failure, and a failure carries structured fields like retryable, category, and retryAfterMilliseconds. Once each transport translates a provider's error into these fields, RetryTransport can decide whether to retry a 429 from Resend or a transient SMTP error the same way.

Still waiting on magic links, even in development

The annoying part of building magic-link login was never the login itself. It was opening an inbox every time and waiting for the link to show up, when the link never needed to be delivered anywhere during development.

The function that sends mail was written to take a Transport from the start.

import { createMessage } from "@upyo/core";
import type { Transport } from "@upyo/core";

async function sendMagicLink(transport: Transport, email: string, link: string) {
  await transport.send(createMessage({
    from: "auth@example.com",
    to: email,
    subject: "Your login link",
    content: { text: `Click to log in: ${link}` },
  }));
}

@upyo/logtape wraps another transport and logs instead of sending. In development, that's what gets injected.

import { LogTapeTransport } from "@upyo/logtape";
import { SmtpTransport } from "@upyo/smtp";

const smtp = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  auth: { user: "smtp-user", pass: "smtp-password" },
});

const transport = process.env.NODE_ENV === "development"
  ? new LogTapeTransport({ category: ["app", "email"] })
  : new LogTapeTransport({ transport: smtp, category: ["app", "email"] });

Copy the link straight out of the server log and paste it into the browser. No refreshing an inbox.

Automated tests use the same injection point. This time, sendMagicLink() gets @upyo/mock's MockTransport instead.

import { MockTransport } from "@upyo/mock";
import assert from "node:assert/strict";

const transport = new MockTransport();

await sendMagicLink(transport, "user@example.com", "https://example.com/verify?token=...");

const sent = await transport.waitForMessage(
  (msg) => msg.subject.includes("login link"),
  1000,
);

assert.equal(sent.recipients[0].address, "user@example.com");

sendMagicLink() itself never changed. Only the Transport handed to it did.

A small API that still holds the complexity

A small Transport interface doesn't mean the messy parts of email got skipped. The SMTP transport handles internationalized addresses through SMTPUTF8 and requests delivery status notifications through DSN. Attachments stream, so even large files don't sit in memory. The Message.calendar field turns a message into a meeting invitation or cancellation, and messageId, inReplyTo, and references let outgoing mail be part of a conversation rather than a one-off notice.

Getting started

To send over SMTP, install these packages.

npm add @upyo/core @upyo/smtp

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";

const transport = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  auth: { user: "smtp-user", pass: "smtp-password" },
});

const message = createMessage({
  from: "sender@example.com",
  to: "recipient@example.com",
  subject: "Hello from Upyo",
  content: { text: "This is a test email." },
});

await transport.send(message);

Layer RetryTransport, PoolTransport, or LogTapeTransport on top as needed. Configuration for each transport is in the docs, the source is on GitHub, and packages are on npm and JSR.

That's the answer so far to the question I started with: how an application delivers email regardless of runtime or provider. There's still plenty to refine, so if something's broken or missing, an issue or a discussion is welcome.

#1Password