LoftBox 文件 - API beta

開始

開始使用

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 端點時，輪詢尚未確認的入站訊息。

端點

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。

認證

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 提示詞

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 記錄。

以 POST /v1/domains建立網域。
以 GET /v1/domains/{id}/dns取得所需的記錄。
在你的 DNS 主機上新增回傳的 TXT、MX、DKIM 以及 return-path 記錄。
在 DNS 傳播完成後呼叫 POST /v1/domains/{id}/verify 。
在建立正式信箱之前，請等到入站與出站狀態皆已驗證。

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 認證 → 網域上線 → 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.

官方技能 & 原始碼

onboard-business-domain 與 setup-loftbox-domain 為官方 LoftBox 技能。它們發布於公開技能儲存庫，並由 https://loftbox.net/install.sh 安裝 — 若 agent 找不到它們，表示其已安裝的套件已過時，重新執行安裝程式即可加入它們。

儲存庫（公開）： github.com/TheMagicTower/loftbox-agent-mail-skill
技能目錄： onboard-business-domain/、 setup-loftbox-domain/
已安裝套件版本 & 釘選 commit： loftbox.net/skill-version.json

該 setup-loftbox-domain 技能透過直接執行其指令稿來呼叫（安裝程式並不會建立 setup-loftbox-domain shell 命令）。 $SKILL_DIR 為 install.sh 放置技能的位置 — 例如 ~/.claude/skills/setup-loftbox-domain、 ~/.codex/skills/setup-loftbox-domain，或在 Hermes 上 ~/.hermes/skills/email/setup-loftbox-domain。該技能會呼叫 LoftBox API — 請完全使用 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 政策範圍內。

入站

入站 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 時一次性回傳。請立即存放，並在信任事件內容之前驗證每個入站簽章。

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

只有在 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

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 代理或首頁文件出問題的證明。