Node.js SDK

Official TypeScript/JavaScript client library for the HS Mail API. Zero dependencies — uses native fetch (Node 18+).

Node.js ≥ 18TypeScript 5Zero DependenciesMIT Licensenpm

Installation

bash

npm install hsmail-sdk
# or
yarn add hsmail-sdk
# or
pnpm add hsmail-sdk

Quick Start

typescript

import { HsMailClient } from 'hsmail-sdk';

const client = new HsMailClient({ apiKey: 'YOUR_API_KEY' });

// Ping
const ping = await client.ping();
console.log('Your IP:', ping.ip);

// Profile
const profile = await client.getProfile();
console.log('Balance:', profile.balance, 'BDT');

// Products
const categories = await client.products.list();

// Place an order
const order = await client.orders.create('product-uuid', 1);
console.log('Order ID:', order.orderId);

// 2FA
const twofa = await client.tools.generate2fa('BASE32_SECRET');
console.log(`Code: ${twofa.code} (${twofa.timeRemaining}s)`);

Authentication

Get your API key from the HS Mail Dashboard.

typescript

const client = new HsMailClient({
    apiKey:  'hs_live_xxxxxxxxxxxxxxx',
    baseUrl: 'https://api.hsmail.shop',   // optional
    timeout: 30000,                        // ms, optional
});

TypeScript Types

All request and response objects are fully typed. Import them from hsmail-sdk:

typescript

import type {
    Profile, Category, Product, ProductDetail,
    CreateOrderResult, OrderDetail, OrderDetail,
    OutlookReadResult, TokenRefreshResult,
    TwoFaResult, HsMailClientOptions
} from 'hsmail-sdk';

API Reference

Products

typescript

const categories = await client.products.list();
const product    = await client.products.get('product-uuid');

Orders

typescript

// Create order (quantity defaults to 1)
const order = await client.orders.create('product-uuid', 1);

// Get order
const details = await client.orders.get('ORDER_ID');

// Service order messages
const chat = await client.orders.messages('ORDER_ID');

// Send message
await client.orders.sendMessage('ORDER_ID', 'Please process ASAP');

// Reopen under warranty
await client.orders.reopen('ORDER_ID');

Mailbox

typescript

// Outlook
await client.mailbox.readOutlook(email, refreshToken, clientId);
await client.mailbox.refreshOutlookToken(clientId, refreshToken);
await client.mailbox.checkOutlook(email, refreshToken, clientId);

// Gmail (requires GMAIL subscription)
await client.mailbox.readGmail(email, orderId);
await client.mailbox.checkGmail(email);

// Facebook (requires FB subscription)
await client.mailbox.checkFacebookBulk(['acc:pass', ...]);
await client.mailbox.checkFacebook('FB_USER_ID');

// Instagram (requires IG subscription)
await client.mailbox.checkInstagram('username');

// Hotmail Creator
await client.mailbox.createHotmailOrder(
    ['a@hotmail.com', 'b@hotmail.com'],
    'USER_ONLY'
);

Tools

typescript

const result = await client.tools.generate2fa('JBSWY3DPEHPK3PXP');
// { code: '123456', timeRemaining: 17 }

Error Handling

typescript

import {
    HsMailError,
    InsufficientBalanceError,
    RateLimitError,
    AuthenticationError,
} from 'hsmail-sdk';

try {
    const order = await client.orders.create('product-uuid');
} catch (err) {
    if (err instanceof InsufficientBalanceError) {
        console.error('Top up at https://hsmail.shop');
    } else if (err instanceof RateLimitError) {
        await new Promise(r => setTimeout(r, 60_000)); // wait 60s
    } else if (err instanceof HsMailError) {
        console.error(`[${err.code}] ${err.message} (HTTP ${err.statusCode})`);
    }
}

Build & Publish to npm

bash

# Build (compiles TypeScript to dist/)
npm run build

# Login to npm
npm login

# Publish
npm publish --access public

The package exports both CommonJS (dist/index.js) and ESM (dist/index.mjs), so it works in all environments.