hsmail-sdk 1.0.0

Official Python SDK for the HS Mail API

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(["[e-mail]", ...], "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})")

Exception	When raised
AuthenticationError	Invalid/expired API key, banned account
RateLimitError	>100 requests/minute
NotFoundError	Resource not found
InsufficientBalanceError	Not enough BDT balance
ValidationError	Bad input, out of stock, closed order
HsMailError	All other errors

---

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