# Messages API

Outbound activity lives under the workspace.

## Get one message

```bash
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/messages/$MESSAGE_ID"
```

Bodies are omitted unless the caller has `messages.view_content`.

## Search

```bash
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/messages/search?q=termin&limit=50"
```

Filters typically include `tag`, `status`, `route`, date bounds, and free-text `q` (recipient, subject, tag). The dashboard Emails page uses this endpoint.

## Timeline and events

```bash
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/messages/$MESSAGE_ID/timeline"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/messages/$MESSAGE_ID/events"
```

Timeline is the product view (status transitions). Events are the raw delivery-event stream for that message (delivery, open, click, bounce, complaint, delay).

## Statuses

`pending`, `queued`, `processed`, `delivered`, `opened`, `clicked`, `soft_bounced`, `hard_bounced`, `auto_replied`, `spam_complaint`, `failed`, `suppressed`, `unsubscribed`, `delivery_delayed`.

## Workspace activity

```bash
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/events"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/overview"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/rates"
```

Prefer [webhooks](/api/webhooks) over polling for automation.