HS Mail Node.js SDK

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

Installation

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

Quick Start

import { HsMailClient } from 'hsmail-sdk';

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

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

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

// List 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);

Authentication

Get your API key from the HS Mail Dashboard.

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

API Reference

Profile & Status

const ping    = await client.ping();
const profile = await client.getProfile();

Products

// List all categories + products
const categories = await client.products.list();

// Single product by UUID
const product = await client.products.get('product-uuid');

Product object:

{
    uuid: string, name: string, slug: string,
    type: 'normal' | 'service',
    price: number,   // BDT, rank-adjusted
    stock: number,
    warranty: string | null,
    ...
}

Orders

// Create an order
const order = await client.orders.create('product-uuid', 1);
// { orderId, productName, status, isService, totalCost, items[] }

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

// Service order — get 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');

Order statuses: PENDING · PROCESSING · COMPLETED · DELIVERED · REFUNDED

Mailbox

Outlook / Hotmail

// Read inbox
const inbox = await client.mailbox.readOutlook(email, refreshToken, clientId);

// Refresh token
const tokens = await client.mailbox.refreshOutlookToken(clientId, refreshToken);

// Check status
const check = await client.mailbox.checkOutlook(email, refreshToken, clientId);
// { accountStatus: 'Live' | 'Die' }

Gmail (requires GMAIL subscription)

const messages = await client.mailbox.readGmail('[email protected]', orderId);
const status   = await client.mailbox.checkGmail('[email protected]');

Facebook (requires FB subscription)

const bulk   = await client.mailbox.checkFacebookBulk(['acc:pass', ...]);
const single = await client.mailbox.checkFacebook('FB_USER_ID');

Instagram (requires IG subscription)

const ig = await client.mailbox.checkInstagram('username');

Hotmail Creator

const result = await client.mailbox.createHotmailOrder(
    ['[email protected]', '[email protected]'],
    'USER_ONLY'
);

Tools

const twofa = await client.tools.generate2fa('JBSWY3DPEHPK3PXP');
console.log(`${twofa.code}  (valid ${twofa.timeRemaining}s)`);

Error Handling

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

try {
    const order = await client.orders.create('product-uuid', 1);
} catch (err) {
    if (err instanceof InsufficientBalanceError) {
        console.error('Top up your balance at https://hsmail.shop');
    } else if (err instanceof RateLimitError) {
        await sleep(60_000);  // Wait 60s and retry
    } else if (err instanceof HsMailError) {
        console.error(`[${err.code}] ${err.message} (HTTP ${err.statusCode})`);
    }
}

| Class | Trigger | |---|---| | AuthenticationError | Invalid key, banned/suspended/unverified account | | RateLimitError | >100 requests/minute | | NotFoundError | Resource doesn't exist | | InsufficientBalanceError | Not enough BDT balance | | ValidationError | Invalid params, out of stock, closed order | | HsMailError | All other API errors |

Publishing to npm

# Build first
npm run build

# Login to npm
npm login

# Publish
npm publish --access public

License

MIT © HS Mail Team