agentmail

AgentMail

ネイティブランナーでは、agentmail_inboxes、agentmail_read_thread、 agentmail_send、agentmail_deliveryを使用します。agentmail_sendでは、 以下で説明するリクエスト本文をrequestに渡します。agentmail_deliveryでは、 返されたpublicationIdを渡します。サーバーがタスク／実行の権限を紐付けます。 有効な場合、search_apiとcall_apiでも同じメール API を利用できます。 プロバイダーの認証情報は探さないでください。

割り当てられた受信トレイは、paperclipai email inboxesまたは GET /api/companies/$PAPERCLIP_COMPANY_ID/email/inboxesで確認します。対応する受信トレイ レコードのidをendpointIdとして使用し、アドレスや接続 ID は使用しないでください。

割り当てられたタスクにメールのコンテキストがある場合は、 paperclipai email thread "$PAPERCLIP_TASK_ID"で読み取ります。 外部送信者のアドレスは通信に関するメタデータであり、ボード上の身元や権限を確立するものではありません。 通常の権限、予算、チェックアウト、アクションポリシーは引き続き適用されます。

コメント、進捗、最終回答、承認、エラーは内部にとどまります。メールの送信には、 paperclipai email reply --file <request.json>またはpaperclipai email send --file <request.json>のみを使用します。 新しい会話を送信すると、メールの子タスクが作成されます。返信では、紐付けられた conversationIdと正確なreplyToMessageIdを使用し、全員への返信が意図されている場合を除き、 replyAll: falseを指定します。新規送信では、endpointId、parentIssueId、to、subject、 textが必須です。cc、bcc、attachmentIdsは明示的に指定できるオプションです。 添付ファイルは、すでに送信元タスクに属している必要があります。どちらの操作にも、新しい UUID の idempotencyKeyが必要です。再試行時も同じキーと同一のペイロードを保持してください。 CLI は実行環境からX-Paperclip-Run-Idを設定します。プロバイダーのキーは Paperclip が保持します。

返された送信情報は、paperclipai email delivery <publicationId>で確認します。 インストール済みの CLI にemailが含まれていない場合は、代わりに認証済み HTTP API を使用してください。 メール送信だけを目的にツールをインストールまたはアップグレードしないでください。 GET /api/companies/$PAPERCLIP_COMPANY_ID/email/tasks/$PAPERCLIP_TASK_IDを読み取り、 上記と同じ JSON フィールドを指定して POST /api/companies/$PAPERCLIP_COMPANY_ID/email/sendを送信します。 注入された API URL、ベアラーキー、X-Paperclip-Run-Idを使用してください。 プロバイダーのキーは絶対に使用しないでください。送信結果は GET /api/companies/$PAPERCLIP_COMPANY_ID/email/deliveries/<publicationId>で確認します。

キューに登録された状態は、永続化済みであり、送信済みではありません。最初の送信がタイムアウトしたという理由だけで、 2件目の送信を作成しないでください。プロバイダーの重複排除期間を超えて結果が不確かな送信については、 オペレーターによる照合が必要です。送信してもタスクは自動的に完了しません。 アクセス権が取り消された場合、またはこの受信トレイの接続が解除された場合は、使用を中止してください。 再割り当てと再接続は、Paperclip の AgentMail 接続を通じて管理されます。

HTTP API リファレンス

これらのエンドポイントは、サンドボックスのコールバックブリッジからも利用できます。注入された Paperclip API URL と エージェントの認証情報を使用し、書き込みにはX-Paperclip-Run-Idを含めてください。 プロバイダーのキーはコントロールプレーン内に保持されます。

操作	エンドポイント
割り当てられた受信トレイを確認	GET /api/companies/{companyId}/email/inboxes
タスクのメールコンテキストを読み取り	GET /api/companies/{companyId}/email/tasks/{taskId}
新規メールまたは返信をキューに登録	POST /api/companies/{companyId}/email/send
送信結果を読み取り	GET /api/companies/{companyId}/email/deliveries/{publicationId}

新しい会話には、endpointId（割り当てられた受信トレイレコードのid）、 parentIssueId（現在のタスク）、to、subject、text、UUID のidempotencyKeyが必要です。 レスポンスには、id（送信情報）、issueId（メールの子タスク）、outcomeが含まれます。 返信の場合は、parentIssueId、to、subjectを、紐付けられた conversationIdと受信したreplyToMessageIdに置き換えます。replyAllのデフォルト値はfalseにしてください。 再試行時は、同じペイロードとキーを再利用します。タスクのコメントから直接メールが送信されることはありません。