Integrate HS Mail in Minutes
Official client libraries for PHP, Node.js, and Python. Full type safety, built-in authentication, automatic error handling — everything you need to work with the HS Mail API without writing a single raw HTTP call.
PHP SDK
Packagistcomposer require hsmail/hsmail-sdk- PHP 8.0+
- Guzzle HTTP Client
- 5 Typed Exceptions
- Composer / Packagist
Node.js SDK
npmnpm install hsmail-sdk- Node 18+ / TypeScript
- Zero Dependencies
- 25+ Type Definitions
- npm / yarn / pnpm
Python SDK
PyPIpip install hsmail-sdk- Python 3.8+
- requests Library
- Pythonic Naming
- pip / PyPI
Complete API Coverage
All 18 endpoints across 6 resource groups — fully wrapped by every SDK.
- GET /v1/profile
- GET /v1/products
- GET /v1/products/:id
- POST /v1/orders
- GET /v1/orders/:id
- GET /v1/orders/:id/messages
- POST /v1/orders/:id/message
- POST /v1/orders/:id/reopen
- Outlook read / check / refresh
- Gmail read / check
- Facebook bulk / single
- Instagram check
- Hotmail Creator
- POST /v1/tools/2fa
- GET /v1/ping
What You Can Build
Every capability of the HS Mail platform, directly accessible from your code.
Authentication System
Flexible, secure, and zero-config inside the SDK — just pass your key.
Bearer Token
Pass your key via Authorization: Bearer header — the standard, secure method.
Query Parameter
Alternatively append ?api_key=xxx — useful for quick testing.
IP Whitelisting
Lock your key to specific IP addresses from the dashboard for zero-trust security.
Account Guards
Keys are automatically invalidated if the account is banned, suspended, or unverified.
# Method 1 — Authorization header (recommended)
Authorization: Bearer hs_live_xxxxxxxxxxxxxxxxxxxxxxxx
# Method 2 — Query parameter (quick testing)
GET https://api.hsmail.shop/v1/profile?api_key=hs_live_xxxRate Limiting
Every SDK handles rate limit errors automatically with typed exceptions.
100 req / min
X-RateLimit-Remaining
RATE_LIMIT_EXCEEDED (429)
Wait 60 seconds, then retry
// PHP
try { ... }
catch (RateLimitException $e) {
sleep(60); // wait & retry
}// Node.js
} catch (err) {
if (err instanceof RateLimitError)
await sleep(60_000);
}# Python
except RateLimitError:
import time
time.sleep(60)Unified Error Hierarchy
Same exception structure across all three SDKs — easy to learn once, use everywhere.
| Exception / Error Class | HTTP Status | When It's Thrown |
|---|---|---|
| AuthenticationException | 401 / 403 | Invalid key, banned, suspended, or unverified account |
| RateLimitException | 429 | More than 100 requests per minute |
| NotFoundException | 404 | Product, order, or resource does not exist |
| InsufficientBalanceException | 400 | Account balance too low to complete the order |
| ValidationException | 400 / 422 | Out of stock, order closed, invalid parameters |
| HsMailException (base) | Any | Catch-all for unexpected API errors |
Quick Start — 3 Steps
From zero to first API call in under 2 minutes.
Get Your API Key
Log into the HS Mail dashboard → Settings → API Keys → Generate → Copy your key (starts with "hs_live_").
Open Dashboard →Install the SDK
Pick your language and run the install command. The SDK has no build steps — just install and import.
npm install hsmail-sdk # Node.js
pip install hsmail-sdk # Python
composer require hsmail/hsmail-sdk # PHPMake Your First Call
Initialise the client with your key. All methods return typed objects — no JSON parsing needed.
import { HsMailClient } from 'hsmail-sdk';
const client = new HsMailClient({ apiKey: 'hs_live_xxx' });
const profile = await client.getProfile();
console.log(profile.balance); // e.g. 500 BDTReady to Build?
Pick your language, install the SDK, and go. Full reference documentation is one click away.