建立經過網域驗證的 agent 電子郵件工作流程。

開始使用

LoftBox 個人 beta 從一個擁有者電子郵件開始。註冊會建立組織並寄送一組 6 位數的驗證權杖。只有在擁有者電子郵件驗證後，LoftBox 才會回傳第一個 API 金鑰，而該明文金鑰只會顯示一次。驗證同時也會寄給擁有者一封歡迎信，內含 beta 限制以及未來的管理員/帳務註冊路徑。

個人 beta 帳號每天的出站寄送上限為 100 封。信箱訊息保留期間預設為 7 天。企業上線、帳務、組織成員管理以及更高的限制屬於 roadmap 項目。

• POST /v1/auth/signup建立個人 beta 組織並寄送擁有者電子郵件驗證權杖。
• POST /v1/auth/signup/verify驗證擁有者電子郵件、一次性取得初始 API 金鑰，並觸發擁有者歡迎通知。
• POST /v1/agents以擁有者、用途及政策範圍建立一個 agent 身分。
• POST /v1/domains為你掌控的網域啟動自訂網域上線。
• POST /v1/agents/{agent_id}/mailboxes建立由 LoftBox 託管的 beta 信箱，或經驗證的自訂網域信箱。
• POST /v1/messages從 agent 信箱寄送營運用電子郵件。
• GET /v1/mailboxes/{id}/inbox當 agent 沒有 webhook 端點時，輪詢尚未確認的入站訊息。
• 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 金鑰

透過對 POST /v1/auth/agent-signup 的一次免驗證呼叫即可取得可用的 API 金鑰。無需主控台註冊，代理可立即開始。

在擁有者透過電子郵件驗證（認領）帳戶之前，代理只能與該擁有者的單一位址收發郵件（封閉迴路）。擁有者可在 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驗證驗證碼以將帳戶升級為已驗證並解除受限模式。

Base URL 與機器可讀文件

正式的公開 API 端點為 https://api.loftbox.net。首頁保留一個 /api/* 代理路徑供預覽驗證使用，但正式環境的整合應使用專用的 API 主機名稱。

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

在串接整合之前，先檢查邊緣節點與 schema：

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

該 https://loftbox.net/api 路由會移除 /api 前綴並轉送至相同的 Fly API origin。請將它用於 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 認證

首先為個人 beta 組織註冊擁有者電子郵件。擁有者會收到一封含驗證權杖的電子郵件；驗證呼叫會一次性回傳初始 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、由部署平台管理的環境變數，或專用的密鑰管理工具。請勿將真實金鑰貼到 issue 留言、截圖、分析工具或瀏覽器程式碼中。

當營運人員離職、密鑰可能外洩，或某個環境不再需要 API 存取時，請輪換金鑰。

一行安裝與 agent 提示詞

Agent 可以安裝公開的 LoftBox mail 技能，然後僅以擁有者電子郵件執行上線流程。註冊技能會從目前的 agent 推導出組織標籤、穩定的 external_id、agent 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

請僅將更新檢查當作通知路徑使用。安裝新的技能套件會改變 agent 行為，因此更新應在營運人員核准後才執行。

只有在無法推導出 agent 身分，或重複的外部 ID 屬於另一個 agent 時，才需要詢問其他值。

自訂網域上線

每個出站網域都必須先經過驗證，信箱才能使用它。API 會回傳用於所有權、入站路由、寄件者對齊以及投遞驗證所需的 DNS 記錄。

1. 以 POST /v1/domains建立網域。
2. 以 GET /v1/domains/{id}/dns取得所需的記錄。
3. 在你的 DNS 主機上新增回傳的 TXT、MX、DKIM 以及 return-path 記錄。
4. 在 DNS 傳播完成後呼叫 POST /v1/domains/{id}/verify 。
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"

或者讓 agent 透過統一的 onboard-business-domain 流程端到端完成整個業務上線（email 認證 &rarr; 網域上線 &rarr; DNS）。將這段提示詞貼到你的 agent：

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; 若 agent 找不到它們，表示其已安裝的套件已過時，重新執行安裝程式即可加入它們。

