# Dialogs — read inbox, reply, compose, search

> **TL;DR for agents:** List + filters: `GET /api/dialogs`. Stats incl. inbox-rate: `GET /api/dialogs/stats`. Read a thread: `GET /api/dialogs/thread/:threadId`. Reply: `POST /api/dialogs/:id/reply`. Compose new: `POST /api/dialogs/compose`. Search by query: `?search=…`.

## List + filter dialogs

Scope: `dialogs:read`. Useful query params: `direction=IN|OUT`, `unread=1`, `attention=1`, `accountId=…`, `companyId=…`, `leadId=…`, `search=…`, `pageSize`, `page`.

```bash
curl -s "https://api.live-direct-marketing.online/api/dialogs?direction=IN&unread=1&pageSize=20" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Search by query (subject / body / from / to)

```bash
curl -s "https://api.live-direct-marketing.online/api/dialogs?search=demo&pageSize=5" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Stats — placement (inbox / spam / unchecked) + attention

Scope: `dialogs:read`. Returns counts the dashboard uses: total, attention (needs reply), drafts (failed sends), pendingSend, byChannel, marking, **placement.{inbox,spam,unchecked}** for outbound deliverability tracking.

```bash
curl -s "https://api.live-direct-marketing.online/api/dialogs/stats" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Read a thread (whole conversation)

```bash
curl -s "https://api.live-direct-marketing.online/api/dialogs/thread/$THREAD_ID" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Reply to a dialog

Scope: `dialogs:write`. Pass `bodyHtml` (HTML allowed). The thread is auto-resolved from the parent dialog.

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/dialogs/$DIALOG_ID/reply" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"bodyHtml":"<p>Thanks — booking a slot now.</p>","sendSmtp":true}'
```

## Compose a brand-new outbound (with attachment)

Scope: `dialogs:write`. Upload the file via `/api/files/upload` first to get `fileId`, then pass it in `attachments[]`.

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/dialogs/compose" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{
    "to":"prospect@example.com","accountId":"$ACCOUNT_ID",
    "subject":"Quick intro","bodyHtml":"<p>Hi — short pitch attached.</p>",
    "attachments":[{"fileId":"$FILE_ID"}]
  }'
```