● RESELLER API · v1

Reseller API Documentation

Fetch products, stock and prices; buy automatically from your own software or SMM panel. Prices, stock and rules are exactly the same as on the site; purchases are paid from your balance.

Getting started

Sign up and add funds. Requirement: a balance of at least 10 USD. The balance is not locked; you can keep spending it as usual.
Apply under My Account → API. Approval usually takes less than 24 hours.
After approval, create a key on the same tab (up to 5). The key is shown only once; store it safely.

Base URL: https://kingofmail.com/api/v1 · Currency: USD

Authentication

Send your key in the X-API-Key header on every request. Keys start with kom_.

curl https://kingofmail.com/api/v1/user/balance \
  -H "X-API-Key: kom_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Never use the key in a browser or client-side code; call the API from your server only. If you suspect a leak, delete it under My Account → API and create a new one.

Response format

Every response has success. On success the payload is in data; on failure you get a machine-readable error_code and a human-readable message. Branch on error_code, never on the wording of message. Money values are strings with two decimals ("1.50").

{ "success": true, "data": { ... }, "meta": { ... } }
{ "success": false, "error_code": "insufficient_balance", "message": "..." }

GET/api/v1/user/balance

{ "success": true, "data": { "balance": "125.40", "currency": "USD" } }

Products

GET/api/v1/products

PARAMETER	DESCRIPTION
`category`	Optional: `gmail` · `hotmail` · `outlook` · `other`
`in_stock`	`1` = only purchasable products
`page`	Page (50 products each)

{
  "success": true,
  "data": [
    {
      "id": 421, "category": "gmail", "title": "...", "description": "...", "region": "ABD",
      "tags": ["2FA ...", "..."], "price": "1.60", "currency": "USD", "stock": 64,
      "delivery": "instant", "min_quantity": 1, "max_quantity": 5000
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 223, "last_page": 5 }
}

delivery: instant = delivered immediately · preorder = delivered within 0–3 hours (pre-order, during support hours) · notify = not purchasable right now. price is per unit; 10% off is applied automatically on 250+ units. Stock and prices are live; the purchase response is authoritative.

GET/api/v1/products/{id}

A single product; same fields as in the list.

Purchase

POST/api/v1/purchase

FIELD	DESCRIPTION
`product_id`	Required. Product id.
`quantity`	Required. 1–5000.
`client_reference`	Recommended. A UUID you generate. A retry with the same value is never charged twice; the original order is returned with `"replayed": true`.

curl -X POST https://kingofmail.com/api/v1/purchase \
  -H "X-API-Key: kom_..." -H "Content-Type: application/json" \
  -d '{"product_id": 421, "quantity": 2, "client_reference": "3f8a1c22-9e4b-4f2a-bd51-0c7e5a9d1234"}'

201
{
  "success": true,
  "data": {
    "order_id": 1052, "status": "completed", "product_id": 421, "product": "...", "quantity": 2,
    "unit_price": "1.60", "discount": "0.00", "total_price": "3.20", "currency": "USD",
    "accounts": ["[email protected]:password1", "[email protected]:password2"],
    "new_balance": "122.20"
  }
}

status: completed = accounts are in accounts · processing = being fetched from the supplier (usually seconds) · waiting = pre-order (until deadline_at) · review = being checked · failed/refunded = amount refunded to your balance.
If not completed, poll GET /api/v1/orders/{id} every few seconds.
The account line format depends on the product (usually email:password, some include extra fields). See the product description.
Remaining stock rule: you cannot leave 1–4 units of a product; when 5 or fewer remain, buy them all.
If the connection drops or times out, retry safely with the same client_reference. Error responses (4xx/5xx) mean you were not charged.

Orders

GET/api/v1/orders?page=1&per_page=20

Your orders, newest first (including those placed on the site; via: web or api). Accounts are not included here. per_page max 100.

GET/api/v1/orders/{id}

A single order; accounts is filled once delivered. Same fields as the purchase response.

Errors

HTTP	error_code	MEANING
401	`invalid_key`	Missing, unknown, revoked or expired key, or API access disabled
403	`wrong_site`	The account does not belong to this site
422	`validation_failed`	Invalid field (product, quantity, client_reference)
404	`product_not_found`	Product does not exist or is not on sale
400	`insufficient_balance`	Insufficient balance
400	`insufficient_stock`	Not enough stock (the message includes the available amount)
400	`order_rejected`	Other rule violations (remaining stock rule, minimum quantity, etc.)
409	`price_changed`	Price was updated; fetch the product again and retry
409	`request_in_progress`	A request with the same client_reference is still being processed
503	`temporarily_unavailable`	Product temporarily unavailable, or pre-order outside support hours
404	`order_not_found`	Order does not exist or is not yours
429	`rate_limit_exceeded`	Rate limit exceeded; wait for `Retry-After`

Limits

All requests: 240 per minute · Product listing: 60 per minute · Purchases: 30 per minute (per account, shared by all keys).
Cache the product list (refreshing every few minutes is enough); the final stock/price check happens at purchase time.

SMM panel compatible endpoint (v2)

You can add us to your SMM panel as an "API provider". URL: https://kingofmail.com/api/v2 · Requests are POST, form or JSON; the key goes in the key field.

action	PARAMETERS	RESPONSE
`balance`	—	`{"balance":"125.40","currency":"USD"}`
`services`	—	Product list: `service, name, category, rate, min, max`. `rate` is the price per 1000 (SMM standard).
`add`	`service, quantity` (`link` is ignored)	`{"order":1052}`
`status`	`order` or `orders`=1,2,3 (max 100)	`{"charge":"3.20","start_count":"0","status":"Completed","remains":"0","currency":"USD"}`
`accounts`	`order`	Delivered accounts: `{"status":"Completed","accounts":["..."]}`

Statuses: Completed, In progress, Pending (pre-order), Canceled (refunded). Errors look like {"error":"..."}. v2 has no retry protection (client_reference); if the connection drops, check with status first.

curl -X POST https://kingofmail.com/api/v2 -d "key=kom_..." -d "action=add" -d "service=421" -d "quantity=10"

Support

For integration questions, reach us via the contact page; please include the order_id.