PHP SDK

Official PHP 8.0+ client library for the HS Mail API. Built on Guzzle HTTP with typed exceptions.

PHP ^8.0Guzzle ^7.0MIT LicensePackagist

Installation

bash

composer require hsmail/hsmail-sdk

Requires PHP 8.0+ and Composer.

Quick Start

php

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

use HsMail\HsMailClient;

$client = new HsMailClient('YOUR_API_KEY');

// Ping the API
$ping = $client->ping();
echo "Your IP: " . $ping['ip'];

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

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

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

Authentication

Get your API key from the HS Mail Dashboard.

php

$client = new HsMailClient(
    'hs_live_xxxxxxxxxxxxxxx',         // Your API key
    'https://api.hsmail.shop'          // Optional: override base URL
);

API Reference

Products

php

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

foreach ($categories as $cat) {
    foreach ($cat['products'] as $p) {
        echo $p['name'] . ' — ' . $p['price'] . ' BDT';
    }
}

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

Orders

php

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

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

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

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

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

Mailbox

php

// Read Outlook inbox
$inbox = $client->mailbox()->readOutlook($email, $refreshToken, $clientId);

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

// Check Outlook account status
$check = $client->mailbox()->checkOutlook($email, $refreshToken, $clientId);
echo $check['accountStatus']; // 'Live' or 'Die'

// Read Gmail (requires GMAIL subscription)
$gmail = $client->mailbox()->readGmail($email, $orderId);

// Check Gmail status
$status = $client->mailbox()->checkGmail($email);

// Bulk Facebook live check (requires FB subscription)
$fb = $client->mailbox()->checkFacebookBulk([$account1, $account2]);
echo "Live: " . $fb['liveCount'];

// Single Facebook check
$single = $client->mailbox()->checkFacebook('FB_USER_ID');

// Instagram check (requires IG subscription)
$ig = $client->mailbox()->checkInstagram('username');

// Bulk Hotmail Creator
$created = $client->mailbox()->createHotmailOrder(
    ['user@hotmail.com'],
    'USER_ONLY'
);

Tools

php

$result = $client->tools()->generate2fa('JBSWY3DPEHPK3PXP');
echo "Code: " . $result['code'] . " — valid for " . $result['timeRemaining'] . "s";

Error Handling

php

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

try {
    $order = $client->orders()->create('product-uuid', 1);
} catch (InsufficientBalanceException $e) {
    echo "Top up at https://hsmail.shop";
} catch (RateLimitException $e) {
    sleep(60); // Wait and retry
} catch (AuthenticationException $e) {
    echo "Auth problem: " . $e->getErrorCode();
} catch (HsMailException $e) {
    echo "[{$e->getErrorCode()}] {$e->getMessage()} (HTTP {$e->getHttpStatus()})";
    print_r($e->getResponseData());
}

Exception	Trigger
AuthenticationException	Invalid key, banned/suspended account
RateLimitException	>100 requests/minute
NotFoundException	Resource doesn't exist
InsufficientBalanceException	Not enough BDT balance
ValidationException	Invalid input, out of stock, closed order
HsMailException	Base — all other API errors

Publishing to Packagist

Push the sdk/php folder to a public GitHub repository
Log in to packagist.org and click Submit
Enter your GitHub repository URL
Enable auto-update: Settings → Webhooks → https://packagist.org/api/github