• 儲存庫（公開）： github.com/TheMagicTower/loftbox-agent-mail-skill
• 技能目錄： onboard-business-domain/、 setup-loftbox-domain/
• 已安裝套件版本 &amp; 釘選 commit： 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。該技能會呼叫 LoftBox API &mdash; 請完全使用 API 回傳的 DNS 值，切勿自行捏造：

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 權杖步驟需要人工介入，因此並非完全無人值守。

在上線階段，個人 beta 使用 LoftBox 託管的投遞與 LoftBox 託管的入站 MX 處理。自訂網域僅在驗證後才會啟用。

Agent 與信箱

Agent 保有業務用途、所有權脈絡以及穩定的外部 ID。信箱則將一個位址與網域附加到該 agent。請讓顯示名稱、擁有者及政策範圍清晰到足以供營運人員審查。

• 每個營運 agent 或工作流程角色使用一個信箱。
• 使用 external_id 進行重複檢查與冪等的 agent 設定。
• 正式出站郵件請使用經驗證的自訂網域。
• 當 agent 用途不明確時，停用或暫停自主寄送。

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

對於 LoftBox 託管的個人 beta 網域，請省略 domain_id 。若 agent 具有 HTTPS 端點，請另外註冊一個 agent webhook。

在經驗證的自訂網域上，你可以將一個信箱標記為 catch-all（"is_catch_all": true 在建立或更新時）。該網域上任何沒有精確對應信箱的位址都會路由至它 — 適合以單一 agent 接收 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 relay 用途皆不在 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.

入站 webhook 與輪詢

回覆會儲存為入站訊息。具有 HTTPS 端點的 agent 可以接收經簽章的 webhook 事件；沒有端點的 agent 則應輪詢信箱收件匣並對每則已處理的訊息進行確認。

• message.inbound一則新的入站訊息或回覆已被解析、歸入討論串，並提供給所設定的 webhook。
• 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"
    ]
  }'

Webhook 密鑰會在建立 webhook 時一次性回傳。請立即存放，並在信任事件內容之前驗證每個入站簽章。

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.

只有在 agent 已穩固處理完訊息後才進行確認。空的收件匣輪詢應退避；活躍輪詢應使用適中的間隔，例如 30-60 秒。

即時串流（WebSocket）

無法托管 HTTPS webhook 的 agent（例如位於 NAT 或防火牆後方）可以透過 WebSocket 即時訂閱事件。該串流承載與 webhook 相同的事件類型，具備次秒級投遞以及以游標為基礎、用於重放斷線期間漏掉事件的能力。需要 receive 範圍。

• GET /v1/wsWebSocket 升級。以 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 frame，或 resync_required時，請使用最後接收到的游標重新連線。

權限與 API 金鑰

API 金鑰帶有範圍。粗粒度範圍（send、 receive、 admin）會涵蓋細粒度範圍（message:send、 message:read、 domain:manage、 approval:decide、 keys:manage、…），因此既有金鑰仍可運作，同時你也能為子 agent 核發最小權限的子金鑰。

• 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：政策、速率限制或報告控制阻擋了寄送。

速率限制與報告控制

出站寄送受組織、agent、信箱、收件者及網域政策的限制。個人 beta 組織每天的寄送上限為 100 封。高風險訊息可能會被暫停以等待核准，之後才嘗試投遞。

請以退避方式處理 429 回應。請勿無止盡重試，或從另一個信箱繞過核准暫停。

HTTP/1.1 429 Too Many Requests
Retry-After: 60

託管投遞與安全設定

LoftBox 為 beta 帳號營運託管的出站投遞。公開文件應描述顧客可見的控制，而不曝露內部供應商名稱、憑證或路由細節。

• 業務性質：為經網域驗證的 AI agent 提供 API 託管的營運電子郵件身分。
• 電子郵件類型：交易/系統通知、由經驗證使用者發起的 agent 回覆、上線/測試訊息，以及報告/聯絡處理。
• 控制：僅限經驗證網域、明確的速率限制、投遞日誌、抑制/投訴處理，以及受監控的報告聯絡。
• 公開頁面： 隱私權、 條款，以及 反垃圾郵件政策。

DNS 傳播與投遞驗證的暫停狀態應被視為設定狀態，而非 API 代理或首頁文件出問題的證明。