@xyz/email

A unified library to send emails - Choose your own email provider.

Features

• 🔌 Unified interface for multiple email providers
• 📝 TypeScript support with full type definitions
• 🔄 Easy to switch between providers without changing your code
• 🚀 Works with Node.js, Bun, Deno, and Cloudflare Workers

Supported Providers

| Provider | Environment Variable | |----------|---------------------| | Nodemailer | MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS | | Resend | RESEND_API_KEY | | Postmark | POSTMARK_SERVER_TOKEN | | Plunk | PLUNK_API_KEY | | Console | (none - logs to console) | | Custom | (implement your own) |

Installation

# npm
npm install @xyz/email

# pnpm
pnpm add @xyz/email

# yarn
yarn add @xyz/email

# bun
bun add @xyz/email

Environment Variables

Create a .env file with the appropriate variables for your chosen provider:

# Nodemailer (SMTP)
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USER=your-username
MAIL_PASS=your-password
[email protected]

# Resend
RESEND_API_KEY=re_xxxxxxxxxxxx

# Postmark
POSTMARK_SERVER_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Plunk
PLUNK_API_KEY=pk_xxxxxxxxxxxx

Usage

import { useEmail } from "@xyz/email";

// Choose your provider
const emailService = useEmail("resend");

// Send an email
await emailService.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Hello!",
  text: "This is a plain text email.",
  html: "<h1>Hello!</h1><p>This is an HTML email.</p>",
});

Sending to Multiple Recipients

await useEmail("postmark").send({
  from: "[email protected]",
  to: ["[email protected]", "[email protected]"],
  subject: "Team Update",
  text: "Hello team!",
});

Switching Providers

const resend = useEmail("resend");
const postmark = useEmail("postmark");
const nodemailer = useEmail("nodemailer");
const plunk = useEmail("plunk");
const consoleLogger = useEmail("console"); // For development

API Reference

useEmail(provider: EmailProvider)

Creates an email service instance for the specified provider.

Parameters:

• provider: One of "nodemailer" | "resend" | "postmark" | "plunk" | "console" | "custom"

Returns:

• An email service instance with a send method

send(options: SendEmailParams)

Sends an email using the configured provider.

Parameters:

| Property | Type | Required | Description | |----------|------|----------|-------------| | from | string | ✅ | Sender email address | | to | string \| string[] | ✅ | Recipient email address(es) | | subject | string | ✅ | Email subject | | text | string | ❌ | Plain text content | | html | string | ❌ | HTML content |

Returns:

• Promise<void>

Error Handling

try {
  await useEmail("resend").send({
    from: "[email protected]",
    to: "[email protected]",
    subject: "Hello",
    text: "Hello World",
  });
  console.log("Email sent successfully");
} catch (error) {
  console.error("Failed to send email:", error);
}

TypeScript Support

This package is written in TypeScript and provides type definitions out of the box.

import { useEmail, type SendEmailParams, type EmailProvider } from "@xyz/email";

const provider: EmailProvider = "resend";
const options: SendEmailParams = {
  from: "[email protected]",
  to: "[email protected]",
  subject: "Typed Email",
  text: "Hello!",
};

await useEmail(provider).send(options);

License

MIT