Aller au contenu principal

Asynchronous Mail Classification API

This API allows you to classify emails asynchronously. It behaves exactly like the synchronous classification endpoint but returns immediately with a process ID, so the result can be fetched later.

Ideal when you want to avoid waiting for classification to complete in real time.

Processing may take from a few seconds up to 1–2 minutes depending on the model used and system load.

1. Submit a mail for asynchronous classification​

POST /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/classification-async

Initiates the asynchronous classification of an email.

Path Parameters​

  • companyCuid (string) – Your company identifier.
  • orchestratorCuid (string) – The orchestrator identifier.

Request Body (MailClassificationAsyncParameters)​

{
  "mail": {
    "subject": "Request for refund",
    "body": "Hi, I would like to request a refund for my recent order..."
  },
  "external_ref": "123-azd-456",
  "external_metadata": {
    "customer_id": "abc-789"
  }
}

Response (TextProcessOutput)​

{
  "process_cuid": "f45sz0ho8rcl"
}

Use the returned process_cuid to retrieve the classification result later.

2. Retrieve the classification result​

GET /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/classification-async/{processCuid}

Fetch the result of a previously submitted asynchronous classification.

Path Parameters​

  • companyCuid (string) – Your company identifier.
  • orchestratorCuid (string) – The orchestrator identifier.
  • processCuid (string) – The process ID returned by the submission endpoint.

Response (MailClassificationAsyncOutput)​

{
  "status": "completed",
  "result": {
    "classification": "refund_request",
    "confidence": 0.92
  },
  "external_ref": "123-azd-456",
  "external_metadata": {
    "customer_id": "abc-789"
  }
}

Possible status values​

  • "started" – Processing has begun.
  • "completed" – Classification is done, result is available.
  • "failed" – An error occurred during processing.

If status is not "completed", the result field will be null.

About external_ref and external_metadata​

Both external_ref and external_metadata are optional fields that allow you to associate internal references to the classification request.

These values are not used in the classification process but are:

  • Stored when the classification is submitted.
  • Returned unchanged when you retrieve the result.

This makes it easier to match the classification output with your own internal systems (e.g., end-user identifiers, message IDs, or customer context).

Example usage​

"external_ref": "user-xyz-456",
"external_metadata": {
  "thread_id": "email-12345",
  "source": "support_portal"
}