Mailbox insights

GET/api/v1/mailbox/insights
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Patterns in the mailbox over a window (30d, 90d default, 180d or 365d): what needs attention, how fast replies go out, when mail arrives, who you write to most, and clutter. Each block is left out when there is nothing to say. Results are cached; refresh=true recomputes.

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.
503 Insights are busy on this server; try again shortly.

Parameters

NameInTypeDescription
windowquerystring
refreshqueryboolean

Request

GET/api/v1/mailbox/insights
curl -X GET 'https://courier.mailyte.com/api/v1/mailbox/insights' \
  -H 'Authorization: Bearer MAILBOX_TOKEN'

Response

Successful Response

  • dataobject
    • windowobject
      • fromstring
      • tostring
      • messages_consideredinteger
      • cachedboolean
    • attentionobject

      Unanswered and unread mail worth a look.

    • response_timeobject

      How long replies take, both ways.

    • rhythmobject

      Busiest hours and days, in the holder's time zone.

    • relationshipsobject

      Top correspondents.

    • hygieneobject

      Newsletters and clutter.

200application/json
{
  "type": "success",
  "msg": "Insights retrieved successfully",
  "data": {
    "window": {
      "from": "2026-07-13T00:00:00+00:00",
      "to": "2026-10-11T12:00:00+00:00",
      "messages_considered": 1696,
      "cached": true
    },
    "relationships": {
      "top_correspondents": [
        {
          "email": "tunde@example.com",
          "name": "Tunde Bello",
          "messages": 64
        }
      ]
    }
  }
}

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
503Insights are busy on this server; try again shortly.

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