API documentation
REST API for buying mailboxes and reading mail. All responses are JSON. Create a key in your account and send it in the X-API-KEY header. Default limit is 10 requests per second per key. Money is in integer kopecks.
Quick start
curl https://mailwave.net/v1/balance -H "X-API-KEY: rk_live_..."
# buy 100 mailboxes (Idempotency-Key protects from double purchase on retry)
curl -X POST https://mailwave.net/v1/mailboxes \
-H "X-API-KEY: rk_live_..." -H "Idempotency-Key: order-0001" \
-H "Content-Type: application/json" \
-d '{"count": 100, "tariff": "standard"}'
# get the code from a message (wait up to 60 seconds)
curl "https://mailwave.net/v1/mailboxes/[email protected]/code?wait=60" -H "X-API-KEY: rk_live_..."
Endpoints
| Method | URL | What it does |
|---|---|---|
GET | /v1/ping | Availability check (no key) |
GET | /v1/catalog | Plans and prices in kopecks |
GET | /v1/balance | Balance and recent transactions |
GET | /v1/capacity | How many mailboxes can be issued now |
POST | /v1/mailboxes | Buy a batch: count (up to 1000), tariff, password_format. Header Idempotency-Key. |
GET | /v1/orders | Your orders |
GET | /v1/mailboxes/{address}/messages | Mailbox messages (folder, limit); all folders by default, including Spam |
GET | /v1/mailboxes/{address}/code | Latest code or link; wait — wait up to 120 s; service — filter |
GET | /v1/mailboxes/{address}/alive | Is the mailbox alive (login works) |
POST | /v1/mailboxes/{address}/password | Change password (new_password or random) |
POST | /v1/mailboxes/{address}/address | Change the address itself (new_local_part or random) |
GET POST DELETE | /v1/webhooks | Notifications about new mail to your URL |
Purchase response
{
"order_id": 57, "status": "done", "requested": 100, "created": 100,
"repeated": false, "price_kop": 1000, "balance_kop": 99000,
"mailboxes": [{"address": "[email protected]", "password": "Xk3...9"}, ...]
}
Passwords are returned once, on the first purchase. A retry with the same Idempotency-Key returns the same order with "repeated": true and addresses without passwords. You can always download passwords in your account.
Errors
{"error": {"code": "insufficient_funds", "message": "..."}}
Main codes: 401 invalid_api_key, 402 insufficient_funds, 404 mailbox_not_found (someone else's mailbox is also 404), 404 code_not_found, 409 pool_exhausted, 429 rate_limited, 503 sales_closed.
IMAP
Any mail client or library: server mail.mailwave.net, port 993 (SSL/TLS), login is the full mailbox address, password as issued. Unencrypted connections are closed.
import imaplib
M = imaplib.IMAP4_SSL("mail.mailwave.net", 993)
M.login("[email protected]", "password")
M.select("INBOX")
Webhooks
Subscribe with POST /v1/webhooks and a url — we POST the message data signed with a secret shown once on creation.