@orello/mailer/README.md

SDK for Orello Email Service — A developer-friendly toolkit to integrate email delivery, events, and interactions.

# 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

```bash
npm install orello
# or
pnpm add orello
```

## Configuration

Set your API KEY in environment variables:

```env
ORELLO_API_KEY=your-orello-api-key
```

## Usage

```typescript
import { Orello } from "orello";

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

### Sending an Email

```typescript
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

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

### Scheduling an Email

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

### Subscribing a User

```typescript
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.

```typescript
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