npm package: @mailiam/node
Description: Official Node.js SDK for Mailiam - transactional email made simple
Author: Mailiam
Latest version: 0.2.0

# @mailiam/node

Official Node.js SDK for [Mailiam](https://mailiam.io) - Transactional email made simple.

## Installation

```bash
npm install @mailiam/node
```

## Quick Start

```typescript
import { Mailiam } from '@mailiam/node';

const mailiam = new Mailiam({
  apiKey: process.env.MAILIAM_API_KEY
});

// Send a single email
await mailiam.emails.send({
  from: 'hello@mycompany.com',
  to: 'customer@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our service</h1>'
});
```

## Features

- ✅ **TypeScript Support** - Full type safety with TypeScript definitions
- ✅ **Automatic Retries** - Built-in retry logic with exponential backoff
- ✅ **Rate Limit Handling** - Respects 429 responses and retries appropriately
- ✅ **Batch Sending** - Send multiple emails efficiently
- ✅ **Error Handling** - Comprehensive error classes for different failure modes
- ✅ **Zero Dependencies** - Uses native fetch API (Node.js 18+)

## Usage

### Get Your API Key

```bash
# Install Mailiam CLI
npm install -g mailiam

# Create an API key
mailiam keys create --name "Production" --type usage
```

### Send a Single Email

```typescript
import { Mailiam } from '@mailiam/node';

const mailiam = new Mailiam({
  apiKey: 'mlm_sk_...'
});

try {
  const result = await mailiam.emails.send({
    from: 'hello@mycompany.com',
    to: 'customer@example.com',
    subject: 'Welcome!',
    html: '<h1>Welcome!</h1>',
    text: 'Welcome!', // Optional plain text version
    replyTo: 'support@mycompany.com', // Optional
    cc: ['team@mycompany.com'], // Optional
    bcc: ['archive@mycompany.com'] // Optional
  });

  console.log('Email sent:', result.messageId);
} catch (error) {
  console.error('Failed to send:', error.message);
}
```

### Send Batch Emails

```typescript
const users = [
  { email: 'user1@example.com', name: 'Alice' },
  { email: 'user2@example.com', name: 'Bob' }
];

const emails = users.map(user => ({
  from: 'notifications@mycompany.com',
  to: user.email,
  subject: `Hello ${user.name}!`,
  html: `<h1>Hi ${user.name}!</h1>`
}));

const result = await mailiam.emails.sendBatch(emails);
console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);
```

### With Custom Configuration

```typescript
const mailiam = new Mailiam({
  apiKey: 'mlm_sk_...',
  baseUrl: 'https://api.mailiam.dev', // Optional: Custom API URL
  timeout: 30000, // Optional: Request timeout in ms (default: 30000)
  maxRetries: 3, // Optional: Max retry attempts (default: 3)
  debug: false // Optional: Enable debug logging (default: false)
});
```

## Error Handling

The SDK provides specific error classes for different failure modes:

```typescript
import {
  Mailiam,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NetworkError,
  ApiError
} from '@mailiam/node';

try {
  await mailiam.emails.send({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded (429)
    console.log('Retry after:', error.retryAfter);
  } else if (error instanceof ValidationError) {
    // Invalid request data
  } else if (error instanceof NetworkError) {
    // Network/timeout error
  } else if (error instanceof ApiError) {
    // Other API error
    console.log('Status:', error.statusCode);
  }
}
```

## Examples

See the [examples directory](../../examples) for more detailed examples:

- **Basic Email** - Simple single email
- **Batch Emails** - Send multiple emails
- **Express.js** - Integration with Express
- **Next.js API Route** - Integration with Next.js

## Requirements

- Node.js 16.0.0 or higher
- Native fetch support (Node.js 18+) or a fetch polyfill

## License

MIT

## Support

- Documentation: https://mailiam.io/docs
- Issues: https://github.com/mailiam/mailiam/issues
- Email: team@mailiam.dev