This document describes the bulk email status endpoint: `POST
/apps/api/v1/email/update_status`. You can use this endpoint to change the
status of up to 100 email sessions to a status that you specify. For each email
session that you specify, the response reports whether it was updated, required
no change, or couldn't be updated, along with the reason. This means that
integrations can handle partial success and identify which sessions still need
attention.

The bulk email status endpoint supports the following use cases:

- You manage a high-volume email queue and need to pause, resolve, or close
  many sessions at once.

- You run an external workflow that transitions email sessions based on
  business rules---for example, pausing a batch of sessions during an
  after-hours window.

- You want a single operation that reports the outcome of each email session
  so your integration can retry or reconcile the sessions that didn't
  transition to a new status.

## Authentication

To authenticate, see [Basic authentication](https://docs.cloud.google.com/contact-center/ccai-platform/docs/apps-api#basic-authentication).

## How to use the endpoint

To call the bulk email status endpoint, you specify a target status and a list
of session IDs for the email sessions whose status you want to update. You can
specify only one target status per request. To update sessions to a different
status, send a separate request.

Session status can be updated only for email sessions within the instance that
owns the API token. A session ID for an email session that isn't in the instance
is marked with `"result": "failure"` and `"reason": "not_found"`.

Transitioning a session to `closed` can trigger configured CRM synchronization
for those sessions.

For information about getting session IDs for the email sessions you want to
update, see [Get email sessions and messages](https://docs.cloud.google.com/contact-center/ccai-platform/docs/get-email-sessions-and-messages).

### Valid status transitions

When you specify the target status, you can transition only from a valid source
status to the target status. Any session whose current status isn't a valid
source for the target won't change status and will be marked with `"reason":
"invalid_transition"`.

The following table shows the target statuses that you can specify and the valid
source statuses for each target:

| Target status | Valid source statuses |
|---|---|
| `active` | `unopened`, `reopened`, `paused` |
| `paused` | `active` |
| `resolved` | `active` |
| `closed` | `paused`, `resolved` |

## Update email session status

To update email session status, send a `POST` request to the following endpoint:

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

Include a request body with the following structure:

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

Replace the following:

- `YOUR_CCAAS_HOST`: your CCAI Platform host.

- `SESSION_ID`: a string array of up to 100 email
  session IDs---for example, `["123", "456", "789"]`. Empty values are rejected.

- `NEW_EMAIL_STATUS`: the target status applied to
  every session in the request. Possible values: `active`, `paused`, `resolved`, or `closed`.

Optional: To guard against updating session status for email sessions that
changed after you last read them, include the following field in the request
body:

    {
      "existing_email_status": "EXISTING_EMAIL_STATUS"
    }

Replace `EXISTING_EMAIL_STATUS` with one of the following
statuses: `unopened`, `active`, `paused`, `resolved`, `closed`, or `reopened`.
If you include `existing_email_status` and a session isn't in this status, it
fails with reason `stale_state`.

The output is similar to the following:

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

### Response fields

The `results` array contains the following fields:

- `session_id`: the ID of a session that the request targets.

- `from_status`: the status of the session before the update.

- `to_status`: the status of the session after the update.

- `result`: the outcome of the update. Possible values:

  - `success`: the session status was updated. The result includes
    `from_status` and `to_status`.

  - `failure`: the session status wasn't updated. The result includes
    `reason` and `current_status`.

  - `noop`: the session was already in the target status, so no update was
    needed. The result includes `current_status`.

- `reason`: the reason a status update failed. Possible values:

  - `not_found`: no email session in your instance matches the specified
    session ID. Retrying won't succeed.

  - `invalid_transition`: the session's current status isn't a valid source
    status for the specified target status.

  - `stale_state`: you included `existing_email_status` and the session's
    current status didn't match.

  - `internal_error`: an unexpected error occurred. You can retry the
    request.

- `current_status`: the session's status when the request was processed.

### Error messages

The bulk email status endpoint returns the following error messages:

- `400 Bad Request`: the request body is malformed, `session_ids` is missing
  or empty, `session_ids` exceeds 100 elements, `new_email_status` is missing
  or not an accepted status, or `existing_email_status` isn't a valid status.

- `401 Unauthorized`: authentication failed or the credential isn't an
  `ApiUser` token.

- `404 Not Found`: the endpoint isn't available on your instance.

## What's next

- [Get email sessions and messages](https://docs.cloud.google.com/contact-center/ccai-platform/docs/get-email-sessions-and-messages): locate the sessions that you want to update by querying email interaction records.