Node.js SDK - Installation

The @mailiam/node SDK provides a complete solution for sending transactional emails from your Node.js applications.

Installation

Install the package using npm:

npm install @mailiam/node

Or using yarn:

yarn add @mailiam/node

Or using pnpm:

pnpm add @mailiam/node

Requirements

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

Get an API Key

You need a Usage or Admin API key to use the Node.js SDK:

# Install mailiam CLI if you haven't already
npm install -g mailiam

# Create a usage key for your application
mailiam keys create --name "Production Server" --type usage

Save the key that starts with mlm_sk_... - you’ll need it for authentication.

Keep Your Key Secret

Usage and Admin keys should never be exposed in client-side code. Always keep them in environment variables on your server.

Basic Setup

JavaScript (CommonJS)

const { mailiam } = require('@mailiam/node');

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

JavaScript (ES Modules)

import { mailiam } from '@mailiam/node';

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

TypeScript

import { mailiam } from '@mailiam/node';

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

Configuration Options

The SDK accepts several configuration options:

const mailiam = new mailiam({
  // Required: Your API key
  apiKey: 'mlm_sk_...',

  // Optional: Custom API base URL (default: https://api.mailiam.dev)
  baseUrl: 'https://api.mailiam.dev',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Maximum retry attempts (default: 3)
  maxRetries: 3,

  // Optional: Enable debug logging (default: false)
  debug: false
});

Environment Variables

Store your API key in environment variables:

Using .env file

Create a .env file:

MAILIAM_API_KEY=mlm_sk_your_key_here

Install dotenv:

npm install dotenv

Load it in your application:

import 'dotenv/config';
import { mailiam } from '@mailiam/node';

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

Next.js

Next.js automatically loads .env.local:

.env.local

MAILIAM_API_KEY=mlm_sk_your_key_here

Use it in API routes:

pages/api/send-email.ts

import { mailiam } from '@mailiam/node';

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

export default async function handler(req, res) {
  // Use mailiam here
}

Vercel / Netlify

Add environment variables in your hosting platform’s dashboard under “Environment Variables” or “Settings”.

Verify Installation

Test that everything is working:

import { mailiam } from '@mailiam/node';

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

async function test() {
  try {
    const result = await mailiam.emails.send({
      from: 'hello@yourdomain.com',
      to: 'test@example.com',
      subject: 'Test Email',
      text: 'Hello from mailiam!'
    });

    console.log('✓ SDK working! Message ID:', result.messageId);
  } catch (error) {
    console.error('✗ Error:', error.message);
  }
}

test();

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Next Steps

• Sending Emails - Learn how to send emails
• Batch Operations - Send multiple emails
• Error Handling - Handle errors gracefully
• API Reference - Complete API documentation