Документация бета-версии API

Создавайте сценарии работы с почтой для агентов на подтверждённых доменах.

Эта бета-документация охватывает проверку email владельца, аутентификацию API, настройку навыков агента, подключение собственных доменов, почтовые ящики агентов, отправку, входящие вебхуки, события доставки, ограничения частоты и управление доставкой.

Начало

Начало работы

Персональная бета-версия LoftBox начинается с одного email владельца. Регистрация создаёт организацию и отправляет на email 6-значный токен подтверждения. Только после проверки email владельца LoftBox возвращает первый ключ API, и этот ключ в открытом виде показывается один раз. После подтверждения владелец также получает приветственное письмо с ограничениями бета-версии и сведениями о будущем пути регистрации администратора/биллинга.

Аккаунты персональной бета-версии ограничены 100 исходящими отправлениями в день. Срок хранения сообщений в почтовом ящике по умолчанию составляет 7 дней. Корпоративное подключение, биллинг, членство в организации и более высокие лимиты входят в дорожную карту.

  • POST /v1/auth/signupСоздать организацию персональной бета-версии и отправить токен подтверждения на email владельца.
  • POST /v1/auth/signup/verifyПодтвердить email владельца, единожды получить начальный ключ API и инициировать приветственное уведомление владельца.
  • POST /v1/agentsСоздать идентичность агента с владельцем, назначением и областью политики.
  • POST /v1/domainsНачать подключение собственного домена для домена, которым вы управляете.
  • POST /v1/agents/{agent_id}/mailboxesСоздать управляемый LoftBox бета-почтовый ящик или почтовый ящик на подтверждённом собственном домене.
  • POST /v1/messagesОтправить операционное письмо из почтового ящика агента.
  • GET /v1/mailboxes/{id}/inboxОпрашивать неподтверждённые входящие сообщения, когда у агента нет конечной точки вебхука.
Конечная точка

Базовый URL и машиночитаемая документация

Канонической публичной конечной точкой API является https://api.loftbox.net. На главной странице сохраняется /api/* прокси-путь для проверки в предпросмотре, но для продакшен-интеграций следует использовать выделенное имя хоста API.

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

Перед настройкой интеграции проверьте edge и схему:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

Маршрут https://loftbox.net/api удаляет префикс /api и перенаправляет на тот же источник Fly API. Используйте его для проверок в предпросмотре Pages, а не как основной URL интеграции.

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

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

Начните с регистрации email владельца для организации персональной бета-версии. Владелец получает токен подтверждения по email; вызов подтверждения единожды возвращает начальный ключ API и отправляет приветственное уведомление владельцу.

export LOFTBOX_OWNER_EMAIL="[email protected]"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

Используйте возвращённый серверный ключ API с заголовком Authorization . Никогда не раскрывайте ключи API в браузерах, мобильных клиентах, публичных логах или событиях аналитики.

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Храните ключи в серверном хранилище секретов, таком как Fly secrets, переменные окружения, управляемые платформой развёртывания, или специализированный менеджер секретов. Не вставляйте реальные ключи в комментарии к задачам, скриншоты, инструменты аналитики или код браузера.

Меняйте ключи, когда оператор уходит, секрет мог быть скомпрометирован или окружению больше не нужен доступ к API.

Настройка агента

Установка в одну строку и промпт агента

Агенты могут установить публичные почтовые навыки LoftBox, а затем выполнить процесс подключения, указав только email владельца. Навык регистрации выводит метку организации, стабильный external_id, slug агента и локальную часть почтового ящика из текущего агента. После регистрации установленные навыки отправки и проверки входящих используют выданный ключ API и ID почтового ящика.

curl -fsSL https://loftbox.net/install.sh | sh
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"
If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.
curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

Используйте проверки обновлений только как канал уведомлений. Установка нового набора навыков изменяет поведение агента, поэтому обновления следует выполнять после одобрения оператора.

Запрашивайте другое значение только в том случае, если идентичность агента нельзя вывести или дублирующийся внешний ID принадлежит другому агенту.

