Email account API

The stock endpoint is public and needs no key

GET https://api.xmailhub.net/stock takes no key, no header and no account. That is deliberate, and it is the endpoint to start with. The response looks like this: {"status":"success","code":200,"data":[{"Name":"Hotmail Fresh","Price":"0.004","Stock":34},{"Name":"Outlook Trusted","Price":"0.040","Stock":17}]}. Price is a string, not a number, so parse it rather than assuming a float, and Stock is an integer that moves constantly as other buyers take accounts. Two honest notes. First, the data array lists product names, not the product codes you pass to the purchase endpoint, so the mapping table above is where those codes live. Second, the count is read live at request time rather than from a long cache, which is why a product can read 34 on one call and 0 on the next. Poll it right before you buy, not once at the start of a long job.

Getting an API key and funding a balance

Your API key is in your account dashboard, on the API page, and it is generated for you when you register. There is no application form and no approval step. You can rotate it from the same page whenever you want, which is worth doing if a key has been sitting in an old script or a shared config for a while, since rotation costs you one deploy and a leaked key costs you your balance. The key authenticates in three interchangeable ways: as a path segment, as ?apiKey= in the query string, or as an X-API-Key header. All three hit the same handler. Money works the same way for the API as for the store. You fund a prepaid balance with cryptocurrency through Plisio, which takes USDT on TRC20, Litecoin and Tron, and every purchase call debits that balance. Read the current figure with GET /balance/YOUR_KEY, which returns code, balance as a string, and date formatted as dd/mm/yyyy HH:MM:SS.

Buying accounts: /purchase/KEY/CODE/QUANTITY

A purchase is one request: GET https://api.xmailhub.net/purchase/YOUR_KEY/Hotmail/10 buys ten fresh Hotmail accounts. CODE is the product's API code, and there are four live ones: Hotmail, Outlook, Hotmail_Trusted and Outlook_Trusted. Matching is case-insensitive, so hotmail_trusted works. The Account field in the /stock response gives you the code for every product, so you do not have to hard-code this list. Quantity runs from 1 to 100,000 per order, and the unit price never changes with volume, so ten thousand fresh Hotmail costs ten thousand times $0.004. Yes, a mutating call over GET is unusual, and no, we are not going to pretend otherwise. It exists because the old system's URLs looked exactly like this and thousands of working scripts point at them; changing the verb would have broken every one of them to satisfy a convention. Treat the consequences seriously: this URL spends real money, so keep it out of anything that retries blindly, prefetches links, or writes full URLs to a shared log.

What the purchase response returns

A successful purchase returns status, code, message, purchase_id, balance, price and a data array with one object per account. Each object has Email, Password, AccessToken, RefreshToken and ClientId. Those last three are the OAuth2 fields that let you reach the mailbox over IMAP or Microsoft Graph without touching the interactive web login, which is where Microsoft tends to ask for a phone number. AccessToken comes back as "-" when an account has no token stored, so check for that before feeding it to a mail library. balance is your remaining balance after the debit and price is the unit price you actually paid, both as strings. purchase_id is the order reference, and it is the one field worth writing down: it identifies the order to support if an account will not log in. The credentials also stay in your order history, so a script that dies after the response has been sent has not lost the accounts.

Reading a mailbox: /mailreader and /mailinfo

Two endpoints work on accounts you already own. GET /mailreader/[email protected] reads the inbox and returns code, message and a data object holding email_address plus the messages the upstream reader found, each carrying the date, sender_email, sender_name, subject, message, folder and id. Append &html to get raw HTML bodies instead of cleaned text. GET /mailinfo/[email protected] returns the stored credentials for one account: mail, password, accessToken, refreshToken and clientId. Both check ownership against your order history, so an address you did not buy returns 400 with the key publicapi.invalid_mail rather than leaking anything. Both also require the mail parameter; without it you get 400 and the key publicapi.missing_params. Reading depends on an upstream mail service, so if that service is unreachable the call returns 503 rather than an empty inbox. Treat 503 as retry later, not as no mail.

Errors, status codes and the quirks worth knowing

Error bodies carry success: false, a machine-readable code, and both messageKey and messageText, the latter translated by your Accept-Language header or ?lang=. A missing key returns 401 with code API_KEY_MISSING, an invalid one returns 401 with API_KEY_INVALID, and a key belonging to a suspended account returns 403 with ACCOUNT_INACTIVE. Do not lump those together: 401 means fix your key, 403 means talk to support, and neither is worth retrying. An unknown product code returns 404. Asking for more than the supplier has returns 400 with INSUFFICIENT_STOCK, and the message tells you how many are actually available, so a script can lower the quantity and try again. A quantity outside 1 to 100,000 returns 400 QUANTITY_OUT_OF_RANGE, an empty balance returns 400 INSUFFICIENT_BALANCE. Two genuine oddities: calling /purchase with the query format and no code or quantity returns HTTP 400 with a body that says code: 403, and during maintenance every endpoint returns 503 with code: 999.

Two URL formats, and old scripts

Every endpoint answers on two shapes at once. The legacy path format puts the key in the URL: /balance/KEY, /purchase/KEY/CODE/QUANTITY, /mailinfo/KEY?mail=..., /mailreader/KEY?mail=.... The query format keeps the path clean: /balance?apiKey=KEY, /purchase?apiKey=KEY&code=Hotmail&quantity=10. Both reach the same handler and return the same body, and a third option, the X-API-Key header, works on either. This is not a deprecation with a countdown attached. Both formats are live side by side with no cutover date, which is why a script written years ago against the old PHP subdomain keeps running: point it at https://api.xmailhub.net, keep the key, done. If you are writing something new, prefer the header. Keys in URLs end up in access logs, browser history, proxy caches and the referrer of any page you fetch afterwards, and none of those are places you want a key that spends money.

Frequently asked questions