Endpunkt für Bulk-E-Mail-Status

In diesem Dokument wird der Endpunkt für den Status von Massen-E‑Mails beschrieben: POST /apps/api/v1/email/update_status. Mit diesem Endpunkt können Sie den Status von bis zu 100 E‑Mail-Sitzungen in einen von Ihnen angegebenen Status ändern. Für jede von Ihnen angegebene E‑Mail-Sitzung wird in der Antwort angegeben, ob sie aktualisiert wurde, keine Änderung erforderlich war oder nicht aktualisiert werden konnte, zusammen mit dem Grund. So können Integrationen mit Teilerfolgen umgehen und ermitteln, welche Sitzungen noch Aufmerksamkeit erfordern.

Der Endpunkt für den Status von Massen-E‑Mails unterstützt die folgenden Anwendungsfälle:

  • Sie verwalten eine E‑Mail-Warteschlange mit hohem Volumen und müssen viele Sitzungen gleichzeitig pausieren, auflösen oder schließen.

  • Sie führen einen externen Workflow aus, der E‑Mail-Sitzungen basierend auf Geschäftsregeln ändert, z. B. das Pausieren eines Batches von Sitzungen außerhalb der Geschäftszeiten.

  • Sie möchten einen einzelnen Vorgang, der das Ergebnis jeder E‑Mail-Sitzung meldet, damit Ihre Integration die Sitzungen, die nicht in einen neuen Status übergegangen sind, wiederholen oder abgleichen kann.

Authentifizierung

Informationen zur Authentifizierung finden Sie unter Einfache Authentifizierung.

Endpunkt verwenden

Wenn Sie den Endpunkt für den Status von Massen-E‑Mails aufrufen möchten, geben Sie einen Zielstatus und eine Liste von Sitzungs-IDs für die E‑Mail-Sitzungen an, deren Status Sie aktualisieren möchten. Pro Anfrage kann nur ein Zielstatus angegeben werden. Wenn Sie Sitzungen auf einen anderen Status aktualisieren möchten, senden Sie eine separate Anfrage.

Der Sitzungsstatus kann nur für E‑Mail-Sitzungen in der Instanz aktualisiert werden, die das API-Token besitzt. Eine Sitzungs-ID für eine E‑Mail-Sitzung, die sich nicht in der Instanz befindet wird mit "result": "failure" und "reason": "not_found" gekennzeichnet.

Wenn Sie eine Sitzung in den Status closed versetzen, kann die konfigurierte CRM-Synchronisierung für diese Sitzungen ausgelöst werden.

Informationen zum Abrufen von Sitzungs-IDs für die E‑Mail-Sitzungen, die Sie aktualisieren möchten, finden Sie unter E‑Mail-Sitzungen und ‑Nachrichten abrufen.

Gültige Statusübergänge

Wenn Sie den Zielstatus angeben, können Sie nur von einem gültigen Quellstatus zum Zielstatus wechseln. Der Status von Sitzungen, deren aktueller Status keine gültige Quelle für das Ziel ist, wird nicht geändert und sie werden mit "reason": "invalid_transition" gekennzeichnet.

In der folgenden Tabelle sind die Zielstatus aufgeführt, die Sie angeben können, sowie die gültigen Quellstatus für jedes Ziel:

Zielstatus Gültige Quellstatus
active unopened, reopened, paused
paused active
resolved active
closed paused, resolved

Status der E‑Mail-Sitzung aktualisieren

Wenn Sie den Status der E‑Mail-Sitzung aktualisieren möchten, senden Sie eine POST-Anfrage an den folgenden Endpunkt:

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

Fügen Sie einen Anfragetext mit der folgenden Struktur ein:

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

Ersetzen Sie Folgendes:

  • YOUR_CCAAS_HOST: Ihr CCAI Platform-Host.

  • SESSION_ID: Ein String-Array mit bis zu 100 E‑Mail Sitzungs-IDs, z. B. ["123", "456", "789"]. Leere Werte werden abgelehnt.

  • NEW_EMAIL_STATUS: Der Zielstatus, der auf jede Sitzung in der Anfrage angewendet wird. Mögliche Werte: active, paused, resolved oder closed.

Optional: Wenn Sie verhindern möchten, dass der Sitzungsstatus für E‑Mail-Sitzungen aktualisiert wird, die sich seit dem letzten Lesen geändert haben, fügen Sie das folgende Feld in den Anfragetext ein:

{
  "existing_email_status": "EXISTING_EMAIL_STATUS"
}

Ersetzen Sie EXISTING_EMAIL_STATUS durch einen der folgenden Status: unopened, active, paused, resolved, closed oder reopened. Wenn Sie existing_email_status angeben und eine Sitzung nicht diesen Status hat, schlägt sie mit dem Grund stale_state fehl.

Die Ausgabe sieht etwa so aus:

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

Antwortfelder

Das Array results enthält die folgenden Felder:

  • session_id: Die ID einer Sitzung, auf die sich die Anfrage bezieht.

  • from_status: Der Status der Sitzung vor der Aktualisierung.

  • to_status: Der Status der Sitzung nach der Aktualisierung.

  • result: Das Ergebnis der Aktualisierung. Mögliche Werte:

    • success: Der Sitzungsstatus wurde aktualisiert. Das Ergebnis enthält from_status und to_status.

    • failure: Der Sitzungsstatus wurde nicht aktualisiert. Das Ergebnis enthält reason und current_status.

    • noop: Die Sitzung hatte bereits den Zielstatus, daher war keine Aktualisierung erforderlich. Das Ergebnis enthält current_status.

  • reason: Der Grund, warum eine Statusaktualisierung fehlgeschlagen ist. Mögliche Werte:

    • not_found: In Ihrer Instanz stimmt keine E‑Mail-Sitzung mit der angegebenen Sitzungs-ID überein. Ein Wiederholungsversuch ist nicht erfolgreich.

    • invalid_transition: Der aktuelle Status der Sitzung ist kein gültiger Quellstatus für den angegebenen Zielstatus.

    • stale_state: Sie haben existing_email_status angegeben und der aktuelle Status der Sitzung stimmt nicht überein.

    • internal_error: Ein unerwarteter Fehler ist aufgetreten. Sie können die Anfrage wiederholen.

  • current_status: Der Status der Sitzung, als die Anfrage verarbeitet wurde.

Fehlermeldungen

Der Endpunkt für den Status von Massen-E‑Mails gibt die folgenden Fehlermeldungen zurück:

  • 400 Bad Request: Der Anfragetext ist fehlerhaft, session_ids fehlt oder ist leer, session_ids enthält mehr als 100 Elemente, new_email_status fehlt oder ist kein akzeptierter Status oder existing_email_status ist kein gültiger Status.

  • 401 Unauthorized: Die Authentifizierung ist fehlgeschlagen oder die Anmeldedaten sind kein ApiUser-Token.

  • 404 Not Found: Der Endpunkt ist in Ihrer Instanz nicht verfügbar.

Nächste Schritte