Домены

Подключение собственного домена

Каждый исходящий домен должен быть подтверждён, прежде чем почтовые ящики смогут его использовать. API возвращает DNS-записи, необходимые для подтверждения владения, маршрутизации входящих, согласования отправителя и проверки доставки.

  1. Создайте домен с помощью POST /v1/domains.
  2. Получите необходимые записи с помощью GET /v1/domains/{id}/dns.
  3. Добавьте возвращённые записи TXT, MX, DKIM и return-path у вашего DNS-провайдера.
  4. Вызовите POST /v1/domains/{id}/verify после распространения DNS.
  5. Прежде чем создавать продакшен-почтовые ящики, дождитесь, пока статус входящих и исходящих не станет подтверждённым.
curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Либо позвольте агенту провести всё бизнес-подключение от начала до конца с помощью единого процесса onboard-business-domain (аутентификация email → подключение домена → DNS). Вставьте этот промпт в своего агента:

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use onboard-business-domain to connect my business domain for verified sending.
Ask me only for my owner email and the domain to send from.

1. Email auth: register my owner email. LoftBox emails a 6-digit token — ask me
   to paste it, then verify to obtain my organization API key (LoftBox-managed
   sending is available immediately once approved).
2. Domain onboard: run add <domain> (note the returned domain id), then read
   next_actions for the exact DNS records (TXT, DKIM, return-path, inbound MX).
   Show me each record (host, type, value).
3. DNS: let me add the records at my DNS host myself, or auto-apply them with
   apply-dns --provider route53|cloudflare using my own cloud credentials from
   the environment (they stay in my environment; LoftBox never receives them).
4. The domain re-verifies asynchronously on the server after DNS propagates.
   Poll status <domain_id> until inbound and outbound are both verified, then
   report — custom-domain sending activates once verified.
Operate only on my organization. Do not fabricate DNS values; use exactly what the API returns. If onboarding cannot proceed (domain previously deleted, or in use by another org), report it and stop.

Официальные навыки &amp; исходный код

onboard-business-domain и setup-loftbox-domain являются официальными навыками LoftBox. Они опубликованы в публичном репозитории навыков и устанавливаются с помощью https://loftbox.net/install.sh &mdash; если агент не может их найти, его установленный набор устарел, и повторный запуск установщика добавит их.

Навык setup-loftbox-domain вызывается путём прямого запуска его скрипта (установщик не создаёт setup-loftbox-domain shell-команду). $SKILL_DIR находится там, куда install.sh поместил навык &mdash; например, ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, или на Hermes ~/.hermes/skills/email/setup-loftbox-domain. Навык вызывает API LoftBox &mdash; используйте именно те значения DNS, которые возвращает API, никогда не выдумывайте их:

SKILL_DIR=<path to setup-loftbox-domain>   # e.g. ~/.claude/skills/setup-loftbox-domain

python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" add <domain>
   # onboard the domain (idempotent: resolves an existing active row on 409)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" dns <id>
   # list the exact DNS records to set (TXT, DKIM, return-path, MX)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" status <id>
   # structured status: inbound/outbound flags + next_actions
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" verify <id>
   # trigger verification after the DNS records are in place
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" apply-dns <id> --provider route53|cloudflare [--dry-run] [--overwrite]
   # auto-apply the next_actions records using cloud credentials from your OWN
   # environment (they never leave it). With no credentials, add the records
   # manually instead — onboarding still completes.

onboard-business-domain оркестрирует register-loftbox-mail-agent (аутентификация email) и setup-loftbox-domain (подключение домена + DNS) от начала до конца. Шаг с 6-значным email-токеном требует участия человека, поэтому процесс не полностью автономен.

На старте персональная бета-версия использует управляемую LoftBox доставку и управляемую LoftBox обработку входящих MX. Собственные домены включаются только после подтверждения.

Почтовые ящики

Агенты и почтовые ящики

