API временной почты и MCP-сервер для тестов и ИИ-агентов

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

Создайте ящик, дождитесь следующего письма, прочитайте его и удалите ящик. Храните API-ключ в TEMPGENERATOR_TOKEN и никогда не передавайте его в URL.

Нужны curl и jq. Скрипт до трёх раз ждёт письмо по 20 секунд, выводит тему, коды, ссылки и текст каждого письма, а затем удаляет ящик.

export TEMPGENERATOR_URL='https://www.tempgenerator.com'
API="$TEMPGENERATOR_URL/developer-api/v1"
AUTH="Authorization: Bearer $TEMPGENERATOR_TOKEN"
INBOX=$(curl --fail-with-body -sS -X POST "$API/inboxes" -H "$AUTH" -H 'Accept: application/json')
ID=$(printf '%s' "$INBOX" | jq -r .id)
echo "Send a test email to $(printf '%s' "$INBOX" | jq -r .address)"
for ATTEMPT in 1 2 3; do
  RESULT=$(curl --fail-with-body -sS "$API/inboxes/$ID/wait?after=0&timeout=20" -H "$AUTH" -H 'Accept: application/json')
  [ "$(printf '%s' "$RESULT" | jq -r .status)" = message ] && break
done
for MESSAGE in $(printf '%s' "$RESULT" | jq -r '.messages[].id'); do
  curl --fail-with-body -sS "$API/inboxes/$ID/messages/$MESSAGE" -H "$AUTH" -H 'Accept: application/json' \
    | jq '{subject, codes, links, text}'
done
curl --fail-with-body -sS -X DELETE "$API/inboxes/$ID" -H "$AUTH"

Обзор API

Базовый URL: https://www.tempgenerator.com/developer-api/v1. Передавайте Authorization: Bearer <key> в каждом запросе. Ответы приходят в формате JSON; ошибки имеют вид {"error": {"code", "message", "retry_after"}}, а при ошибках квоты дополнительно отправляется заголовок Retry-After.

• POST /inboxes Создать ящик и получить его адрес и срок действия
• GET /inboxes/{id}/wait?after=0&timeout=20 Ждать следующее письмо после курсора до 20 секунд
• GET /inboxes/{id}/messages?after=0 Получить до 50 писем после курсора, сначала самые старые
• GET /inboxes/{id}/messages/{message_id} Прочитать письмо: текст, коды, ссылки и список вложений
• GET /inboxes/{id}/messages/{message_id}/attachments/{index} Скачать вложение по его индексу
• DELETE /inboxes/{id} Сразу удалить ящик и его письма

Список и ожидание принимают необязательные фильтры from и subject_contains: поиск по вхождению в отправителе и теме без учёта регистра.

Пример ответа при чтении письма

{
    "id": 42,
    "from": "no-reply@app.example",
    "subject": "Your verification code",
    "received_at": "2026-10-03T09:41:07+00:00",
    "text": "Your verification code is 482913.\nOr confirm: https://app.example/verify?token=8f3c",
    "text_truncated": false,
    "codes": [
        "482913"
    ],
    "links": [
        "https://app.example/verify?token=8f3c"
    ],
    "expires_at": "2026-10-03T10:40:12+00:00",
    "attachments": [
        {
            "index": 0,
            "filename": "receipt.pdf",
            "size": 48213
        }
    ],
    "untrusted_content": true
}

Токены разработчика

После подтверждения почты создавайте API-ключи в разделе «Доступ разработчика». Ключ с правами на чтение и запись может создавать, читать и удалять ящики; ключ только для чтения — получать список, ждать, читать и скачивать. Ключи действуют 90 дней, у аккаунта может быть до 10 активных ключей, а отзыв ключа вступает в силу сразу.

Каждый ключ показывается один раз и хранится только в виде хеша SHA-256. Отзыв ключа не удаляет его ящики: другие действующие ключи аккаунта сохраняют к ним доступ, пока ящики не истекут или не будут удалены.

Ожидание следующего письма без sleep()

