Upyo is a cross-runtime email library for JavaScript that provides a unified API for sending emails across Node.js, Deno, Bun, and edge functions. It supports multiple transports including SMTP, Mailgun, SendGrid, Amazon SES, and more.

Upyo 0.4.0 introduces JMAP transport, DKIM signing for SMTP, and improvements to idempotency handling. This release focuses on expanding protocol support and improving email authentication.

JMAP transport

The new @upyo/jmap package adds support for JMAP (JSON Meta Application Protocol), a modern email protocol defined in RFC 8620 and RFC 8621. Unlike SMTP which requires persistent connections, JMAP uses standard HTTP requests with JSON payloads, making it well-suited for serverless and edge environments.

import { JmapTransport } from "@upyo/jmap";

const transport = new JmapTransport({
  sessionUrl: "https://mail.example.com/.well-known/jmap",
  bearerToken: "your-bearer-token",
});

const receipt = await transport.send(message);

The transport handles session discovery automatically, caching sessions to avoid unnecessary round-trips. It resolves sender identities from the from address and supports both bearer token and basic authentication.

A notable feature of JMAP is batch request support. The sendMany() method combines multiple emails into a single HTTP request, reducing network overhead when sending multiple messages. The transport supports all standard Upyo message features: text and HTML content, file attachments (both inline and regular), CC/BCC recipients, custom headers, and priority settings.

For detailed documentation, see the JMAP transport guide.

Installation

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

DKIM signing support

The SMTP transport now supports DKIM (DomainKeys Identified Mail) signing for outgoing emails. DKIM allows recipients to verify that emails actually came from the claimed domain, which can improve deliverability and reduce the chance of messages being marked as spam.

import { SmtpTransport } from "@upyo/smtp";
import { readFileSync } from "node:fs";

const transport = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  secure: false,
  auth: { user: "[email protected]", pass: "password" },
  dkim: {
    signatures: [{
      signingDomain: "example.com",
      selector: "mail",
      privateKey: readFileSync("./dkim-private.pem", "utf8"),
    }],
  },
});

The implementation uses the Web Crypto API for cross-runtime compatibility. It supports both rsa-sha256 (RFC 6376) and ed25519-sha256 (RFC 8463) algorithms, multiple signatures per message, and configurable failure handling—either throwing an error or sending unsigned when signing fails.

Private keys can be provided as PEM strings or as CryptoKey objects from the Web Crypto API. See the SMTP transport documentation for configuration details.

Message-level idempotency keys

The Message interface now includes an optional idempotencyKey property. This addresses an issue where retry logic couldn't properly deduplicate requests—previously, a new idempotency key was generated on each send attempt, defeating the purpose of idempotency protection.

By including the key in the message itself, applications can ensure the same key is used across retry attempts:

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Important notification",
  content: { text: "..." },
  idempotencyKey: "unique-key-for-this-message",
});

// Retrying with the same message object uses the same idempotency key
await transport.send(message);

The Resend transport now uses this key when provided, falling back to automatic key generation otherwise. This also fixes a bug where the idempotency key was incorrectly placed in the email's custom headers rather than as an HTTP request header.

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

For questions or issues, please visit our GitHub repository.