Агенты содержат бизнес-назначение, контекст владения и стабильный внешний ID. Почтовые ящики привязывают адрес и домен к этому агенту. Сохраняйте отображаемые имена, владельцев и область политики достаточно ясными для проверки оператором.

  • Используйте один почтовый ящик на один операционный агент или роль в сценарии.
  • Используйте external_id для проверок на дубликаты и идемпотентной настройки агента.
  • Используйте подтверждённые собственные домены для продакшен-исходящей почты.
  • Отключайте или приостанавливайте автономную отправку, когда назначение агента неясно.
curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"
curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

Опустите domain_id для управляемого LoftBox домена персональной бета-версии. Если у агента есть конечная точка HTTPS, зарегистрируйте вебхук агента отдельно.

На подтверждённом собственном домене вы можете отметить один почтовый ящик как catch-all ("is_catch_all": true при создании или обновлении). Любой адрес на этом домене без точного почтового ящика тогда маршрутизируется в него — полезно для перехвата support@, sales@, или anything@yourdomain одним агентом.

Исходящие

Отправка сообщений

Отправляйте операционные или транзакционные сообщения через API из подтверждённого почтового ящика. LoftBox записывает ссылки доставки, состояние доставки, решения по ограничению частоты и результаты одобрения оператором.

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["[email protected]"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" },
  "send_at": "2030-01-01T09:00:00Z"
}'

Передайте send_at (RFC3339, будущее), чтобы запланировать доставку, и заголовок Idempotency-Key для дедупликации повторных попыток (повтор возвращает исходное сообщение). Перечисляйте и ищите отправленные или полученные сообщения с помощью GET /v1/messages?q=<text>&label=<name>, и упорядочивайте цепочки через POST/DELETE /v1/messages/{id}/labels.

LoftBox не является сервисом массовых маркетинговых рассылок. Купленные списки, собранные парсингом получатели и использование в качестве универсального SMTP-релея находятся за пределами политики MVP.

Входящие

Входящие вебхуки и опрос

Ответы сохраняются как входящие сообщения. Агенты с конечной точкой HTTPS могут получать подписанные события вебхуков; агенты без неё должны опрашивать входящие почтового ящика и подтверждать каждое обработанное сообщение.

  • message.inboundНовое входящее сообщение или ответ были разобраны, объединены в цепочку и предоставлены настроенному вебхуку.
  • message.deliveredДоставка получателю была подтверждена.
  • message.failedИсходящая доставка окончательно не удалась или исчерпала обработку повторных попыток.
curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

Секрет вебхука возвращается один раз при создании вебхука. Немедленно сохраните его и проверяйте каждую входящую подпись, прежде чем доверять содержимому события.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

Подтверждайте только после того, как агент надёжно обработал сообщение. Опрос пустых входящих должен использовать экспоненциальную задержку; активный опрос должен использовать умеренный интервал, например 30-60 секунд.

Входящие

Потоковая передача в реальном времени (WebSocket)

Агенты, которые не могут разместить вебхук HTTPS (например, работающие за NAT или брандмауэром), могут подписываться на события в реальном времени через WebSocket. Поток передаёт те же типы событий, что и вебхуки, с доставкой менее чем за секунду и повтором на основе cursor для событий, пропущенных во время отключения. Требует области receive .

  • GET /v1/wsОбновление до WebSocket. Аутентифицируйтесь с помощью Authorization: Bearer. Фильтруйте с помощью ?event_types= и ?agent_id=; возобновляйте с помощью ?after=<cursor>.
  • GET /v1/ws/asyncapi.jsonСпецификация AsyncAPI для потока (публичная).
wscat -c "wss://api.loftbox.net/v1/ws?event_types=message.inbound" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

# frames: {"type":"ready",...} then {"type":"event","event":{...},"cursor":"..."}
# on reconnect, pass ?after=<last cursor> to replay missed events

При получении error кадра с кодом lagged или resync_required, переподключайтесь, используя последний полученный cursor.

Контроль доступа

Разрешения и ключи API

