README

Official PHP SDK for the HS Mail API — manage orders, read mailboxes, check live accounts, and generate 2FA codes with a clean, typed interface.

Requirements

• PHP 8.0 or higher
• Composer

Installation

composer require hsmail/hsmail-sdk

Quick Start

<?php
require_once 'vendor/autoload.php';

use HsMail\HsMailClient;

$client = new HsMailClient('YOUR_API_KEY');

// Check API is reachable
$status = $client->ping();
echo "Your IP: " . $status['ip'];

// Get your profile
$profile = $client->getProfile();
echo "Balance: " . $profile['balance'] . " BDT";

// List all products
$products = $client->products()->list();

// Place an order
$order = $client->orders()->create('product-uuid', 1);
echo "Order ID: " . $order['orderId'];

Authentication

Get your API key from your HS Mail Dashboard.

Pass it to the constructor:

$client = new HsMailClient('hs_live_xxxxxxxxxxxxxxxxxxx');

The SDK automatically sends it as a Bearer token:

Authorization: Bearer hs_live_xxxxxxxxxxxxxxxxxxx

API Reference

Profile & Status

// Ping the API
$ping = $client->ping();
// { status, message, ip, timestamp }

// Get your profile
$profile = $client->getProfile();
// { id, name, email, balance, rankLevel, ... }

Products

// List all products (organised by category)
$categories = $client->products()->list();
foreach ($categories as $cat) {
    foreach ($cat['products'] as $p) {
        echo $p['name'] . ' — ' . $p['price'] . ' BDT';
    }
}

// Get a single product by UUID
$product = $client->products()->get('product-uuid');

Orders

// Create an order
$order = $client->orders()->create('product-uuid', 1);
// Returns: { orderId, productName, status, isService, totalCost, items[] }

// Get order details
$details = $client->orders()->get('ORDER_ID');

// Get messages for a service order
$chat = $client->orders()->messages('ORDER_ID');

// Send a message on a service order
$client->orders()->sendMessage('ORDER_ID', 'Please process ASAP');

// Reopen an order under warranty
$client->orders()->reopen('ORDER_ID');

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

Mailbox

Outlook / Hotmail

// Read inbox messages
$inbox = $client->mailbox()->readOutlook(
    'user@hotmail.com',
    'REFRESH_TOKEN',
    'CLIENT_ID',
    'graph'  // 'graph' or 'oauth2'
);

// Refresh OAuth token
$tokens = $client->mailbox()->refreshOutlookToken('CLIENT_ID', 'REFRESH_TOKEN');
echo $tokens['accessToken'];

// Check if account is live
$check = $client->mailbox()->checkOutlook('user@hotmail.com', 'REFRESH_TOKEN', 'CLIENT_ID');
echo $check['accountStatus']; // 'Live' or 'Die'

Gmail

// Read Gmail (requires GMAIL subscription)
$gmail = $client->mailbox()->readGmail('user@gmail.com', 'ORDER_ID');

// Check Gmail account status (requires GMAIL subscription)
$status = $client->mailbox()->checkGmail('user@gmail.com');
echo $status['accountStatus']; // 'LIVE' or 'DEAD'

Facebook & Instagram

// Bulk Facebook live check (requires FB subscription)
$results = $client->mailbox()->checkFacebookBulk([
    'email1@gmail.com:password1',
    'email2@gmail.com:password2',
]);
echo "Live: " . $results['liveCount'];

// Single Facebook check
$fb = $client->mailbox()->checkFacebook('FACEBOOK_USER_ID');

// Instagram check
$ig = $client->mailbox()->checkInstagram('username');
echo $ig['accountStatus']; // 'LIVE' or 'DEAD'

Hotmail Creator

$result = $client->mailbox()->createHotmailOrder(
    ['user1@hotmail.com', 'user2@hotmail.com'],
    'USER_ONLY' // or 'USER_PASS'
);
echo "Order ID: " . $result['orderId'];

Tools

// Generate a TOTP 2FA code
$result = $client->tools()->generate2fa('JBSWY3DPEHPK3PXP');
echo "Code: " . $result['code'] . " (expires in " . $result['timeRemaining'] . "s)";

Error Handling

All errors throw typed exceptions inheriting from HsMailException:

use HsMail\Exceptions\{HsMailException, InsufficientBalanceException, RateLimitException};

try {
    $order = $client->orders()->create('product-uuid', 5);
} catch (InsufficientBalanceException $e) {
    echo "Need more balance! Top up at https://hsmail.shop";
} catch (RateLimitException $e) {
    sleep(60);  // Wait and retry
} catch (HsMailException $e) {
    echo "[{$e->getErrorCode()}] {$e->getMessage()} (HTTP {$e->getHttpStatus()})";
    // Full response data:
    print_r($e->getResponseData());
}

Rate Limits

• 100 requests per minute per API key
• On RateLimitException, wait ~60 seconds and retry

Publishing to Packagist

1. Push this SDK to a public GitHub repository
2. Log in to packagist.org and click Submit
3. Enter your GitHub repository URL
4. Enable auto-update via a GitHub webhook (Settings → Webhooks → https://packagist.org/api/github?username=YOUR_USERNAME)

License

MIT © HS Mail Team