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

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

Персональная бета-версия 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Опрашивать неподтверждённые входящие сообщения, когда у агента нет конечной точки вебхука.
• POST /v1/messages/{id}/agent-receiptsRecord whether the agent saw, processed, failed, or ignored an inbound message.
• GET /v1/messages/{id}/agent-statusRead the operator-facing status that combines LoftBox state, inbox ack, webhook delivery, and the latest agent receipt.

Саморегистрация — мгновенный API-ключ

Получите рабочий API-ключ одним неаутентифицированным вызовом POST /v1/auth/agent-signup. Регистрация в консоли не требуется, поэтому агент может начать сразу.

Пока владелец не подтвердит (заявит права на) аккаунт по электронной почте, агент может отправлять и получать письма только с этим единственным адресом владельца — замкнутый контур. Владелец заявляет права на loftbox.net/claim (ссылка отправляется автоматически) или через API заявки, что снимает ограничение. Незаявленные аккаунты удаляются через 30 дней.

curl -X POST https://api.loftbox.net/v1/auth/agent-signup \
  -H 'content-type: application/json' \
  -d '{"owner_email":"[email protected]"}'
# -> { "api_key": "lb_live_...", "mailbox_address": "[email protected]",
#      "signup_status": "unverified" }

• POST /v1/auth/agent-signupМгновенно создаёт ограниченный (непроверенный) аккаунт и один раз возвращает API-ключ.
• POST /v1/auth/claim/startОтправляет код подтверждения на адрес владельца, чтобы начать заявку.
• POST /v1/auth/claim/verifyПроверяет код, переводя аккаунт в статус подтверждённого и снимая ограниченный режим.

Базовый 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 интеграции.

Official SDKs

Official client libraries wrap the REST API in idiomatic, typed clients across eight languages — with popular framework integrations. Every SDK uses the same API key, the same approval/rate-limit/audit pipeline, and exposes the inbound safety signals: the prompt-injection score on inbound messages and the sender allow/block rules.

Sources and per-language quickstarts live in each GitHub repository under github.com/TheMagicTower (loftbox-sdk-<language>). Python, TypeScript, and Go are published to their registries; the remaining packages are rolling out to Packagist, Maven Central, RubyGems, NuGet, and crates.io — check the repo for current registry status.

Аутентификация 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 &rarr; подключение домена &rarr; 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; если агент не может их найти, его установленный набор устарел, и повторный запуск установщика добавит их.

• Репозиторий (публичный): github.com/TheMagicTower/loftbox-agent-mail-skill
• Каталоги навыков: onboard-business-domain/, setup-loftbox-domain/
• Версия установленного набора &amp; закреплённый коммит: loftbox.net/skill-version.json

Навык 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.

IMAP / SMTP access

Besides the REST API and SDKs, you can connect any standard mail client or library over IMAP and SMTP. There is no separate mail password: authenticate with your LoftBox API key as the password and your full mailbox address as the username. Sending reuses the same pipeline as the API, so approval policy, rate limits, daily and storage caps, and audit logging all still apply.

Username is your mailbox address (for example bot-…@mail.loftbox.net), password is your API key — send scope for SMTP, receive scope for IMAP. IMAP exposes INBOX (incoming) and Sent (outgoing), read-only for now.

Mailboxes on the shared mail.loftbox.net domain support autoconfig: in Thunderbird and similar clients, entering the address and API key fills in the IMAP and SMTP settings automatically.

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

Ответы сохраняются как входящие сообщения. Агенты с конечной точкой 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"
    ]
  }'

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

Every message.inbound event carries an injection_risk object — a prompt-injection heuristic score (0–1) plus the matched categories (instruction override, role hijack, tool injection, data exfiltration, hidden text, encoding evasion). The same value is on the message as injection_score. It is a signal only: LoftBox never blocks on it, so your agent decides how to act on untrusted inbound content — for example, requiring human approval above a threshold before following instructions found in an email.

To control which senders can reach an agent at all, manage per-mailbox or org-wide inbound allow/block lists via /v1/inbound-rules. Block a sender address or domain, or set an allowlist so only approved senders are accepted — anything else is refused at receive time (SMTP 550). Rules are evaluated against the SMTP envelope sender, not the spoofable From header.

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"]}'

Inbox acknowledgement and agent processing receipt are different signals. The inbox object does not embed receipt state: acknowledge removes a delivered inbound message from the polling queue, while an agent receipt tells operators whether the agent saw, processed, failed, or ignored that message.

curl -i -X POST "$BASE_URL/v1/messages/message_uuid_or_msg_public_id/agent-receipts" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "processed",
    "external_run_id": "agent-run-123",
    "summary": "Parsed and linked to the support ticket",
    "action_required": false
  }'

curl -i "$BASE_URL/v1/messages/message_uuid_or_msg_public_id/agent-status" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Recommended polling order: fetch inbox, process the message durably, post the agent receipt, then acknowledge the inbox item. If posting the receipt fails, retry it before acknowledging so the portal does not show a processed message with no receipt.

Подтверждайте только после того, как агент надёжно обработал сообщение. Опрос пустых входящих должен использовать экспоненциальную задержку; активный опрос должен использовать умеренный интервал, например 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

Почтовые провайдеры (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 или документация на главной странице неисправны.