Getting started

This guide will help you set up Upyo in your project and send your first email.

Installation

To install Upyo, you can use your preferred package manager. Upyo is available on JSR and npm, so you can choose the one that fits your project best:

npm

npm add @upyo/core

pnpm

pnpm add @upyo/core

Yarn

yarn add @upyo/core

Deno

deno add jsr:@upyo/core

Bun

bun add @upyo/core

Choosing a transport

Upyo supports multiple transports for sending emails, each with different strengths and use cases:

SMTP

Universal email protocol, works with any SMTP server

Mailgun

HTTP API service with advanced features and analytics

SendGrid

Popular email API with deliverability focus

Amazon SES

Cost-effective email service for AWS users

Mock transport

Testing utility that captures emails without sending

If none of these fit your needs, you can also create a custom transport to integrate with any email service or add specialized functionality.

To get started, install the transport package for your chosen option. For example, to use the SMTP transport, you would install the @upyo/smtp package:

npm

npm add @upyo/smtp

pnpm

pnpm add @upyo/smtp

Yarn

yarn add @upyo/smtp

Deno

deno add jsr:@upyo/smtp

Bun

bun add @upyo/smtp

CAUTION

The SMTP transport currently does not support edge functions or web browsers. If you need to use Upyo in these environments, consider using other transports like Mailgun or similar services that provide HTTP APIs.

Sending your first email

Once you have installed the core package and the transport you want to use, you can start sending emails. Here's a basic example using Gmail through SMTP:

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

const transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true, // Use TLS
  auth: {
    user: "[email protected]",
    pass: "your-app-password",
  }
});

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Hello from Upyo!",
  content: { text: "This is a test email." },
});

const receipt = await transport.send(message);
if (receipt.successful) {
  console.log("Message sent with ID:", receipt.messageId);
} else {
  console.error("Send failed:", receipt.errorMessages.join(", "));
}

That's it! You have sent your first email using Upyo. You can customize the message with HTML content, attachments, and more.