Для разработчиков

API временной почты

Создавайте ящики и читайте письма из кода: для автотестов регистрации, проверки рассылок и подтверждений по почте.

Авторизация

Каждый запрос подписывается ключом в заголовке Authorization. Ключ выдаётся на платных тарифах.

Authorization: Bearer um_YOUR_KEY

Базовый адрес

https://urusmail.pro/api/v1

Быстрый старт

Создайте ящик
Дождитесь письма (запрос сам подождёт до 30 секунд)
Прочитайте письмо: текст, код подтверждения и ссылки

# 1. create an inbox
curl -X POST https://urusmail.pro/api/v1/inboxes \
  -H "Authorization: Bearer um_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes": 60}'
# -> {"inbox":{"id":123,"email":"swift.fox1234@urusmail.pro","expires_at":"..."}}

# 2. wait for a message (up to 30 s)
curl "https://urusmail.pro/api/v1/inboxes/123/messages?wait=30" \
  -H "Authorization: Bearer um_YOUR_KEY"
# -> {"messages":[{"id":456,"subject":"Your code","code":"482910", ...}]}

# 3. read the full message
curl https://urusmail.pro/api/v1/inboxes/123/messages/456 \
  -H "Authorization: Bearer um_YOUR_KEY"

const API = "https://urusmail.pro/api/v1";
const headers = { Authorization: "Bearer " + process.env.URUSMAIL_KEY, "Content-Type": "application/json" };

// create an inbox for one test
const { inbox } = await (await fetch(API + "/inboxes", { method: "POST", headers, body: JSON.stringify({ ttl_minutes: 30 }) })).json();

// ... your app sends a confirmation email to inbox.email ...

// wait for the email and take the code
let code = null;
for (let i = 0; i < 4 && !code; i++) {
  const { messages } = await (await fetch(`${API}/inboxes/${inbox.id}/messages?wait=30`, { headers })).json();
  code = messages[0]?.code ?? null;
}
console.log(inbox.email, code);

await fetch(`${API}/inboxes/${inbox.id}`, { method: "DELETE", headers });

Методы

GET	/me	Тариф, лимиты и текущее использование
GET	/domains	Домены, на которых можно создавать ящики
POST	/inboxes	Создать ящик. Тело: name, domain, ttl_minutes (всё необязательно)
GET	/inboxes	Список ваших ящиков
GET	/inboxes/{id}	Один ящик
DELETE	/inboxes/{id}	Удалить ящик вместе с письмами
GET	/messages	Все письма аккаунта одним списком. Параметры: inbox_id, since_id, limit (до 100)
GET	/inboxes/{id}/messages	Письма ящика. Параметры: since_id, wait (0–30 секунд)
GET	/inboxes/{id}/messages/{mid}	Письмо целиком: text, html, code, links
DELETE	/inboxes/{id}/messages/{mid}	Удалить письмо
GET	/custom-domains	Ваши домены и нужные DNS-записи
POST	/custom-domains	Добавить домен. Тело: domain, catch_all
POST	/custom-domains/{id}/verify	Проверить DNS-записи и включить приём почты
PATCH	/custom-domains/{id}	Включить или выключить catch_all
DELETE	/custom-domains/{id}	Удалить домен и его ящики

Что приходит в письме

code	Код подтверждения, если он найден рядом со словами «код», «code», «verification» и т. п.; иначе null
text	Текст письма. Если письмо только в HTML, текст собирается из него без стилей
html	Исходный HTML письма (показывайте его только в изолированной рамке)
links	Ссылки из письма, до 50 штук

Свой домен

Добавьте домен методом POST /custom-domains. В ответе будут две DNS-записи.
Создайте у регистратора TXT-запись с кодом подтверждения и MX-запись на mail.urusmail.pro.
Вызовите /verify. Когда обе записи найдены, домен появится в GET /domains и на нём можно создавать ящики.
С catch_all письмо на любой адрес домена само создаёт ящик, если тариф позволяет.

Ошибки и лимиты

401	Нет ключа или ключ неверный
403	Ключ отключён или срок истёк
404	Ящик, письмо или домен не найден (или принадлежит не вам)
409	Достигнут лимит тарифа или адрес занят
429	Превышен лимит запросов в минуту. Повторите позже (заголовок Retry-After)

Ошибка всегда приходит в одном виде:

{ "error": { "code": "inbox_limit", "message": "Inbox limit reached (10). Delete an inbox or upgrade the plan" } }

Одновременно ждать письмо (wait) могут не больше трёх запросов на ключ. В ящике хранятся последние 200 писем.

Тарифы и получение ключа