Sort emails into categories with AI

POST/api/v1/mailbox/ai/classify
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Labels a batch of messages as primary, newsletter, promotion, social, notification, finance, travel, action_required or other. Only when capabilities.ai is true and the holder has accepted the AI terms (POST /ai/consent).

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
502 The AI service did not answer usefully.

Request body

  • itemsarray<object>required

    The messages to sort: each an id, its subject and a preview.

    • idstringrequired
    • subjectstring
    • previewstring

Request

POST/api/v1/mailbox/ai/classify
curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/ai/classify' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "id": "INBOX:4821",
        "subject": "Your invoice for October",
        "preview": "Amount due: ₦84,000"
      }
    ]
  }'

Response

Successful Response

  • dataobject
    • itemsarray<object>
      • idstring
      • labelstring
      • confidencenumber
    • labelsarray<string>
    • ai_calls_remaininginteger
200application/json
{
  "type": "success",
  "msg": "Messages classified",
  "data": {
    "items": [
      {
        "id": "INBOX:4821",
        "label": "finance",
        "confidence": 0.93
      }
    ],
    "labels": [
      "primary",
      "newsletter",
      "promotion",
      "social",
      "notification",
      "finance",
      "travel",
      "action_required",
      "other"
    ],
    "ai_calls_remaining": 44
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
422Validation Error
502The AI service did not answer usefully.

Every status, with what causes it and what to do, is on the error reference.