> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Communications

> Every message the platform sends — the delivery tracker, mailbox, chat, and how to diagnose a message that never arrived.

**Operations → Communications**

Every SMS, email and push notification the platform sends lands in one ledger. That is what makes
"did the tenant actually get their invoice?" a question with an answer.

| Surface                       | Route                     | Purpose                                                                                            |
| ----------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
| **Delivery Tracker**          | `/communications/tracker` | Every outbound message and its delivery outcome.                                                   |
| **Mailbox**                   | `/mailbox`                | Email conversations.                                                                               |
| **Chat**                      | `/chat`                   | Direct messaging.                                                                                  |
| **Templates** <sup>Beta</sup> | `/message-templates`      | The templates messages are rendered from. See [Templates & broadcasts](/guides/message-templates). |
| **Notice Board**              | `/lookups/notice-board`   | Property notices. See [Notices & polls](/guides/notices-and-polls).                                |
| **Polls**                     | `/polls`                  | Resident polls.                                                                                    |

## The delivery tracker

The tracker is the operational record of outbound messaging.

| Column                         | Meaning                                                         |
| ------------------------------ | --------------------------------------------------------------- |
| **Channel**                    | SMS, email, WhatsApp, push.                                     |
| **Direction**                  | Outbound or inbound.                                            |
| **Recipient / Recipient name** | Who it went to.                                                 |
| **Sender / Sender address**    | Who it came from.                                               |
| **Subject / Message**          | The content sent.                                               |
| **Message type / Category**    | What kind of message it was.                                    |
| **Source type / Source ID**    | What generated it — an invoice, a payment, a case, a broadcast. |
| **Status**                     | Where it got to (see below).                                    |
| **Attempts / Max attempts**    | Retry state.                                                    |
| **Scheduled at / Next run**    | When it is due to be attempted.                                 |
| **Sent at**                    | When it left.                                                   |
| **Response / Sender response** | What the provider returned.                                     |
| **Batch no**                   | The batch it belonged to, for bulk sends.                       |
| **Sentiment**                  | Where inbound sentiment analysis is enabled.                    |

### Statuses

Messages move through a lifecycle rather than being simply sent or not:

| Status                              | Meaning                                                                |
| ----------------------------------- | ---------------------------------------------------------------------- |
| **Pending / Staged / Queued**       | Accepted, waiting to go.                                               |
| **Processing**                      | Being dispatched.                                                      |
| **Sent**                            | Handed to the provider.                                                |
| **Delivered**                       | Confirmed delivered to the handset or inbox.                           |
| **Read / Viewed / Clicked**         | Engagement, where the channel reports it.                              |
| **Undelivered / Failed / Rejected** | Did not arrive; the response explains why.                             |
| **Delayed / Paused**                | Held.                                                                  |
| **Skipped**                         | Deliberately not sent — for example a recipient with no valid address. |
| **Not required / Not tracked**      | No delivery was expected or is being tracked.                          |

<Warning>
  **Sent is not delivered.** A message handed to a provider can still fail at the network. When a
  resident disputes receiving something, check for **delivered**, not **sent**.
</Warning>

## Diagnosing a message that never arrived

<Steps>
  <Step title="Find it by source">
    Filter by source type and ID — the invoice, payment or case that generated it — rather than
    scrolling by date.
  </Step>

  <Step title="Read the status">
    Skipped means it was never attempted. Failed means it was attempted and rejected.
  </Step>

  <Step title="Read the provider response">
    Most failures name their cause: invalid number, unreachable handset, bounced address, blocked
    sender.
  </Step>

  <Step title="Check the recipient details">
    The address used is recorded on the message. Compare it against the
    [resident record](/guides/residents).
  </Step>

  <Step title="Fix the source, not the message">
    Correcting the resident's phone or email is what fixes the next hundred messages.
  </Step>
</Steps>

## Where messages come from

| Source          | Examples                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------ |
| **Documents**   | Invoice, receipt, statement delivery.                                                      |
| **Collections** | Reminders and demand letters staged by a [strategy](/guides/collections/strategies).       |
| **Promises**    | Reminders ahead of a promised payment date.                                                |
| **Operations**  | Service-request updates, visitor notifications, amenity confirmations.                     |
| **Broadcasts**  | Operator-initiated bulk messages. See [Templates & broadcasts](/guides/message-templates). |
| **System**      | Approval notifications, job outcomes.                                                      |

Because everything lands in one ledger, delivery status is available to every module without each
one building its own tracking.

## Mailbox and chat

* **Mailbox** holds email conversations, with threads and archive.
* **Chat** carries direct messages — operator to operator, and operator to resident where enabled.

Both are conversation surfaces; the tracker is the audit surface. Use chat to talk, use the tracker
to prove.

## Message frequency

Automated messaging can become harassment quickly when several engines each have a reason to write
to the same person. [Collection strategies](/guides/collections/strategies) carry a
**max contacts per week** guard counted across all channels, precisely for this reason. Where you
add new automated messaging, check what else already writes to that audience.

## Common problems

| Symptom                                | Cause                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------ |
| Message skipped                        | Recipient has no valid address for that channel.                         |
| Repeated failures to one number        | Wrong format, or the number is no longer in service.                     |
| Bulk send partially delivered          | Check the batch number and filter by failed within the batch.            |
| Nothing being sent at all              | The dispatch job is off. See [Scheduled tasks](/guides/scheduled-tasks). |
| Tenant received the same message twice | Two sources generated it — check source type on both rows.               |