GET …/wait держит запрос открытым и отвечает, как только приходит письмо, или по истечении тайм-аута (не более 20 секунд) — тогда в ответе будет status timeout. Передайте next_cursor из предыдущего ответа как after, чтобы не прочитать одно и то же письмо дважды.

Тайм-аут — не ошибка доставки: просто снова ждите с тем же курсором. Для одного ящика выполняется одно ожидание, и новое ожидание того же ящика заменяет предыдущее; ожидания разных ящиков выполняются параллельно, не более 2 одновременно на аккаунт.

Тестирование email в Playwright, Cypress, pytest и CI

Дайте каждому тесту собственный ящик, запустите в своём приложении отправку письма о регистрации или сбросе пароля, дождитесь его и проверьте код или ссылку. В teardown удаляйте ящик.

Храните ключ в секретах CI, например как TEMPGENERATOR_TOKEN в GitHub Actions. Cypress может делать те же HTTP-запросы через cy.request, а рецепт на Python ниже работает в pytest и любом другом раннере.

Playwright (TypeScript)

import { test, expect } from '@playwright/test';

const api = `${process.env.TEMPGENERATOR_URL}/developer-api/v1`;
const headers = { Authorization: `Bearer ${process.env.TEMPGENERATOR_TOKEN}`, Accept: 'application/json' };

async function call(path: string, method = 'GET') {
  const response = await fetch(api + path, { method, headers });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.status === 204 ? null : response.json();
}

async function waitForCode(inboxId: string, after = 0): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await call(`/inboxes/${inboxId}/wait?after=${after}&timeout=20`);
    for (const summary of result.messages) {
      const message = await call(`/inboxes/${inboxId}/messages/${summary.id}`);
      if (message.codes.length) return message.codes[0];
    }
    after = result.next_cursor;
  }
  throw new Error('No verification code arrived');
}

test('signup sends a verification code', async ({ page }) => {
  const inbox = await call('/inboxes', 'POST');
  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(inbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();
    await page.getByLabel('Verification code').fill(await waitForCode(inbox.id));
    await expect(page.getByText('Welcome')).toBeVisible();
  } finally {
    await call(`/inboxes/${inbox.id}`, 'DELETE');
  }
});

GitHub Actions

- name: End-to-end tests
  run: npx playwright test
  env:
    TEMPGENERATOR_URL: https://www.tempgenerator.com
    TEMPGENERATOR_TOKEN: ${{ secrets.TEMPGENERATOR_TOKEN }}

Проверка регистрации на Python

Запустите скрипт с заданными переменными окружения. Он выведет новый ящик: отправьте на этот адрес письмо о регистрации из своего тестового приложения и нажмите Enter. Скрипт ждёт до 15 секунд, выводит каждое письмо с его кодами и ссылками и удаляет ящик, даже если чтение завершилось ошибкой.

import json, os
from urllib.request import Request, urlopen

base = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/developer-api/v1"
headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"],
           "Accept": "application/json"}

def request(path, method="GET"):
    with urlopen(Request(base + path, headers=headers, method=method), timeout=30) as response:
        return json.load(response) if response.status != 204 else None

inbox = request("/inboxes", "POST")
print(json.dumps(inbox), flush=True)
try:
    input()
    result = request("/inboxes/" + inbox["id"] + "/wait?after=0&timeout=15")
    print(json.dumps(result))
    for message in result["messages"]:
        detail = request("/inboxes/" + inbox["id"] + "/messages/" + str(message["id"]))
        print(json.dumps(detail))
finally:
    request("/inboxes/" + inbox["id"], "DELETE")

MCP-сервер для ИИ-агентов

Эндпоинт https://www.tempgenerator.com/mcp, аутентификация через Authorization: Bearer <key>. Streamable HTTP с протоколом 2026-07-28; старые клиенты обслуживаются через рукопожатие 2025-11-25 или 2025-06-18.

Подключение клиента

Claude Code

