Messages

The landlord portal has a mailbox with the office: threads with a subject, optionally about one apartment, read and answered by both sides. These endpoints give a tool the same mailbox. All need landlord:messages, which is a writing scope — it is not pre-selected when a key is created.

GET /messages

Your threads, newest activity first, with the number of office messages you have not read.

{
  "threads": [
    {
      "id": "01934…",
      "unitId": "0190c…",
      "unitName": "Marina Loft · 2BR",
      "subject": "AC service in October",
      "status": "open",
      "openedBy": "agency",
      "unread": 1,
      "lastMessageAt": "2026-09-02T15:10:00.000Z",
      "createdAt": "2026-09-01T09:30:00.000Z",
      "lastMessage": { "authorSide": "agency", "authorName": "Sara (Marina Stays)", "body": "The technician can come on the 7th…", "createdAt": "2026-09-02T15:10:00.000Z" }
    }
  ],
  "unread": 1
}

GET /messages/:id

The thread with all its messages, oldest first. Reading it marks the office’s messages as read — the same as opening it in the portal.

{
  "thread": { "id": "01934…", "subject": "AC service in October", "status": "open", "unread": 0, "…": "…" },
  "messages": [
    { "id": "…", "authorSide": "agency", "authorName": "Sara (Marina Stays)", "body": "…", "createdAt": "2026-09-01T09:30:00.000Z" },
    { "id": "…", "authorSide": "owner", "authorName": "Hassan Al Mansoori (API)", "body": "…", "createdAt": "2026-09-01T11:02:00.000Z" }
  ]
}

POST /messages

Opens a thread. Messages written through a key are signed with your name and “(API)”, so the office knows a program sent it.

{ "subject": "Question about the August statement", "body": "Line 3 shows…", "unit": "marina-loft-2br" }

Field	Required	Notes
subject	yes	1–200 characters
body	yes	Up to 20,000 characters
unit	no	Unit slug the conversation is about

Response 201 { "id": "…" }. 404 NOT_FOUND when unit is not one of yours.

POST /messages/:id/replies

{ "body": "Thank you, the 7th works." }

Response 201 { "id": "…" }. A reply reopens a closed thread — the office closes what it considers done, and you writing again clearly does not.