Orello SDK

A robust, TypeScript-first Node.js SDK for sending transactional and templated emails, managing subscriptions, and handling email events via the Orello API.

Features

• Send emails (immediate or scheduled)
• Use templates with dynamic data
• Attach files (Buffer, Blob, string)
• Subscribe users to lists
• Event-driven hooks for delivery, engagement, and system events
• Type-safe, modern API

Installation

npm install orello
# or
pnpm add orello

Configuration

Set your API KEY in environment variables:

ORELLO_API_KEY=your-orello-api-key

Usage

import { Orello } from "orello";

const orello = new Orello({
  apiKey: process.env.ORELLO_API_KEY!,
  timeoutMs: 10000, // optional, default 15000ms
});

Sending an Email

const mail = {
  to: "user@example.com",
  subject: "Welcome!",
  text: "Hello, welcome to Orello.",
  html: "<b>Hello, welcome to Orello.</b>",
  attachments: [
    {
      filename: "info.pdf",
      content: Buffer.from("..."),
      contentType: "application/pdf",
    },
  ],
};

orello.createMail(mail).send();

Using Templates

orello.useTemplate("welcome-template-id", {
  to: "user@example.com",
  data: { name: "John" },
}).send();

Scheduling an Email

orello.createMail({
  ...mail,
  sendAt: new Date(Date.now() + 3600 * 1000), // send in 1 hour
}).scheduleSend();

Subscribing a User

await orello.subscribe({
  subscription: "newsletter",
  email: "user@example.com",
  firstName: "John",
});

API Reference

Orello(options: OrelloConfig)

• apiKey (string, required): Your Orello API key
• timeoutMs (number, optional): Request timeout in ms

createMail(mail: OrelloMailerConfig)

Returns a mail builder with methods:

• send(): Send immediately
• scheduleSend(): Send at a future time
• queue(): Queue for later (custom logic)
• on(event, callback): Listen for events

OrelloMailerConfig

• to, cc, bcc: string or string[]
• subject: string
• text, html: string
• attachments: Array of { filename, content, contentType }
• headers, metadata: Record<string, string>
• sendAt: Date | ISO string | timestamp

useTemplate(templateId: string, options: OrelloTemplateMailerOption)

Returns a template mail builder with same methods as above.

OrelloTemplateMailerOption

• to, cc, bcc: string or string[]
• data: Record<string, any> (template variables)
• attachments: Array of attachments
• sendAt: Date | ISO string | timestamp

subscribe(subscription: OrelloSubscriptionOptions)

Subscribes a user to a list.

OrelloSubscriptionOptions

• subscription: string (list ID)
• email: string
• firstName, lastName: string
• message: string (optional)

Events

Supported events:

• Delivery: QUEUED, SENT, DELIVERED, BOUNCED, SPAM
• Engagement: OPEN, CLICK, REPLY, FORWARD, ATTACHMENT_OPEN
• Subscription: SUBSCRIBE, UNSUBSCRIBE, PROFILE_UPDATE
• System: DROPPED, DEFERRED, FAILED, BLACKLISTED, DELIVERY_OPTIMIZED, ERROR

Error Handling

All SDK errors throw OrelloError for easy detection.

try {
  await orello.createMail(mail).send();
} catch (err) {
  if (err instanceof OrelloError) {
    // handle SDK error
  }
}

TypeScript Support

All types are exported for strong typing and IDE autocompletion.

License

MIT