検証済みドメインのエージェントメールワークフローを構築しましょう。

はじめに

LoftBox の個人ベータは、1 つのオーナーメールから始まります。サインアップすると組織が作成され、6 桁の検証トークンがメールで送信されます。オーナーメールの検証が完了した後にのみ、LoftBox は最初の API キーを返し、その平文キーは一度だけ表示されます。検証時には、ベータの制限事項と今後の管理者・課金サインアップの導線を記載したウェルカムメールもオーナーに送信されます。

個人ベータアカウントは 1 日あたり 100 通のアウトバウンド送信に制限されます。メールボックスのメッセージ保持期間はデフォルトで 7 日です。エンタープライズのオンボーディング、課金、組織メンバーシップ、より大きな制限はロードマップ項目です。

• POST /v1/auth/signup個人ベータの組織を作成し、オーナーメールの検証トークンを送信します。
• POST /v1/auth/signup/verifyオーナーメールを検証し、初回の API キーを一度だけ受け取り、オーナーへのウェルカム通知をトリガーします。
• POST /v1/agentsオーナー、目的、ポリシースコープを持つエージェントアイデンティティを作成します。
• POST /v1/domains管理しているドメインのカスタムドメインオンボーディングを開始します。
• POST /v1/agents/{agent_id}/mailboxesLoftBox 管理のベータメールボックス、または検証済みのカスタムドメインメールボックスを作成します。
• 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"

統合を組み込む前に、エッジとスキーマを確認してください:

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 認証

まず、個人ベータ組織のオーナーメールを登録します。オーナーはメールで検証トークンを受け取ります。検証呼び出しは初回の 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 アクセスが不要になったときは、キーをローテーションしてください。

ワンラインインストールとエージェントプロンプト

エージェントは公開の LoftBox メールスキルをインストールし、オーナーメールのみでオンボーディングフローを実行できます。登録スキルは、現在のエージェントから組織ラベル、安定した external_id、エージェントスラグ、メールボックスのローカル部分を導出します。登録後、インストールされた送信スキルと受信トレイ確認スキルは、発行された 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 フロー（メール認証 → ドメインオンボーディング → 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 スキルは、そのスクリプトを直接実行することで呼び出されます（インストーラーは setup-loftbox-domain シェルコマンドを作成しません）。 $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 （メール認証）と setup-loftbox-domain （ドメインオンボーディング + DNS）をエンドツーエンドで。6 桁のメールトークンのステップには人間が必要なため、完全な無人実行にはなりません。

ローンチ時、個人ベータは LoftBox 管理の配信と LoftBox 管理のインバウンド MX 処理を使用します。カスタムドメインは検証後にのみ有効になります。

エージェントとメールボックス

エージェントはビジネス目的、所有コンテキスト、安定した外部 ID を保持します。メールボックスは、そのエージェントにアドレスとドメインを紐付けます。表示名、オーナー、ポリシースコープは、オペレーターがレビューできる程度に明確に保ってください。

• 運用エージェントまたはワークフローのロールごとに 1 つのメールボックスを使用します。
• 重複チェックと冪等なエージェントセットアップには 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
  }'

LoftBox 管理の個人ベータドメインの場合は domain_id を省略します。エージェントに HTTPS エンドポイントがある場合は、エージェントのウェブフックを別途登録します。

検証済みのカスタムドメインでは、1 つのメールボックスを catch-all としてマークできます（"is_catch_all": true を作成時または更新時に指定）。そのドメインの正確なメールボックスを持たないアドレスはすべてそこへルーティングされます。これは support@、 sales@、または anything@yourdomain を 1 つのエージェントで受け取るのに便利です。

メッセージの送信

検証済みのメールボックスから 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 エンドポイントを持つエージェントは、署名付きのウェブフックイベントを受信できます。エンドポイントを持たないエージェントは、メールボックスの受信トレイをポーリングし、処理した各メッセージを確認（acknowledge）してください。

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

エージェントがメッセージを永続的に処理した後にのみ確認（acknowledge）してください。空の受信トレイのポーリングはバックオフすべきです。アクティブなポーリングは 30～60 秒程度の適度な間隔を使用してください。

リアルタイムストリーミング（WebSocket）

HTTPS ウェブフックをホストできないエージェント（例えば NAT やファイアウォールの背後で動作する場合）は、WebSocket 経由でリアルタイムにイベントをサブスクライブできます。このストリームはウェブフックと同じイベントタイプを、サブ秒の配信と、切断中に取りこぼしたイベントのカーソルベースのリプレイで伝送します。これには 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 の 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 など）は、どの送信元 IP があなたの検証済みドメインとしてメールを送信したか、また SPF/DKIM/DMARC が整合したかを要約した、日次の DMARC 集約（rua）レポートを送信します。LoftBox はこれらを構造化レポートに取り込むため、配信性を監視し、なりすましを検知できます。保存される各レポートには、認証されたレポーターのドメインも記録されます。

• GET /v1/dmarc/reports組織の DMARC 集約レポートを新しい順に一覧表示します。カーソルページネーションは次で行います: before_date_end + before_id （次としてまとめて返されます: next_cursor）。次が必要です: domain:read。
• GET /v1/dmarc/reports/{id}送信元 IP ごとのレコード（メッセージ数、disposition、DKIM/SPF アラインメント、header-from）とともに 1 つのレポートを取得します。次が必要です: 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"

レポートはプロバイダーが提出するごとに表示されます（通常、レポーターごとに 1 日 1 回）。返されるのは自分の検証済みドメインのレポートのみで、プラットフォームや未ホストドメインのレポートが公開されることはありません。

配信イベント

配信ステータスは、管理配信のコールバックと内部送信状態にまたがって正規化されます。サポートには受信者の個人データではなく、イベント ID と配信参照を使用してください。

• queued: LoftBox が配信のために受理しました。
• sent: アウトバウンド配信のために受理されました。
• delivered: 受信者への配信が報告されました。
• failed: 配信が恒久的に失敗したか、リトライを使い果たしました。
• blocked: ポリシー、レート制限、またはレポートコントロールによって送信がブロックされました。

レート制限とレポートコントロール

アウトバウンド送信は、組織、エージェント、メールボックス、受信者、ドメインのポリシーによって制限されます。個人ベータ組織は 1 日あたり 100 通の送信に上限が設けられています。リスクの高いメッセージは、配信を試みる前に承認のために保留される場合があります。

次のレスポンスはバックオフして処理してください: 429 。無期限にリトライしたり、別のメールボックスから承認保留をバイパスしたりしないでください。

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

管理配信と安全性のセットアップ

LoftBox はベータアカウント向けに管理されたアウトバウンド配信を運用します。公開ドキュメントでは、内部ベンダー名、認証情報、ルーティングの詳細を公開することなく、顧客に見えるコントロールを記述すべきです。

• ビジネスの性質: 検証済みドメインの AI エージェント向けに API で管理される運用メールアイデンティティ。
• メールの種類: トランザクション/システム通知、検証済みユーザーが開始したエージェント返信、オンボーディング/テストメッセージ、レポート/問い合わせ対応。
• コントロール: 検証済みドメインのみ、明示的なレート制限、配信ログ、抑制/苦情対応、監視されたレポート連絡先。
• 公開ページ: プライバシー、 利用規約、および アンチスパムポリシー。

DNS 伝播と配信検証の保留は、セットアップ状態として扱うべきであり、API プロキシやホームページのドキュメントが壊れている証拠ではありません。