一括メールのステータス エンドポイント

このドキュメントでは、一括メールのステータス エンドポイント POST /apps/api/v1/email/update_status について説明します。このエンドポイントを使用すると、最大 100 件のメール セッションのステータスを指定したステータスに変更できます。指定したメール セッションごとに、更新されたかどうか、変更が必要なかったかどうか、更新できなかったかどうかと、その理由がレポートされます。つまり、統合で部分的な成功を処理し、注意が必要なセッションを特定できます。

一括メールのステータス エンドポイントは、次のユースケースをサポートしています。

  • 大量のメールキューを管理しており、多くのセッションを一度に一時停止、解決、終了する必要がある。

  • ビジネスルールに基づいてメール セッションを移行する外部ワークフローを実行します（たとえば、営業時間外にセッションのバッチを一時停止するなど）。

  • 各メール セッションの結果をレポートする単一のオペレーションが必要です。これにより、統合で新しいステータスに移行しなかったセッションを再試行または調整できます。

認証

認証については、基本認証をご覧ください。

エンドポイントの使用方法

一括メール ステータス エンドポイントを呼び出すには、ターゲット ステータスと、ステータスを更新するメール セッションのセッション ID のリストを指定します。リクエストごとに指定できるターゲット ステータスは 1 つだけです。セッションのステータスを更新するには、別のリクエストを送信します。

セッションのステータスを更新できるのは、API トークンを所有するインスタンス内のメール セッションのみです。インスタンスにないメール セッションのセッション ID は、"result": "failure" と "reason": "not_found" でマークされます。

セッションを closed に移行すると、それらのセッションに対して構成された CRM 同期がトリガーされる可能性があります。

更新するメール セッションのセッション ID を取得する方法については、メール セッションとメッセージを取得するをご覧ください。

有効なステータス遷移

ターゲット ステータスを指定すると、有効なソース ステータスからターゲット ステータスにのみ移行できます。現在のステータスがターゲットの有効なソースではないセッションは、ステータスが変更されず、"reason": "invalid_transition" でマークされます。

次の表に、指定できるターゲット ステータスと、各ターゲットの有効なソース ステータスを示します。

ターゲット ステータス 有効なソースのステータス
active unopened、reopened、paused
paused active
resolved active
closed paused、resolved

メール セッションのステータスを更新する

メール セッションのステータスを更新するには、次のエンドポイントに POST リクエストを送信します。

https://YOUR_CCAAS_HOST/apps/api/v1/email/update_status

次の構造のリクエスト本文を含めます。

{
  "session_ids": [
    "SESSION_ID"
  ],
  "new_email_status": "NEW_EMAIL_STATUS"
}

次のように置き換えます。

  • YOUR_CCAAS_HOST: CCAI プラットフォーム ホスト。

  • SESSION_ID: 最大 100 個のメール セッション ID の文字列配列（例: ["123", "456", "789"]）。空の値は拒否されます。

  • NEW_EMAIL_STATUS: リクエスト内のすべてのセッションに適用されるターゲット ステータス。有効な値: active、paused、resolved、closed。

省略可: 最後に読み取った後に変更されたメール セッションのセッション ステータスの更新を防ぐには、リクエスト本文に次のフィールドを含めます。

{
  "existing_email_status": "EXISTING_EMAIL_STATUS"
}

EXISTING_EMAIL_STATUS は、unopened、active、paused、resolved、closed、reopened のいずれかのステータスに置き換えます。existing_email_status を含めて、セッションがこのステータスでない場合、理由 stale_state で失敗します。

出力は次のようになります。

{
  "results": [
    { "session_id": "123", "from_status": "active", "to_status": "paused", "result": "success" },
    { "session_id": "456", "result": "failure", "reason": "invalid_transition", "current_status": "closed" },
    { "session_id": "789", "result": "noop", "current_status": "paused" }
  ]
}

レスポンスのフィールド

results 配列には次のフィールドが含まれます。

  • session_id: リクエストのターゲットとなるセッションの ID。

  • from_status: 更新前のセッションのステータス。

  • to_status: 更新後のセッションのステータス。

  • result: 更新の結果。値は次のいずれかです。

    • success: セッションのステータスが更新されました。結果には from_status と to_status が含まれます。

    • failure: セッションのステータスが更新されませんでした。結果には reason と current_status が含まれます。

    • noop: セッションはすでにターゲット ステータスにあるため、更新は必要ありませんでした。結果には current_status が含まれます。

  • reason: ステータスの更新が失敗した理由。値は次のいずれかです。

    • not_found: インスタンス内のメール セッションが、指定されたセッション ID と一致しません。再試行しても成功しません。

    • invalid_transition: セッションの現在のステータスが、指定されたターゲット ステータスの有効なソース ステータスではありません。

    • stale_state: existing_email_status が含まれており、セッションの現在のステータスが一致しませんでした。

    • internal_error: 予期しないエラーが発生しました。リクエストを再試行できます。

  • current_status: リクエストが処理されたときのセッションのステータス。

エラー メッセージ

一括メール ステータス エンドポイントは、次のエラー メッセージを返します。

  • 400 Bad Request: リクエスト本文の形式が正しくない、session_ids がないか空である、session_ids が 100 個の要素を超えている、new_email_status がないか受け入れ可能なステータスではない、existing_email_status が有効なステータスではない。

  • 401 Unauthorized: 認証に失敗したか、認証情報が ApiUser トークンではありません。

  • 404 Not Found: エンドポイントがインスタンスで使用できません。

次のステップ