claude mcp add --transport http tempgenerator-mail https://www.tempgenerator.com/mcp \
  --header "Authorization: Bearer $TEMPGENERATOR_TOKEN"

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "tempgenerator-mail": {
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TEMPGENERATOR_TOKEN}" }
    }
  }
}

VS Code: .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "tempgenerator-token", "description": "TempGenerator API key", "password": true }
  ],
  "servers": {
    "tempgenerator-mail": {
      "type": "http",
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tempgenerator-token}" }
    }
  }
}

Claude в веб-версии и десктопном приложении: добавьте пользовательский коннектор с URL эндпоинта, выберите вариант без входа и добавьте заголовок запроса Authorization: Bearer <key>. Claude подключается из облака Anthropic, поэтому URL должен быть доступен из интернета.

Инструменты

create_inbox

Создаёт приватный ящик и возвращает его ID и адрес.

list_messages

Возвращает сводки писем после курсора с необязательными фильтрами по отправителю и теме.

wait_for_message

Ждёт следующее письмо до 20 секунд.

read_message

Читает текст, коды, ссылки и список вложений одного письма.

delete_inbox

Удаляет ящик и его письма.

Пример промпта

Создайте временный ящик и сообщите мне его адрес. Затем дождитесь письма с подтверждением от моего staging-приложения и назовите код.

Разрешайте агентам завершать регистрацию только в аккаунтах, которые принадлежат вам или которые вам разрешено использовать. Входящим письмам доверять нельзя: сервер никогда не открывает ссылки, а агенты не должны выполнять инструкции из писем.

MCP SDK для Python

Проверено с Python 3 и официальным пакетом mcp 2.3.0: pip install "mcp>=2.3,<3". Сначала задайте TEMPGENERATOR_URL и TEMPGENERATOR_TOKEN.

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/mcp"
    headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"]}
    async with httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30, read=60)) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            created = await client.call_tool("create_inbox", {})
            if created.is_error:
                raise RuntimeError(created.content)
            inbox = created.structured_content
            try:
                print("Send a test email to", inbox["address"])
                waited = await client.call_tool("wait_for_message", {"inbox_id": inbox["id"], "timeout": 20})
                for summary in waited.structured_content["messages"]:
                    message = await client.call_tool("read_message", {"inbox_id": inbox["id"], "message_id": summary["id"]})
                    print(message.structured_content["subject"], message.structured_content["codes"])
            finally:
                deleted = await client.call_tool("delete_inbox", {"inbox_id": inbox["id"]})
                if deleted.is_error:
                    raise RuntimeError(deleted.content)

asyncio.run(main())

Вложения

При чтении письма возвращаются индекс, имя файла и размер каждого вложения. Скачать вложение можно через GET …/attachments/{index}: файлы до 10 МБ отдаются как application/octet-stream с очищенными именами файлов. MCP-клиенты видят тот же список и скачивают вложения через этот REST-эндпоинт.

Когда выбрать этот API вместо других инструментов

Mailpit, MailHog и Ethereal перехватывают письма, которые ваше приложение отправляет на локальный или фиктивный SMTP-сервер, — это идеально, когда вы управляете настройками SMTP. Эти ящики — настоящие адреса на публичном домене, поэтому до них может достучаться любой отправитель: сторонний сервис, staging-сервер с вашим реальным почтовым провайдером или сценарий, близкий к продакшену.

Обычные API временной почты, например mail.tm или Guerrilla Mail, рассчитаны на личные одноразовые адреса. Этот API создан для автоматизации: ключи с ограниченными правами и сроком действия, один ящик на тест, ограниченное по времени ожидание через long polling, распознавание кодов и ссылок и MCP-сервер.

Не входит: отправка писем, SMS, предпросмотр HTML или проверка на спам, собственные домены и вход через OAuth для MCP-клиентов.

Хранение, ограничения и безопасность

Домен приёма может задать более короткий срок жизни или меньший лимит писем.

Только приём. Считайте письма и вложения недоверенными; ничего не открывается автоматически. При удалении ящика его письма удаляются сразу, а истёкшие ящики удаляет плановая очистка.

Частые вопросы