@mailiam/node

Official Node.js SDK for Mailiam - Transactional email made simple.

Installation

npm install @mailiam/node

Quick Start

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

# Install Mailiam CLI
npm install -g mailiam

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

Send a Single Email

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

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

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:

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