← Tempmail

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/:addrttl, extend, pinned, forward_to, blocklist
GET/mailboxes/:addr/messagessince, 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/waitLong-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.