API технических ящиков
Ваш сервис просит ящик → мы даём адрес → ждём письмо → отдаём код подтверждения.
Авторизация
Ключ создаётся в почте: меню → «API и ключи». Передавайте его в каждом запросе:
Authorization: Bearer m1006_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Базовый адрес: https://1006-mail.shop/api/v1. Все ответы — JSON, ошибки — {"error": "текст"}
с HTTP-кодом 4xx.
Сценарий
| Шаг | Запрос | Что происходит |
|---|---|---|
| 1 | POST /mailboxes | Создаём ящик со случайным (смешным) именем, статус waiting. |
| 2 | — | Ваш сервис вставляет адрес в форму регистрации на нужном сайте. |
| 3 | GET /mailboxes/{id}/code?timeout=60 | Ждём письмо до 60 секунд. Ответ приходит в ту же секунду, как письмо легло в ящик. |
| 4 | POST /mailboxes/{id}/confirm | «Спасибо»: ящик сохраняется за вами в группе «API mail's». |
Если письмо не пришло за 10 минут — ящик уходит в «Черновик». Если писем нет двое суток с создания — ящик удаляется. Письмо, пришедшее в черновик, возвращает его в работу.
Запросы можно делать параллельно: 5–10 ящиков одновременно — штатный режим (до 50 ждущих ящиков на учётную запись, до 120 новых ящиков в минуту).
Методы
POST /mailboxes — новый ящик
Тело (необязательно): {"note": "для чего", "callback_url": "https://ваш-сервис/hook"}
{
"id": 42,
"address": "sleepypelmen42@1006-mail.shop",
"status": "waiting",
"created_at": 1760450000,
"draft_at": 1760450600,
"delete_at": 1760622800
}
GET /mailboxes/{id}/code — ждать код
Параметры: timeout — сколько секунд ждать (0–120, по умолчанию 60);
since — id письма, после которого искать (для второго кода передайте message_id первого).
Вместо id можно передать сам адрес ящика.
{
"status": "received",
"mailbox": "sleepypelmen42@1006-mail.shop",
"code": "860975",
"link": "https://example.com/verify?token=…",
"subject": "Your verification code",
"from": "no-reply@example.com",
"message_id": 1337,
"received_at": 1760450042
}
Не дождались — {"status": "waiting", "code": null} (или "draft"): просто повторите запрос.
Если письмо пришло, а код распознать не удалось, code будет null, но subject,
preview и message_id заполнены — полный текст отдаёт GET /messages/{message_id}.
Распознаются коды из 4–8 цифр (в том числе «123 456» и «G-482913») и буквенно-цифровые вроде «K7Q-29X» рядом со словами «код», «code», «verification», «подтверждения» и т. п.
POST /mailboxes/{id}/confirm — «спасибо»
Синоним: POST /mailboxes/{id}/thanks. Ответ: {"ok": true, "status": "saved"}.
Остальное
GET /mailboxes?status=saved&q=pelmen | список ваших API-ящиков; поиск по имени, фильтр по статусу
(waiting, received, saved, draft) |
GET /mailboxes/{id} | один ящик |
GET /mailboxes/{id}/messages | письма ящика (без тел) |
GET /messages/{id} | письмо целиком: text, html, вложения (список) |
DELETE /mailboxes/{id} | удалить API-ящик со всеми письмами |
Webhook (по желанию)
Если при создании передан callback_url, на каждое письмо мы отправим POST с JSON
{"event": "mail", "mailbox": "…", "message": {…, "code": "860975"}}. Подпись — заголовок
X-1006-Signature = HMAC-SHA256 тела, где ключ — шестнадцатеричный SHA-256 от вашего API-ключа.
Адреса во внутренних сетях не принимаются.
Пример: Python
import requests
API = "https://1006-mail.shop/api/v1"
H = {"Authorization": "Bearer m1006_…"}
box = requests.post(f"{API}/mailboxes", headers=H, json={"note": "регистрация"}).json()
print("адрес:", box["address"]) # вставляем в форму регистрации
code = None
for _ in range(10): # до 10 минут
r = requests.get(f"{API}/mailboxes/{box['id']}/code", headers=H,
params={"timeout": 60}, timeout=75).json()
if r["status"] == "received":
code = r["code"]
break
print("код:", code)
requests.post(f"{API}/mailboxes/{box['id']}/confirm", headers=H) # «спасибо»
Пример: curl
KEY=m1006_… curl -s -X POST -H "Authorization: Bearer $KEY" https://1006-mail.shop/api/v1/mailboxes curl -s -H "Authorization: Bearer $KEY" "https://1006-mail.shop/api/v1/mailboxes/42/code?timeout=60" curl -s -X POST -H "Authorization: Bearer $KEY" https://1006-mail.shop/api/v1/mailboxes/42/confirm