Composing messages

Creating email messages in Upyo is straightforward and flexible. The library provides the createMessage() function from the @upyo/core package, which accepts various input formats and automatically handles validation and type conversion for you.

Basic message creation

To create a simple email message, you need to provide at minimum a sender address, recipient address, subject, and content. The createMessage() function accepts these in a convenient object format:

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

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

The function automatically converts string email addresses to proper Address objects and validates the input. You can provide email addresses as simple strings like "[email protected]" or with display names using the format "Name <[email protected]>" like "John Doe <[email protected]>". You can also provide Address objects directly if you prefer to work with the structured format.

Multiple recipients

When you need to send an email to multiple recipients, you can provide arrays for the to, cc, and bcc fields. Each field accepts either a single address or an array of addresses, and you can mix different formats including plain email addresses, display name formats, and Address objects:

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

const message = createMessage({
  from: "Support Team <[email protected]>",
  to: ["[email protected]", "John Smith <[email protected]>"],
  cc: { name: "Manager", address: "[email protected]" },
  bcc: ["[email protected]", "[email protected]"],
  subject: "Team Update",
  content: { text: "Here's the latest team update." },
});

You can also specify a custom reply-to address using the replyTo field, which is useful when you want replies to go to a different address than the sender:

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  replyTo: "[email protected]",
  subject: "Welcome to our service",
  content: { text: "Thank you for signing up!" },
});

Rich content

Upyo supports both plain text and HTML email content. You can provide just text content, just HTML content, or both. When you provide both, email clients will choose the appropriate format to display:

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Monthly Newsletter",
  content: {
    html: "<h1>Welcome to our newsletter!</h1><p>This month we have exciting updates.</p>",
    text: "Welcome to our newsletter! This month we have exciting updates.",
  },
});

If you only need plain text, you can simply provide the text property:

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "System Notification",
  content: { text: "Your backup has completed successfully." },
});

Message priority and organization

You can set the priority level of your messages to help recipients understand their importance. Upyo supports three priority levels: "high", "normal", and "low":

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Server Alert",
  content: { text: "The server is experiencing high load." },
  priority: "high",
});

For better organization and filtering, you can add tags to your messages. Tags are simple strings that can help you categorize and search your emails later:

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

const message = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Ticket Update",
  content: { text: "Your support ticket has been updated." },
  tags: ["support", "customer-service", "urgent"],
});

Custom headers

Sometimes you need to include custom email headers for specific functionality or compliance requirements. You can add custom headers using the headers field as a simple object, a standard Headers instance, or an ImmutableHeaders instance (which is an immutable version compatible with the standard Headers interface):

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

// Using a simple object
const message1 = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Password Reset",
  content: { text: "Click the link to reset your password." },
  headers: {
    "X-Mailer": "Upyo Email Library",
    "X-Priority": "1",
    "List-Unsubscribe": "<mailto:[email protected]>",
  },
});

// Using standard Headers object
const headers = new Headers();
headers.set("X-Mailer", "Upyo Email Library");
headers.set("X-Priority", "1");

const message2 = createMessage({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Password Reset",
  content: { text: "Click the link to reset your password." },
  headers,
});

The createMessage() function handles all the complexity of email message construction, ensuring that your messages are properly formatted and valid before sending them through your chosen transport.