API v1 · Public beta

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

1. Выпустите API key

Войдите в dashboard, откройте «Ключи API» и сохраните secret: он показывается только один раз.

2. Создайте inbox

curl -X POST https://api.tstly.ru/v1/inboxes \
  -H "Authorization: Bearer $TSTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"signup","retentionSeconds":86400}'

{
  "id": "019…",
  "tenantId": "019…",
  "localPart": "signup",
  "address": "signup@acme.tstly.ru",
  "retentionSeconds": 86400,
  "createdAt": "2026-08-01T12:00:00Z"
}

3. Отправьте письмо

Укажите возвращённый address как получателя в SMTP-клиенте вашего приложения.

Аутентификация

Передавайте API key как Bearer token. Ключ привязан к tenant и не даёт доступ к чужим inbox.

Authorization: Bearer $TSTLY_API_KEY

Получение писем

Сначала получите текущий список, затем используйте latestCursor как afterCursor в long polling. Без cursor запрос ждёт первое доступное сообщение.

curl "https://api.tstly.ru/v1/inboxes/$INBOX_ID/messages/wait?timeoutSeconds=30" \
  -H "Authorization: Bearer $TSTLY_API_KEY"

Ответ 204 No Content означает, что за выбранные 30 секунд нового письма не появилось. Повторите запрос; это нормальный результат, не ошибка.

TypeScript SDK и CLI

Официальный ESM-пакет @tstly/sdk работает в Node.js 22.12+. Клиент типизирует inbox, сообщения, вложения, usage и webhooks, поддерживает AbortSignal, timeout и безопасный retry чтения с учётом Retry-After.

curl -fLO https://tstly.ru/downloads/tstly-sdk-0.1.0.tgz
npm install ./tstly-sdk-0.1.0.tgz

import { Tstly } from "@tstly/sdk";

const tstly = new Tstly({ apiKey: process.env.TSTLY_API_KEY! });
const inbox = await tstly.inboxes.create({ retentionSeconds: 3600 });
const message = await tstly.messages.wait(inbox.id, {
  subject: "Confirm account",
  timeoutSeconds: 30,
});

CLI для CI

Передавайте ключ только через TSTLY_API_KEY. JSON-данные пишутся в stdout, диагностика — в stderr. Timeout ожидания завершает команду с кодом 3.

export TSTLY_API_KEY='…'
tstly inbox create --local-part ci --retention 3600
tstly message wait "$INBOX_ID" --subject "Confirm account" --timeout 30

Playwright и Cypress

Готовые адаптеры создают отдельный inbox на каждую попытку теста, изолируют параллельные workers и гарантируют cleanup. API key остаётся в Node-процессе и не передаётся странице или browser context.

Playwright fixture

curl -fLO https://tstly.ru/downloads/tstly-sdk-0.1.0.tgz
curl -fLO https://tstly.ru/downloads/tstly-playwright-0.1.0.tgz
npm install -D ./tstly-sdk-0.1.0.tgz ./tstly-playwright-0.1.0.tgz @playwright/test

import { test, expect } from "@tstly/playwright";
test("signup", async ({ page, tstly }) => {
  await page.getByLabel("Email").fill(tstly.inbox.address);
  expect(await tstly.wait({ subject: "Confirm account" })).not.toBeNull();
});

Cypress tasks

// cypress.config.ts — Node process
import { setupTstly } from "@tstly/cypress/node";
// support/e2e.ts — browser commands, no API key
import { installTstlyCommands } from "@tstly/cypress/commands";

При падении Playwright по умолчанию прикладывает только metadata. Режим artifactMode: "full" добавляет raw MIME и вложения — включайте его только для защищённых CI artifacts с ограниченным retention.

Webhooks

Подписка получает событие message.received как at-least-once доставку. Secret возвращается один раз. Проверяйте HMAC в X-Tstly-Signature, дедуплицируйте поX-Tstly-Event-Id и отвечайте 2xx.

curl -X POST https://api.tstly.ru/v1/webhooks \
  -H "Authorization: Bearer $TSTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.test/tstly","description":"CI events"}'

История delivery, ротация secret и ручной redelivery доступны в API и dashboard. Redirect и private-network targets отклоняются.

Ошибки

Ошибка возвращается в едином JSON-формате с кодом, сообщением, request ID и ошибками полей.

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "requestId": "…",
  "fieldErrors": []
}

Лимиты beta

Матрица совместимости

Миграция alpha → beta

Смена base URL, API key и inbox address не требуется. Зафиксируйте пакеты на ^0.1.0, храните key только в Node/CI secret, обрабатывайте 204 long-poll timeout и 429с Retry-After. Для webhooks добавьте HMAC-проверку и идемпотентность event ID. HTML писем по-прежнему считается недоверенным содержимым.

Beta release notes

В beta входят quota/usage, cursor filters и long polling, подписанные webhooks, TypeScript SDK/CLI, Playwright и Cypress adapters, workspace roles/audit, operator abuse controls и external SMTP reliability monitoring.

Безопасность, support и feedback

Не отправляйте реальные персональные или production-данные. Удаляйте inbox после теста и выбирайте минимальный retention. Уязвимости сообщайте приватно на security@tstly.ru, вопросы и feedback — на support@tstly.ru. Не прикладывайте API keys, raw MIME или содержимое писем.