Check when people are busy

POST/api/v1/mailbox/calendar/free-busy
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Busy periods for colleagues in start–end (at most 31 days). known: false means the server cannot see that person's calendar (usually someone outside the organization): treat it as unknown, never as free.

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.
400 end must be after start, a range over 31 days, or No valid addresses.

Request body

  • attendeesarray<string>required

    Addresses to check.

  • startstringrequired

    ISO 8601.

  • endstringrequired

    ISO 8601, at most 31 days after start.

Request

POST/api/v1/mailbox/calendar/free-busy
curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/calendar/free-busy' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "attendees": [
      "tunde@yourdomain.com"
    ],
    "start": "2026-10-14T08:00:00+01:00",
    "end": "2026-10-14T18:00:00+01:00"
  }'

Response

Successful Response

  • dataarray<object>
    • emailstring
    • knownboolean
    • busyarray<object>
      • startstring
      • endstring
200application/json
{
  "type": "success",
  "msg": "Availability retrieved successfully",
  "data": [
    {
      "email": "tunde@yourdomain.com",
      "known": true,
      "busy": [
        {
          "start": "2026-10-14T10:00:00+01:00",
          "end": "2026-10-14T11:00:00+01:00"
        }
      ]
    }
  ]
}

Returned inside the standard envelope.

Errors

StatusWhen
400`end must be after start`, a range over 31 days, or `No valid addresses`.
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

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