> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taimly.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Временные почты

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

## Что это

Mail API создаёт почтовые ящики и отдаёт пришедшие на них письма. Только приём — отправка не поддерживается.

Авторизация — тем же API-ключом, что и Spam Check ([подробнее](https://docs.taimly.net/authentication.md)). Ящики и письма видны только владельцу ключа.

## Как это работает

**1. Создайте ящик**

`POST /api/mail/mailboxes` — получите адрес. Тело запроса необязательно.

**2. Используйте адрес**

Зарегистрируйтесь на нужном сервисе или отправьте письмо на этот адрес.

**3. Получите письмо**

`GET /api/mail/mailboxes/{address}/wait` дождётся письма и сразу отдаст его целиком, вместе с найденным кодом подтверждения в поле `code`.

## Пример

```bash cURL theme={null}
# 1. Создать ящик
curl -X POST https://taimly.net/api/mail/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Дождаться письма (до 55 секунд)
curl "https://taimly.net/api/mail/mailboxes/anna.smith42@example.com/wait?timeout=55" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python Python theme={null}
import requests

BASE_URL = "https://taimly.net"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

box = requests.post(f"{BASE_URL}/api/mail/mailboxes", headers=HEADERS).json()
address = box["address"]
print(f"Адрес: {address}")

# ... здесь адрес используется для регистрации ...

while True:
    r = requests.get(
        f"{BASE_URL}/api/mail/mailboxes/{address}/wait",
        params={"timeout": 55, "since": box["created_at"], "from": "github.com"},
        headers=HEADERS,
        timeout=70,
    ).json()
    if r["message"]:
        break

message = r["message"]
print(message["subject"], message["code"])
```

```javascript JavaScript theme={null}
const BASE_URL = "https://taimly.net";
const HEADERS = { "Authorization": "Bearer YOUR_API_KEY" };

const box = await fetch(`${BASE_URL}/api/mail/mailboxes`, {
  method: "POST",
  headers: HEADERS
}).then(r => r.json());
console.log(`Адрес: ${box.address}`);

// ... здесь адрес используется для регистрации ...

let message = null;
while (!message) {
  const url = `${BASE_URL}/api/mail/mailboxes/${box.address}/wait?timeout=55&since=${box.created_at}&from=github.com`;
  ({ message } = await fetch(url, { headers: HEADERS }).then(r => r.json()));
}

console.log(message.subject, message.code);
```

> [!TIP]
>
> Если за `timeout` письмо не пришло, `/wait` возвращает `{"message": null}` — повторите запрос. Передавайте `since` (например, `created_at` ящика), чтобы не пропустить письмо, пришедшее между запросами: без него `/wait` ждёт только письма, пришедшие после начала запроса.

## Домены

* Список доступных доменов — [`GET /api/mail/domains`](https://docs.taimly.net/api-reference/mail/list-domains).
* `domain` при создании ящика **необязателен**. Без него домен выбирается **случайно для каждого ящика** — при нескольких доменах ящики распределяются между ними.
* Чтобы создать ящик на конкретном домене, передайте `domain`:

```json theme={null}
{ "domain": "example.com" }
```

* Домен, которого нет в списке, вернёт `400` с перечнем доступных.

## Адрес ящика

* `name` — имя до `@`. Не указано — генерируется адрес вида `anna.smith42`.
* Допустимо 1–64 символа `a-z 0-9 . _ -`, в начале и в конце — буква или цифра. Регистр не важен.
* Одно и то же имя можно занять на разных доменах.
* Письма принимаются **только на созданные ящики**. На несуществующий адрес отправитель получит отказ.

### +теги

Письма на `name+любой_тег@domain` приходят в ящик `name@domain`. Один ящик можно использовать для разных сервисов, а по полю `to` письма видно, на какой адрес оно пришло:

```json theme={null}
{ "to": "anna.smith42+github@example.com" }
```

## Код подтверждения

Поле `code` — код подтверждения, найденный в теме или тексте письма. Если кода нет или уверенности нет — `null`. Ссылки из письма API не извлекает: они есть в `text` и `html`.

## Ограничения

> [!NOTE]
>
> * **Лимитов на запросы нет** — rate limit не применяется.
> * **Количество ящиков и писем не ограничено** — ни на пользователя, ни на ящик, ни на домен.
> * Максимальный размер письма — **25 МБ**. Более крупные письма отклоняются.
> * Письма хранятся **90 дней**, затем удаляются. Ящик при этом остаётся.
> * `/wait` ждёт не дольше **55 секунд** за запрос.
> * Список писем отдаётся страницами до **200** писем (`limit`, `offset`).

## Сайт

Ящики также доступны в разделе «Временные почты» на [taimly.net](https://taimly.net). Ящики, созданные через API, не показываются там в списке, чтобы не засорять его, — их можно открыть по адресу или закрепить через [`PATCH /api/mail/mailboxes/{address}`](https://docs.taimly.net/api-reference/mail/update-mailbox).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.