API v1
Базовый URL: https://mail.0ae.dev/api/v1. Формат - JSON. Спецификация: /api/openapi.json.
Аккаунты и постоянные ящики
Регистрация только по коду приглашения (POST /auth/register). Ящики аккаунта бессрочные, письма хранятся без ограничения срока, действуют квоты (число ящиков, хранилище). Анонимные временные ящики по умолчанию выключены: GET /domains показывает anonymous_enabled. В настройках аккаунта (/settings) создаются API-ключи, которые видят только ваши ящики: Authorization: Bearer tmk_... работает во всех примерах ниже вместо токена ящика, а POST /mailboxes с таким ключом создаёт постоянный ящик.
Авторизация
Authorization: Bearer <токен>. Токен ящика выдаётся при создании (один раз) и даёт доступ только к этому ящику. API-ключ (tmk_...): пользователь создаёт его в настройках (scopes mailboxes:read, mailboxes:write, webhooks) и видит только свои ящики; админ может выдать ключ автоматизации через POST /admin/keys (дополнительно scope pin для анонимных ящиков). Браузер использует HttpOnly cookie-сессию. Токены в query-строку не передаются.
Примеры
curl
# 1. создать ящик (токен показывается один раз)
curl -s -X POST https://mail.0ae.dev/api/v1/mailboxes -H 'content-type: application/json' \
-d '{"style":"readable","ttl":3600}'
# => {"address":"amber.otter42@example.com","token":"...","expires_at":...}
# 2. подождать письмо с кодом (до 60 с, 408 если не пришло)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://mail.0ae.dev/api/v1/mailboxes/$ADDR/wait?timeout=60&subject=verify"
# 3. забрать последний код
curl -s -H "Authorization: Bearer $TOKEN" https://mail.0ae.dev/api/v1/mailboxes/$ADDR/otp/latest
# => {"code":"482913","codes":["482913"],"links":[...]}
Python
import json, urllib.request
BASE = "https://mail.0ae.dev/api/v1"
def call(method, path, token=None, body=None):
req = urllib.request.Request(BASE + path, method=method,
data=json.dumps(body).encode() if body is not None else None,
headers={"content-type": "application/json", **({"authorization": f"Bearer {token}"} if token else {})})
with urllib.request.urlopen(req, timeout=70) as r:
return json.load(r)
box = call("POST", "/mailboxes", body={"ttl": 3600})
msg = call("GET", f"/mailboxes/{box['address']}/wait?timeout=60", box["token"])
print(msg["otp"], msg["links"])
# готовый клиент: client.py в репозитории
JavaScript
const BASE = "https://mail.0ae.dev/api/v1";
const api = (path, token, init = {}) =>
fetch(BASE + path, { ...init, headers: { "content-type": "application/json", ...(token && { authorization: "Bearer " + token }) } })
.then(r => r.json());
const box = await api("/mailboxes", null, { method: "POST", body: JSON.stringify({ ttl: 3600 }) });
const msg = await api(`/mailboxes/${box.address}/wait?timeout=60`, box.token);
console.log(msg.otp, msg.links);
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
| GET | /health | Проверка работоспособности |
| GET | /domains | Домены, TTL по умолчанию и максимум |
| POST | /mailboxes | Создать ящик: name, domain, style (readable|random), ttl, pinned |
| GET | /mailboxes | Список ящиков ключа (API-ключ) |
| GET DELETE | /mailboxes/:addr | Инфо / удалить ящик |
| PATCH | /mailboxes/:addr | ttl, extend, pinned, forward_to, blocklist |
| GET | /mailboxes/:addr/messages | since, from, subject, q, unread, limit |
| GET PATCH DELETE | /mailboxes/:addr/messages/:id | Письмо; read=true|false; удалить |
| GET | /mailboxes/:addr/messages/:id/raw | Исходник .eml |
| GET | /mailboxes/:addr/messages/:id/attachments/:n | Вложение |
| GET | /mailboxes/:addr/wait | Long-poll: timeout (1-60), since, from, subject |
| GET | /mailboxes/:addr/otp/latest | Последний код и ссылки подтверждения |
| GET POST DELETE | /mailboxes/:addr/webhooks[/:id] | Вебхуки ящика |
| GET POST DELETE | /webhooks[/:id] | Вебхуки на все ящики API-ключа (scope webhooks) |
| POST | /auth/register /auth/login /auth/logout /auth/password | Аккаунт: регистрация по инвайту, вход (cookie-сессия), выход, смена пароля |
| GET | /auth/me | Текущий пользователь, использование, лимиты |
| GET POST DELETE | /account/keys[/:id] | Ваши API-ключи (доступ только к вашим ящикам) |
| GET POST DELETE | /account/webhooks[/:id] | Вебхуки на все ваши ящики |
| GET POST DELETE | /account/invites[/:id] | Приглашения (если админ разрешил) |
| GET | /admin/stats /admin/users /admin/invites /admin/mailboxes /admin/settings /admin/audit | Админ-API (роль admin) |
| PATCH DELETE POST | /admin/users/:id[/reset-password] | Блок, роль, квоты, сброс пароля, удаление |
| POST GET DELETE | /admin/keys[/:id] | Ключи автоматизации (ADMIN_KEY / админ) |
Вебхуки
При новом письме на URL (только https) отправляется POST с JSON {event, mailbox, message}. Неудачные доставки повторяются по расписанию cron (всего 5 попыток).
# заголовки: X-Tempmail-Timestamp, X-Tempmail-Signature: sha256=<hex>
# подпись = HMAC_SHA256(secret, timestamp + "." + raw_body)
import hmac, hashlib
ok = hmac.compare_digest("sha256=" + hmac.new(secret, f"{ts}.".encode() + body, hashlib.sha256).hexdigest(), sig)
Пересылка и блоклист
PATCH с forward_to включает пересылку через message.forward(): адрес должен быть подтверждён в Cloudflare Email Routing (Destination addresses). Блоклист: {"blocklist":["spam@x.com","@bad.org"]} - письма от таких отправителей отклоняются на SMTP-уровне.
Ошибки и лимиты
Ошибки: {"error":"..."} с кодом 4xx/5xx. Анонимное создание ящика (если включено): 10 в час с IP; вход: блокировка на 15 минут после 5 неудачных попыток. Письма больше лимита (по умолчанию 5 МБ) отклоняются. /wait возвращает 408, если письмо не пришло за timeout.