So you need to send emails from your JavaScript application. Email remains one of the most essential features in web appsâwelcome emails, password resets, notificationsâbut the ecosystem is fragmented. Nodemailer doesn't work on edge functions. Each provider has its own SDK. And if you're using Deno or Bun, good luck finding libraries that actually work.
This guide covers how to send emails across modern JavaScript runtimes using Upyo, a cross-runtime email library.
TL;DR for the impatient
If you just want working code, here's the quickest path to sending an email:
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
const transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: {
user: "your-email@gmail.com",
pass: "your-app-password", // Not your regular password!
},
});
const message = createMessage({
from: "your-email@gmail.com",
to: "recipient@example.com",
subject: "Hello from my app!",
content: { text: "This is my first email." },
});
const receipt = await transport.send(message);
if (receipt.successful) {
console.log("Sent:", receipt.messageId);
} else {
console.log("Failed:", receipt.errorMessages);
}
Install with:
npm add @upyo/core @upyo/smtp
That's it. This exact code works on Node.js, Deno, and Bun. But if you want to understand what's happening and explore more powerful options, read on.
Why Upyo?
Cross-runtime: Works on Node.js, Deno, Bun, and edge functions with the same API
Zero dependencies: Keeps your bundle small
Provider independence: Switch between SMTP, Mailgun, Resend, SendGrid, or Amazon SES without changing your application code
Type-safe: Full TypeScript support with discriminated unions for error handling
Built for testing: Includes a mock transport for unit tests
Part 1: Getting started with Gmail SMTP
Let's start with the most accessible option: Gmail's SMTP server. It's free, requires no additional accounts, and works great for development and low-volume production use.
Step 1: Generate a Gmail app password
Gmail doesn't allow you to use your regular password for SMTP. You need to create an app-specific password:
Go to your Google Account
Navigate to Security â 2-Step Verification (enable it if you haven't)
At the bottom, click App passwords
Select Mail and your device, then click Generate
Copy the 16-character password
Step 2: Install dependencies
Choose your runtime and package manager:
Node.js
npm add @upyo/core @upyo/smtp
# or: pnpm add @upyo/core @upyo/smtp
# or: yarn add @upyo/core @upyo/smtp
Deno
deno add jsr:@upyo/core jsr:@upyo/smtp
Bun
bun add @upyo/core @upyo/smtp
The same code works across all three runtimesâthat's the beauty of Upyo.
Step 3: Send your first email
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
// Create the transport (reuse this for multiple emails)
const transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: {
user: "your-email@gmail.com",
pass: "abcd efgh ijkl mnop", // Your app password
},
});
// Create and send a message
const message = createMessage({
from: "your-email@gmail.com",
to: "recipient@example.com",
subject: "Welcome to my app!",
content: {
text: "Thanks for signing up. We're excited to have you!",
html: "<h1>Welcome!</h1><p>Thanks for signing up. We're excited to have you!</p>",
},
});
const receipt = await transport.send(message);
if (receipt.successful) {
console.log("Email sent successfully! Message ID:", receipt.messageId);
} else {
console.error("Failed to send email:", receipt.errorMessages.join(", "));
}
// Don't forget to close connections when done
await transport.closeAllConnections();
Let me highlight a few important details:
secure: true with port 465: This establishes a TLS-encrypted connection from the start. Gmail requires encryption, so this combination is essential.
Separate text and html content: Always provide both. Some email clients don't render HTML, and spam filters look more favorably on emails with plain text alternatives.
The receipt pattern: Upyo uses discriminated unions for type-safe error handling. When receipt.successful is true, you get messageId. When it's false, you get errorMessages. This makes it impossible to forget error handling.
Closing connections: SMTP maintains persistent TCP connections. Always close them when you're done, or use await using (shown next) to handle this automatically.
Pro tip: automatic resource cleanup with await using
Managing resources manually is error-proneâwhat if an exception occurs before closeAllConnections() is called? Modern JavaScript (ES2024) solves this with explicit resource management.
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
// Transport is automatically disposed when it goes out of scope
await using transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: {
user: "your-email@gmail.com",
pass: "your-app-password",
},
});
const message = createMessage({
from: "your-email@gmail.com",
to: "recipient@example.com",
subject: "Hello!",
content: { text: "This email was sent with automatic cleanup!" },
});
await transport.send(message);
// No need to call `closeAllConnections()` - it happens automatically!
The await using keyword tells JavaScript to call the transport's cleanup method when execution leaves this scopeâeven if an error is thrown. This pattern is similar to Python's with statement or C#'s using block. It's supported in Node.js 22+, Deno, and Bun.
What if your environment doesn't support await using?
For older Node.js versions or environments without ES2024 support, use try/finally to ensure cleanup:
const transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});
try {
await transport.send(message);
} finally {
await transport.closeAllConnections();
}
This achieves the same resultâcleanup happens whether the send succeeds or throws an error.
Part 2: Adding attachments and rich content
Real-world emails often need more than plain text.
HTML emails with inline images
Inline images appear directly in the email body rather than as downloadable attachments. The trick is to reference them using a Content-ID (CID) URL scheme.
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFile } from "node:fs/promises";
await using transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});
// Read your logo file
const logoContent = await readFile("./assets/logo.png");
const message = createMessage({
from: "your-email@gmail.com",
to: "customer@example.com",
subject: "Your order confirmation",
content: {
html: `
<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
<img src="cid:company-logo" alt="Company Logo" style="width: 150px;">
<h1>Order Confirmed!</h1>
<p>Thank you for your purchase. Your order #12345 has been confirmed.</p>
</div>
`,
text: "Order Confirmed! Thank you for your purchase. Your order #12345 has been confirmed.",
},
attachments: [
{
filename: "logo.png",
content: logoContent,
contentType: "image/png",
contentId: "company-logo", // Referenced as cid:company-logo in HTML
inline: true,
},
],
});
await transport.send(message);
Key points about inline images:
contentId: This is the identifier you use in the HTML's src="cid:..." attribute. It can be any unique string.
inline: true: This tells the email client to display the image within the message body, not as a separate attachment.
Always include alt text: Some email clients block images by default, so the alt text ensures your message is still understandable.
File attachments
For regular attachments that recipients can download, use the standard File API. This approach works across all JavaScript runtimes.
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFile } from "node:fs/promises";
await using transport = new SmtpTransport({
host: "smtp.gmail.com",
port: 465,
secure: true,
auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});
// Read files to attach
const invoicePdf = await readFile("./invoices/invoice-2024-001.pdf");
const reportXlsx = await readFile("./reports/monthly-report.xlsx");
const message = createMessage({
from: "billing@yourcompany.com",
to: "client@example.com",
cc: "accounting@yourcompany.com",
subject: "Invoice #2024-001",
content: {
text: "Please find your invoice and monthly report attached.",
},
attachments: [
new File([invoicePdf], "invoice-2024-001.pdf", { type: "application/pdf" }),
new File([reportXlsx], "monthly-report.xlsx", {
type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
}),
],
priority: "high", // Sets email priority headers
});
await transport.send(message);
A few notes on attachments:
MIME types matter: Setting the correct type helps email clients display the right icon and open the file with the appropriate application.
priority: "high": This sets the X-Priority header, which some email clients use to highlight important messages. Use it sparinglyâoveruse can trigger spam filters.
Multiple recipients with different roles
Email supports several recipient types, each with different visibility rules:
import { createMessage } from "@upyo/core";
const message = createMessage({
from: { name: "Support Team", address: "support@yourcompany.com" },
to: [
"primary-recipient@example.com",
{ name: "John Smith", address: "john@example.com" },
],
cc: "manager@yourcompany.com",
bcc: ["archive@yourcompany.com", "compliance@yourcompany.com"],
replyTo: "no-reply@yourcompany.com",
subject: "Your support ticket has been updated",
content: { text: "We've responded to your ticket #5678." },
});
Understanding recipient types:
to: Primary recipients. Everyone can see who else is in this field.
cc (Carbon Copy): Secondary recipients. Visible to all recipientsâuse for people who should be informed but aren't the primary audience.
bcc (Blind Carbon Copy): Hidden recipients. No one can see BCC addressesâuseful for archiving or compliance without revealing internal processes.
replyTo: Where replies should go. Useful when sending from a no-reply address but wanting responses to reach a real inbox.
You can specify addresses as simple strings ("email@example.com") or as objects with name and address properties for display names.
Part 3: Moving to production with email service providers
Gmail SMTP is great for getting started, but for production applications, you'll want a dedicated email service provider. Here's why:
Higher sending limits: Gmail caps you at ~500 emails/day for personal accounts
Better deliverability: Dedicated services maintain sender reputation and handle bounces properly
Analytics and tracking: See who opened your emails, clicked links, etc.
Webhook notifications: Get real-time callbacks for delivery events
No dependency on personal accounts: Production systems shouldn't rely on someone's Gmail
The best part? With Upyo, switching providers requires minimal code changesâjust swap the transport.
Option A: Resend (modern and developer-friendly)
Resend is a newer email service with an excellent developer experience.
npm add @upyo/resend
import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";
const transport = new ResendTransport({
apiKey: process.env.RESEND_API_KEY!,
});
const message = createMessage({
from: "hello@yourdomain.com", // Must be verified in Resend
to: "user@example.com",
subject: "Welcome aboard!",
content: {
text: "Thanks for joining us!",
html: "<h1>Welcome!</h1><p>Thanks for joining us!</p>",
},
tags: ["onboarding", "welcome"], // For analytics
});
const receipt = await transport.send(message);
if (receipt.successful) {
console.log("Sent via Resend:", receipt.messageId);
}
Notice how similar this looks to the SMTP example? The only differences are the import and the transport configuration. Your message creation and sending logic stays exactly the sameâthat's Upyo's transport abstraction at work.
Option B: SendGrid (enterprise-grade)
SendGrid is a popular choice for high-volume senders, offering advanced analytics, template management, and a generous free tier.
SendGrid is a popular choice for high-volume senders.
npm add @upyo/sendgrid
import { createMessage } from "@upyo/core";
import { SendGridTransport } from "@upyo/sendgrid";
const transport = new SendGridTransport({
apiKey: process.env.SENDGRID_API_KEY!,
clickTracking: true,
openTracking: true,
});
const message = createMessage({
from: "notifications@yourdomain.com",
to: "user@example.com",
subject: "Your weekly digest",
content: {
html: "<h1>This Week's Highlights</h1><p>Here's what you missed...</p>",
text: "This Week's Highlights\n\nHere's what you missed...",
},
tags: ["digest", "weekly"],
});
await transport.send(message);
Option C: Mailgun (reliable workhorse)
Mailgun offers robust infrastructure with strong EU supportâimportant if you need GDPR-compliant data residency.
npm add @upyo/mailgun
import { createMessage } from "@upyo/core";
import { MailgunTransport } from "@upyo/mailgun";
const transport = new MailgunTransport({
apiKey: process.env.MAILGUN_API_KEY!,
domain: "mg.yourdomain.com",
region: "eu", // or "us"
});
const message = createMessage({
from: "team@yourdomain.com",
to: "user@example.com",
subject: "Important update",
content: { text: "We have some news to share..." },
});
await transport.send(message);
Option D: Amazon SES (cost-effective at scale)
Amazon SES is incredibly affordableâabout $0.10 per 1,000 emails. If you're already in the AWS ecosystem, it integrates seamlessly with IAM, CloudWatch, and other services.
npm add @upyo/ses
import { createMessage } from "@upyo/core";
import { SesTransport } from "@upyo/ses";
const transport = new SesTransport({
authentication: {
type: "credentials",
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
region: "us-east-1",
configurationSetName: "my-config-set", // Optional: for tracking
});
const message = createMessage({
from: "alerts@yourdomain.com",
to: "admin@example.com",
subject: "System alert",
content: { text: "CPU usage exceeded 90%" },
priority: "high",
});
await transport.send(message);
Part 4: Sending emails from edge functions
Here's where many email solutions fall short. Edge functions (Cloudflare Workers, Vercel Edge, Deno Deploy) run in a restricted environmentâthey can't open raw TCP connections, which means SMTP is not an option.
You must use an HTTP-based transport like Resend, SendGrid, Mailgun, or Amazon SES. The good news? Your code barely changes.
Cloudflare Workers example
// src/index.ts
import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const transport = new ResendTransport({
apiKey: env.RESEND_API_KEY,
});
const message = createMessage({
from: "noreply@yourdomain.com",
to: "user@example.com",
subject: "Request received",
content: { text: "We got your request and are processing it." },
});
const receipt = await transport.send(message);
if (receipt.successful) {
return new Response(`Email sent: ${receipt.messageId}`);
} else {
return new Response(`Failed: ${receipt.errorMessages.join(", ")}`, {
status: 500,
});
}
},
};
interface Env {
RESEND_API_KEY: string;
}
Vercel Edge Functions example
// app/api/send-email/route.ts
import { createMessage } from "@upyo/core";
import { SendGridTransport } from "@upyo/sendgrid";
export const runtime = "edge";
export async function POST(request: Request) {
const { to, subject, body } = await request.json();
const transport = new SendGridTransport({
apiKey: process.env.SENDGRID_API_KEY!,
});
const message = createMessage({
from: "app@yourdomain.com",
to,
subject,
content: { text: body },
});
const receipt = await transport.send(message);
if (receipt.successful) {
return Response.json({ success: true, messageId: receipt.messageId });
} else {
return Response.json(
{ success: false, errors: receipt.errorMessages },
{ status: 500 }
);
}
}
Deno Deploy example
// main.ts
import { createMessage } from "jsr:@upyo/core";
import { MailgunTransport } from "jsr:@upyo/mailgun";
Deno.serve(async (request: Request) => {
if (request.method !== "POST") {
return new Response("Method not allowed", { status: 405 });
}
const { to, subject, body } = await request.json();
const transport = new MailgunTransport({
apiKey: Deno.env.get("MAILGUN_API_KEY")!,
domain: Deno.env.get("MAILGUN_DOMAIN")!,
region: "us",
});
const message = createMessage({
from: "noreply@yourdomain.com",
to,
subject,
content: { text: body },
});
const receipt = await transport.send(message);
if (receipt.successful) {
return Response.json({ success: true, messageId: receipt.messageId });
} else {
return Response.json(
{ success: false, errors: receipt.errorMessages },
{ status: 500 }
);
}
});
Part 5: Improving deliverability with DKIM
Ever wonder why some emails land in spam while others don't? Email authentication plays a huge role. DKIM (DomainKeys Identified Mail) is one of the key mechanismsâit lets you digitally sign your emails so recipients can verify they actually came from your domain and weren't tampered with in transit.
Without DKIM:
Your emails are more likely to be flagged as spam
Recipients have no way to verify you're really who you claim to be
Sophisticated phishing attacks can impersonate your domain
Setting up DKIM with Upyo
First, generate a DKIM key pair. You can use OpenSSL:
# Generate a 2048-bit RSA private key
openssl genrsa -out dkim-private.pem 2048
# Extract the public key
openssl rsa -in dkim-private.pem -pubout -out dkim-public.pem
Then configure your SMTP transport:
import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFileSync } from "node:fs";
const transport = new SmtpTransport({
host: "smtp.example.com",
port: 587,
secure: false,
auth: {
user: "user@yourdomain.com",
pass: "password",
},
dkim: {
signatures: [
{
signingDomain: "yourdomain.com",
selector: "mail", // Creates DNS record at mail._domainkey.yourdomain.com
privateKey: readFileSync("./dkim-private.pem", "utf8"),
algorithm: "rsa-sha256", // or "ed25519-sha256" for shorter keys
},
],
},
});
The key configuration options:
signingDomain: Must match your email's "From" domain
selector: An arbitrary name that becomes part of your DNS record (e.g., mail creates a record at mail._domainkey.yourdomain.com)
algorithm: RSA-SHA256 is widely supported; Ed25519-SHA256 offers shorter keys (see below)
Adding the DNS record
Add a TXT record to your domain's DNS:
Name: mail._domainkey (or mail._domainkey.yourdomain.com depending on your DNS provider)
Value: v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE
Extract the public key value (remove headers, footers, and newlines from the .pem file):
cat dkim-public.pem | grep -v "^-" | tr -d '\n'
Using Ed25519 for shorter keys
RSA-2048 keys are longâabout 400 characters for the public key. This can be problematic because DNS TXT records have size limits, and some DNS providers struggle with long records.
Ed25519 provides equivalent security with much shorter keys (around 44 characters). If your email infrastructure supports it, Ed25519 is the modern choice.
# Generate Ed25519 key pair
openssl genpkey -algorithm ed25519 -out dkim-ed25519-private.pem
openssl pkey -in dkim-ed25519-private.pem -pubout -out dkim-ed25519-public.pem
const transport = new SmtpTransport({
// ... other config
dkim: {
signatures: [
{
signingDomain: "yourdomain.com",
selector: "mail2025",
privateKey: readFileSync("./dkim-ed25519-private.pem", "utf8"),
algorithm: "ed25519-sha256",
},
],
},
});
Part 6: Bulk email sending
When you need to send emails to many recipientsânewsletters, notifications, marketing campaignsâyou have two approaches:
The wrong way: looping with send()
// â Don't do this for bulk sending
for (const subscriber of subscribers) {
await transport.send(createMessage({
from: "newsletter@example.com",
to: subscriber.email,
subject: "Weekly update",
content: { text: "..." },
}));
}
This works, but it's inefficient:
Each send() call waits for the previous one to complete
No automatic batching or optimization
Harder to track overall progress
The right way: using sendMany()
The sendMany() method is designed for bulk operations:
import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";
const transport = new ResendTransport({
apiKey: process.env.RESEND_API_KEY!,
});
const subscribers = [
{ email: "alice@example.com", name: "Alice" },
{ email: "bob@example.com", name: "Bob" },
{ email: "charlie@example.com", name: "Charlie" },
// ... potentially thousands more
];
// Create personalized messages
const messages = subscribers.map((subscriber) =>
createMessage({
from: "newsletter@yourdomain.com",
to: subscriber.email,
subject: "Your weekly digest",
content: {
html: `<h1>Hi ${subscriber.name}!</h1><p>Here's what's new this week...</p>`,
text: `Hi ${subscriber.name}!\n\nHere's what's new this week...`,
},
tags: ["newsletter", "weekly"],
})
);
// Send all messages efficiently
let successCount = 0;
let failureCount = 0;
for await (const receipt of transport.sendMany(messages)) {
if (receipt.successful) {
successCount++;
} else {
failureCount++;
console.error("Failed:", receipt.errorMessages.join(", "));
}
}
console.log(`Sent: ${successCount}, Failed: ${failureCount}`);
Why sendMany() is better:
Automatic batching: Some transports (like Resend) combine multiple messages into a single API call
Connection reuse: SMTP transport reuses connections from the pool
Streaming results: You get receipts as they complete, not all at once
Resilient: One failure doesn't stop the rest
Progress tracking for large batches
const totalMessages = messages.length;
let processed = 0;
for await (const receipt of transport.sendMany(messages)) {
processed++;
if (processed % 100 === 0) {
console.log(`Progress: ${processed}/${totalMessages} (${Math.round((processed / totalMessages) * 100)}%)`);
}
if (!receipt.successful) {
console.error(`Message ${processed} failed:`, receipt.errorMessages);
}
}
console.log("Batch complete!");
When to use send() vs sendMany()
Scenario
Use
Single transactional email (welcome, password reset)
send()
A few emails (under 10)
send() in a loop is fine
Newsletters, bulk notifications
sendMany()
Batch processing from a queue
sendMany()
Part 7: Testing without sending real emails
Upyo includes a MockTransport for testing:
No external dependencies: Tests run offline, in CI, anywhere
Deterministic: No flaky tests due to network issues
Fast: No HTTP requests or SMTP handshakes
Inspectable: You can verify exactly what would have been sent
Basic testing setup
import { createMessage } from "@upyo/core";
import { MockTransport } from "@upyo/mock";
import assert from "node:assert";
import { describe, it, beforeEach } from "node:test";
describe("Email functionality", () => {
let transport: MockTransport;
beforeEach(() => {
transport = new MockTransport();
});
it("should send welcome email after registration", async () => {
// Your application code would call this
const message = createMessage({
from: "welcome@yourapp.com",
to: "newuser@example.com",
subject: "Welcome to our app!",
content: { text: "Thanks for signing up!" },
});
const receipt = await transport.send(message);
// Assertions
assert.strictEqual(receipt.successful, true);
assert.strictEqual(transport.getSentMessagesCount(), 1);
const sentMessage = transport.getLastSentMessage();
assert.strictEqual(sentMessage?.subject, "Welcome to our app!");
assert.strictEqual(sentMessage?.recipients[0].address, "newuser@example.com");
});
it("should handle email failures gracefully", async () => {
// Simulate a failure
transport.setNextResponse({
successful: false,
errorMessages: ["Invalid recipient address"],
});
const message = createMessage({
from: "test@yourapp.com",
to: "invalid-email",
subject: "Test",
content: { text: "Test" },
});
const receipt = await transport.send(message);
assert.strictEqual(receipt.successful, false);
assert.ok(receipt.errorMessages.includes("Invalid recipient address"));
});
});
The key testing methods:
getSentMessagesCount(): How many emails were âsentâ
getLastSentMessage(): The most recent message
getSentMessages(): All messages as an array
setNextResponse(): Force the next send to succeed or fail with specific errors
Simulating real-world conditions
import { MockTransport } from "@upyo/mock";
// Simulate network delays
const slowTransport = new MockTransport({
delay: 500, // 500ms delay per email
});
// Simulate random failures (10% failure rate)
const unreliableTransport = new MockTransport({
failureRate: 0.1,
});
// Simulate variable latency
const realisticTransport = new MockTransport({
randomDelayRange: { min: 100, max: 500 },
});
Testing async email workflows
import { MockTransport } from "@upyo/mock";
const transport = new MockTransport();
// Start your async operation that sends emails
startUserRegistration("newuser@example.com");
// Wait for the expected emails to be sent
await transport.waitForMessageCount(2, 5000); // Wait for 2 emails, 5s timeout
// Or wait for a specific email
const welcomeEmail = await transport.waitForMessage(
(msg) => msg.subject.includes("Welcome"),
3000
);
console.log("Welcome email was sent:", welcomeEmail.subject);
Part 8: Provider failover with PoolTransport
What happens if your email provider goes down? For mission-critical applications, you need redundancy. PoolTransport combines multiple providers with automatic failoverâif one fails, it tries the next.
import { PoolTransport } from "@upyo/pool";
import { ResendTransport } from "@upyo/resend";
import { SendGridTransport } from "@upyo/sendgrid";
import { MailgunTransport } from "@upyo/mailgun";
import { createMessage } from "@upyo/core";
// Create multiple transports
const resend = new ResendTransport({ apiKey: process.env.RESEND_API_KEY! });
const sendgrid = new SendGridTransport({ apiKey: process.env.SENDGRID_API_KEY! });
const mailgun = new MailgunTransport({
apiKey: process.env.MAILGUN_API_KEY!,
domain: "mg.yourdomain.com",
});
// Combine them with priority-based failover
const transport = new PoolTransport({
strategy: "priority",
transports: [
{ transport: resend, priority: 100 }, // Try first
{ transport: sendgrid, priority: 50 }, // Fallback
{ transport: mailgun, priority: 10 }, // Last resort
],
maxRetries: 3,
});
const message = createMessage({
from: "critical@yourdomain.com",
to: "admin@example.com",
subject: "Critical alert",
content: { text: "This email will try multiple providers if needed." },
});
const receipt = await transport.send(message);
// Automatically tries Resend first, then SendGrid, then Mailgun if others fail
The priority values determine the orderâhigher numbers are tried first. If Resend fails (network error, rate limit, etc.), the pool automatically retries with SendGrid, then Mailgun.
For more advanced routing strategies (weighted distribution, content-based routing), see the pool transport documentation.
Part 9: Observability with OpenTelemetry
In production, you'll want to track email metrics: send rates, failure rates, latency. Upyo integrates with OpenTelemetry:
import { createOpenTelemetryTransport } from "@upyo/opentelemetry";
import { SmtpTransport } from "@upyo/smtp";
const baseTransport = new SmtpTransport({
host: "smtp.example.com",
port: 587,
auth: { user: "user", pass: "password" },
});
const transport = createOpenTelemetryTransport(baseTransport, {
serviceName: "email-service",
tracing: { enabled: true },
metrics: { enabled: true },
});
// Now all email operations generate traces and metrics automatically
await transport.send(message);
This gives you:
Delivery success/failure rates
Send operation latency histograms
Error classification by type
Distributed tracing for debugging
See the OpenTelemetry documentation for details.
Quick reference: choosing the right transport
Scenario
Recommended Transport
Development/testing
Gmail SMTP or MockTransport
Small production app
Resend or SendGrid
High volume (100k+/month)
Amazon SES
Edge functions
Resend, SendGrid, or Mailgun
Self-hosted infrastructure
SMTP with DKIM
Mission-critical
PoolTransport with failover
EU data residency
Mailgun (EU region) or self-hosted
Wrapping up
This guide covered the most popular transports, but Upyo also supports:
JMAP: Modern email protocol (RFC 8620/8621) for JMAP-compatible servers like Fastmail and Stalwart
Plunk: Developer-friendly email service with self-hosting option
And you can always create a custom transport for any email service not yet supported.
Resources
đ Documentation
đŠ npm packages
đŠ JSR packages
đ GitHub repository
Have questions or feedback? Feel free to open an issue.
What's been your biggest pain point when sending emails from JavaScript? Let me know in the commentsâI'm curious what challenges others have run into.
Upyo (pronounced /oo-pyo/) comes from the Korean word é”ç„š, meaning âpostage stamp.â
undefined evan@cosocial.ca shared this topic
undefined oblomov@sociale.network shared this topic
