Python SDK

Official Python 3.8+ client library for the HS Mail API. Simple, Pythonic, and PyPI-ready.

Python ≥ 3.8requests ≥ 2.28MIT LicensePyPI

Installation

bash
pip install hsmail-sdk

Quick Start

python
from hsmail import HsMailClient

client = HsMailClient(api_key="YOUR_API_KEY")

# Ping
status = client.ping()
print("IP:", status["ip"])

# Profile
profile = client.get_profile()
print(f"Balance: {profile['balance']} BDT")

# Products
categories = client.products.list()

# Order
order = client.orders.create("product-uuid", quantity=1)
print("Order ID:", order["orderId"])

# 2FA
result = client.tools.generate_2fa("BASE32_SECRET")
print(f"Code: {result['code']}  ({result['timeRemaining']}s)")

Authentication

Get your API key from the HS Mail Dashboard.

python
client = HsMailClient(
    api_key="hs_live_xxxxxxxxxxxxxxx",
    base_url="https://api.hsmail.shop",  # optional
    timeout=30,                           # seconds, optional
)

API Reference

Profile & Status

python
client.ping()          # { status, message, ip, timestamp }
client.get_profile()   # { id, name, email, balance, rankLevel, ... }

Products

python
client.products.list()           # All categories + products
client.products.get("uuid")      # Single product by UUID

Orders

python
# Create order
order = client.orders.create("product-uuid", quantity=1)
order_id = order["orderId"]

# Get details
details = client.orders.get(order_id)

# Service order messages (poll-based)
msgs = client.orders.messages(order_id)

# Send message
client.orders.send_message(order_id, message="Please process ASAP")

# Reopen under warranty
client.orders.reopen(order_id)

Mailbox

python
# Outlook
client.mailbox.read_outlook(email, refresh_token, client_id)
client.mailbox.refresh_outlook_token(client_id, refresh_token)
client.mailbox.check_outlook(email, refresh_token, client_id)

# Gmail (requires GMAIL subscription)
client.mailbox.read_gmail(email, order_id)
client.mailbox.check_gmail(email)

# Facebook (requires FB subscription)
client.mailbox.check_facebook_bulk(["acc:pass", ...])
client.mailbox.check_facebook("FB_USER_ID")

# Instagram (requires IG subscription)
client.mailbox.check_instagram("username")

# Hotmail Creator
client.mailbox.create_hotmail_order(["a@hotmail.com"], "USER_ONLY")

Tools

python
result = client.tools.generate_2fa("JBSWY3DPEHPK3PXP")
# { 'code': '123456', 'timeRemaining': 17 }

Error Handling

python
from hsmail import (
    HsMailError,
    InsufficientBalanceError,
    RateLimitError,
    AuthenticationError,
    ValidationError,
)

try:
    order = client.orders.create("product-uuid")
except InsufficientBalanceError:
    print("Top up at https://hsmail.shop")
except RateLimitError:
    import time; time.sleep(60)   # Wait 60s and retry
except AuthenticationError as e:
    print(f"Auth problem: {e.code}")
except HsMailError as e:
    print(f"[{e.code}] {e}  (HTTP {e.http_status})")
ExceptionTrigger
AuthenticationErrorInvalid key, banned/suspended account
RateLimitError>100 requests/minute
NotFoundErrorResource doesn't exist
InsufficientBalanceErrorNot enough BDT balance
ValidationErrorInvalid input, out of stock, closed order
HsMailErrorBase — all other API errors

Publishing to PyPI

bash
# Install build tools
pip install build twine

# Build distribution
python -m build

# Upload to PyPI (you'll need a PyPI account and API token)
twine upload dist/*
Create an account at pypi.org
Generate an API token in Account Settings → API Tokens
Add it to ~/.pypirc or use the --username __token__ --password flag