Документация API
REST API для покупки ящиков и чтения писем. Все ответы — JSON. Ключ создаётся в кабинете и передаётся в заголовке X-API-KEY. Лимит по умолчанию — 10 запросов в секунду на ключ. Деньги — целые копейки.
Быстрый старт
curl https://mailwave.net/v1/balance -H "X-API-KEY: rk_live_..."
# купить 100 ящиков (Idempotency-Key защищает от двойной покупки при повторе запроса)
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"}'
# получить код из письма (ждать до 60 секунд)
curl "https://mailwave.net/v1/mailboxes/[email protected]/code?wait=60" -H "X-API-KEY: rk_live_..."
Методы
| Метод | URL | Что делает |
|---|---|---|
GET | /v1/ping | Проверка доступности (без ключа) |
GET | /v1/catalog | Тарифы и цены в копейках |
GET | /v1/balance | Баланс и последние операции |
GET | /v1/capacity | Сколько ящиков можно выдать сейчас |
POST | /v1/mailboxes | Купить партию: count (до 1000), tariff, password_format. Заголовок Idempotency-Key. |
GET | /v1/orders | Ваши заказы |
GET | /v1/mailboxes/{address}/messages | Письма ящика (folder, limit); по умолчанию все папки, включая «Спам» |
GET | /v1/mailboxes/{address}/code | Последний код или ссылка; wait — ждать письмо до 120 с; service — фильтр |
GET | /v1/mailboxes/{address}/alive | Жив ли ящик (вход проходит) |
POST | /v1/mailboxes/{address}/password | Сменить пароль (new_password или случайный) |
POST | /v1/mailboxes/{address}/address | Сменить сам адрес (new_local_part или случайный) |
GET POST DELETE | /v1/webhooks | Уведомления о новых письмах на ваш URL |
Ответ на покупку
{
"order_id": 57, "status": "done", "requested": 100, "created": 100,
"repeated": false, "price_kop": 1000, "balance_kop": 99000,
"mailboxes": [{"address": "[email protected]", "password": "Xk3...9"}, ...]
}
Пароли возвращаются один раз, при первой покупке. Повтор с тем же Idempotency-Key вернёт тот же заказ с "repeated": true и адресами без паролей. Пароли всегда можно скачать в кабинете.
Ошибки
{"error": {"code": "insufficient_funds", "message": "..."}}
Основные коды: 401 invalid_api_key, 402 insufficient_funds, 404 mailbox_not_found (чужой ящик тоже 404), 404 code_not_found, 409 pool_exhausted, 429 rate_limited, 503 sales_closed.
IMAP
Любой почтовый клиент или библиотека: сервер mail.mailwave.net, порт 993 (SSL/TLS), логин — полный адрес ящика, пароль — выданный. Подключения без шифрования закрыты.
import imaplib
M = imaplib.IMAP4_SSL("mail.mailwave.net", 993)
M.login("[email protected]", "password")
M.select("INBOX")
Вебхуки
Подпишитесь методом POST /v1/webhooks с адресом url — мы будем присылать POST с данными письма и подписью секретом, который показывается один раз при создании.