HS Mail Python SDK

Official Python SDK for the HS Mail API. Manage orders, read mailboxes, check live accounts, and generate 2FA codes.

Installation

pip install hsmail-sdk

Quick Start

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.

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

API Reference

Profile & Status

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

Products

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

Orders

client.orders.create("uuid", quantity=1)
client.orders.get("ORDER_ID")
client.orders.messages("ORDER_ID")
client.orders.send_message("ORDER_ID", message="Hello")
client.orders.reopen("ORDER_ID")

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

Mailbox

# 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(["email: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

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

Error Handling

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

try:
    order = client.orders.create("product-uuid")
except InsufficientBalanceError:
    print("Top up at https://hsmail.shop")
except RateLimitError:
    import time; time.sleep(60)  # Retry after 1 minute
except AuthenticationError as e:
    print(f"Auth problem: {e.code}")
except HsMailError as e:
    print(f"[{e.code}] {e} (HTTP {e.http_status})")

Publishing to PyPI

# Install build tools
pip install build twine

# Build
python -m build

# Upload to PyPI
twine upload dist/*

License

MIT © HS Mail Team