대량 이메일 상태 엔드포인트

이 문서에서는 대량 이메일 상태 엔드포인트 POST /apps/api/v1/email/update_status를 설명합니다. 이 엔드포인트를 사용하여 최대 100개의 이메일 세션 상태를 지정한 상태로 변경할 수 있습니다. 지정한 각 이메일 세션에 대해 응답은 업데이트되었는지, 변경이 필요하지 않았는지, 업데이트할 수 없었는지와 그 이유를 보고합니다. 즉, 통합은 부분적인 성공을 처리하고 주의가 필요한 세션을 식별할 수 있습니다.

대량 이메일 상태 엔드포인트는 다음 사용 사례를 지원합니다.

  • 대량 이메일 대기열을 관리하고 많은 세션을 한 번에 일시중지, 해결 또는 종료해야 합니다.

  • 비즈니스 규칙에 따라 이메일 세션을 전환하는 외부 워크플로를 실행합니다(예: 업무 시간 외에 세션 일괄 처리 일시중지).

  • 통합에서 새 상태로 전환되지 않은 세션을 재시도하거나 조정할 수 있도록 각 이메일 세션의 결과를 보고하는 단일 작업을 원합니다.

인증

인증하려면 기본 인증을 참조하세요.

엔드포인트 사용 방법

대량 이메일 상태 엔드포인트를 호출하려면 대상 상태와 상태를 업데이트할 이메일 세션의 세션 ID 목록을 지정합니다. 요청당 하나의 대상 상태만 지정할 수 있습니다. 세션을 다른 상태로 업데이트하려면 별도의 요청을 보내세요.

세션 상태는 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 Platform 호스트입니다.

  • 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: 인스턴스에서 엔드포인트를 사용할 수 없습니다.

다음 단계