Створюйте робочі процеси email для агентів з верифікованим доменом.

Початок роботи

Персональна бета 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Надсилайте операційний email зі скриньки агента.
• 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 власника для організації персональної бети. Власник отримує токен верифікації електронною поштою; виклик верифікації один раз повертає початковий ключ 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.

Офіційні навички & джерело

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

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

Навичка setup-loftbox-domain викликається шляхом прямого запуску її скрипта (інсталятор не створює shell-команду setup-loftbox-domain ). $SKILL_DIR — це місце, куди install.sh розмістив навичку — напр. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, або на Hermes ~/.hermes/skills/email/setup-loftbox-domain. Навичка викликає API LoftBox — використовуйте саме ті значення 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, та обробку вхідного MX, керовану LoftBox. Власні домени вмикаються лише після верифікації.

Агенти та поштові скриньки

Агенти містять бізнес-призначення, контекст володіння та стабільний зовнішній 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. Потік несе ті самі типи подій, що й вебхуки, із доставкою менш ніж за секунду та відтворенням на основі курсора подій, пропущених під час відключення. Потребує область 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, повторно підключіться, використовуючи останній отриманий курсор.

Дозволи та ключі API

Ключі API несуть області. Грубі області (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, …) надсилають щоденні агреговані звіти DMARC (rua), які підсумовують, які вихідні 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 операційні email-ідентичності для AI-агентів із верифікованим доменом.
• Типи email: транзакційні/системні сповіщення, відповіді агентів, ініційовані верифікованими користувачами, онбординг-/тестові повідомлення та обробка звітів/контактів.
• Елементи контролю: лише верифіковані домени, явні обмеження частоти, логи доставки, обробка придушення/скарг та контрольований контакт для звітів.
• Публічні сторінки: Конфіденційність, Умови, та Антиспам-політика.

Поширення DNS та затримки верифікації доставки слід розглядати як стан налаштування, а не як доказ того, що проксі API чи документація домашньої сторінки несправні.