Upyo 0.5.0: Structured errors, automatic retries, and OAuth 2.0

[dahlia]

Upyo is a cross-runtime email library for JavaScript that provides a unified API for sending email across Node.js, Deno, Bun, and edge functions. It supports SMTP, JMAP, and providers such as Mailgun, SendGrid, Amazon SES, Resend, and Plunk, all through the same Transport interface.

Upyo 0.5.0 makes delivery failures structured and machine-readable across every transport, adds a retry transport that absorbs transient failures automatically, welcomes a new Lettermint transport, and brings OAuth 2.0 authentication to the SMTP transport.

While we were at it, upyo.org also got a redesign: a longer, scrollable landing page that walks through cross-runtime support, provider independence, and packaging, wrapped in a warmer paper-and-postal-red theme built around the logo.

Structured receipt errors

Until now, a failed Receipt gave you a human-readable errorMessages array and not much else. If your application wanted to decide whether a failure was worth retrying, or needed the original HTTP status code, it had to parse provider-specific strings by hand.

Every transport now attaches structured metadata to failed receipts, so that information is just there:

import type { Receipt } from "@upyo/core";

function handleReceipt(receipt: Receipt) {
  if (receipt.successful) {
    console.log("Message sent with ID:", receipt.messageId);
  } else {
    console.error("Send failed:", receipt.errorMessages.join(", "));
    console.error("Retryable:", receipt.retryable ?? false);

    for (const error of receipt.errors ?? []) {
      console.error(error.category, error.code, error.provider);
    }
  }
}

A structured ReceiptError can carry a portable category (auth, rate-limit, network, timeout, validation, rejected, server-error, service-unavailable, configuration, or unknown), whether the failure is retryable, an HTTP status code, a retryAfterMilliseconds delay parsed from a provider's Retry-After header, the attempt count, a timestamp, and raw providerDetails when a transport exposes them. This ships across the board: SMTP, JMAP, Mailgun, SendGrid, Amazon SES, Resend, Plunk, and the new Lettermint transport all populate it, and the pool transport aggregates it from every child provider it tries.

To make that aggregation type-safe, Receipt, ReceiptError, and Transport are now generic over a provider id, and every transport exposes a stable id ("smtp", "mailgun", "pool", and so on). Wrapping or combining transports, like pool or retry, preserves the original provider id on each underlying error instead of collapsing everything into one generic failure.

If you write a custom transport, @upyo/core now exports the same building blocks the built-in transports use: createFailedReceipt(), createReceiptError(), classifyReceiptError(), classifyHttpStatus(), and parseRetryAfter(). Reach for them instead of hand-rolling error classification, and your transport's failures will look and behave like every other Upyo transport's. See the custom transport guide for the full pattern.

None of this touches existing code. errorMessages is still there and still works exactly as before; errors is additive.

Retry transport

The new @upyo/retry package adds RetryTransport, a decorator that wraps any Upyo transport and retries transient failures for you, using the structured error metadata above to decide what's worth retrying.

import { MailgunTransport } from "@upyo/mailgun";
import { RetryTransport } from "@upyo/retry";

const baseTransport = new MailgunTransport({
  apiKey: "your-mailgun-api-key",
  domain: "mail.example.com",
});

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

const receipt = await transport.send(message);

By default it retries rate limits, timeouts, and server errors with exponential backoff and full jitter, honors a provider's Retry-After delay when one is given, and gives up cleanly, returning a final failed receipt rather than throwing. AbortSignal cancellation is never retried and still rejects immediately, so it remains a hard stop for callers. sendMany() retries each message independently while throttling how many are in flight at once, and still yields receipts in the original input order.

Retry transport doesn't replace pool transport; it composes with it. Wrap a single provider for straightforward per-provider retries, wrap a pool for retries of the whole failover chain, or nest it inside a pool so each provider gets its own retry budget before the pool moves to the next one. The retry transport guide walks through backoff tuning, shouldRetry overrides, and composition with pool transport in more detail.

Lettermint transport

The new @upyo/lettermint package adds support for Lettermint, a transactional email provider with a straightforward HTTP API.

import { createMessage } from "@upyo/core";
import { LettermintTransport } from "@upyo/lettermint";

const transport = new LettermintTransport({
  apiToken: "lm_project_1234567890abcdef",
});

const message = createMessage({
  from: "support@example.com",
  to: "customer@example.com",
  subject: "Welcome to our service",
  content: { text: "Thank you for signing up!" },
});

const receipt = await transport.send(message);

The transport covers the full range of Upyo message features, including HTML and text content, CC/BCC, custom headers, attachments, and inline images, plus Lettermint-specific extras such as routes, tags, metadata, and tracking settings. sendMany() uses Lettermint's batch endpoint and automatically splits large inputs into chunks of 500 messages, and messages with their own idempotencyKey are sent individually so their keys are preserved. See the Lettermint transport guide for the complete feature set.

Installation

npm  add     @upyo/lettermint
pnpm add     @upyo/lettermint
yarn add     @upyo/lettermint
deno add jsr:@upyo/lettermint
bun  add     @upyo/lettermint

OAuth 2.0 authentication for SMTP

Gmail, Outlook, and a growing number of providers no longer accept plain passwords over SMTP. The SMTP transport now supports OAuth 2.0 through the SASL XOAUTH2 and OAUTHBEARER (RFC 7628) mechanisms, so it can authenticate the way those providers expect.

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

const transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: "your-email@gmail.com",
    accessToken: "ya29.a0Af…your-access-token",
  },
});

A static token is only the starting point. Pass a callback as accessToken to fetch a fresh token from a client such as google-auth-library or msal-node each time a new connection authenticates, or hand the transport your clientId, refreshToken, and tokenEndpoint and let it run the refresh_token grant itself, caching the access token across pooled connections until shortly before it expires. Existing { user, pass } configurations are untouched; OAuth 2.0 is simply a new member of the SmtpAuth union.

Alongside this, connection and authentication setup failures, such as an invalid host, a refused connection, or rejected credentials, are now reported as a failed Receipt instead of rejecting the returned promise, matching how message-level failures like a rejected recipient already worked. Only cancellation via AbortSignal still rejects. See the SMTP transport guide for full configuration details.

What's next

We continue expanding Upyo's transport coverage and resilience features while keeping the library simple, type-safe, and portable across runtimes. Your feedback and contributions help shape where it goes next.

---

For the complete changelog and technical details, see CHANGES.md.

For questions or issues, please visit our GitHub repository.