Ключи API несут области действия (scopes). Крупнозернистые области (send, receive, admin) подразумевают мелкозернистые области (message:send, message:read, domain:manage, approval:decide, keys:manage, …), поэтому существующие ключи продолжают работать, а вы можете выдавать дочерние ключи с минимальными привилегиями для суб-агентов.

  • POST /v1/auth/keysВыдать дочерний ключ. Запрашиваемые области должны быть подмножеством областей вызывающей стороны (без повышения привилегий). Необязательный expires_in_days. Ключ в открытом виде возвращается один раз.
  • GET /v1/auth/keysПеречислить ключи организации (только метаданные, без секретов). Требует keys:manage.
  • DELETE /v1/auth/keys/{id}Отозвать ключ и всех его потомков (каскадом). Разрешено для keys:manage или родителя ключа.
DMARC

Сводные отчёты DMARC

Почтовые провайдеры (Gmail, Outlook, Yahoo, …) ежедневно отправляют сводные (rua) отчёты DMARC, обобщающие, какие исходные IP отправляли почту от имени ваших подтверждённых доменов и согласовались ли SPF/DKIM/DMARC. LoftBox принимает их в структурированные отчёты, чтобы вы могли отслеживать доставляемость и выявлять подмену. Каждый сохранённый отчёт также записывает аутентифицированный домен отправителя отчёта.

  • GET /v1/dmarc/reportsПеречислить сводные отчёты DMARC вашей организации, сначала самые новые. Пагинация по курсору через before_date_end + before_id (возвращаются вместе как next_cursor). Требует domain:read.
  • GET /v1/dmarc/reports/{id}Получить один отчёт с его записями по каждому исходному IP (количество сообщений, диспозиция, согласование DKIM/SPF, header-from). Требует domain:read.
curl -i "$BASE_URL/v1/dmarc/reports" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/dmarc/reports/REPORT_ID" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Отчёты появляются по мере того, как провайдеры их отправляют (обычно раз в день на отправителя отчёта). Возвращаются только отчёты по вашим собственным подтверждённым доменам; отчёты по платформе или нехостящимся доменам никогда не раскрываются.

События

События доставки

Статус доставки нормализуется между обратными вызовами управляемой доставки и внутренним состоянием отправки. Используйте ID событий и ссылки доставки для поддержки, а не приватные данные получателей.

  • queued: принято LoftBox для доставки.
  • sent: принято для исходящей доставки.
  • delivered: доставка получателю была подтверждена.
  • failed: доставка окончательно не удалась или исчерпала повторные попытки.
  • blocked: политика, ограничение частоты или контроль отчётов заблокировали отправку.
Контроль

Ограничения частоты и контроль отчётов

Исходящая отправка ограничена политикой по организации, агенту, почтовому ящику, получателю и домену. Организации персональной бета-версии ограничены 100 отправлениями в день. Сообщения с высоким риском могут быть приостановлены для одобрения, прежде чем будет предпринята попытка доставки.

Обрабатывайте 429 ответы с помощью экспоненциальной задержки. Не повторяйте бесконечно и не обходите приостановки для одобрения из другого почтового ящика.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Управление доставкой

Управляемая доставка и настройка безопасности

LoftBox управляет исходящей доставкой для бета-аккаунтов. Публичная документация должна описывать видимые клиенту средства управления, не раскрывая внутренние имена поставщиков, учётные данные или детали маршрутизации.

  • Характер бизнеса: управляемые через API операционные почтовые идентичности для ИИ-агентов на подтверждённых доменах.
  • Типы писем: транзакционные/системные уведомления, ответы агентов, инициированные подтверждёнными пользователями, сообщения для подключения/тестирования и обработка отчётов/обращений.
  • Средства управления: только подтверждённые домены, явные ограничения частоты, логи доставки, обработка подавлений/жалоб и контролируемый контакт для отчётов.
  • Публичные страницы: Конфиденциальность, Условия, и Политика против спама.

Распространение DNS и приостановки на время проверки доставки следует рассматривать как состояние настройки, а не как доказательство того, что прокси API или документация на главной странице неисправны.