Messages API

Outbound activity lives under the workspace.

Flat status (token workspace)

Use these after POST /api/emails or any other send that returned id. A project token sees only its project. The list body is a JSON array; the next page is the X-Next-Cursor header (cursor query).

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/emails/$MESSAGE_ID"

curl -sS -D - -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/emails?limit=50"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/emails/stats?days=30"

GET /api/emails/stats returns sent, delivered, bounced, complained, opened, and clicked (max 90 days).

Get one message

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

GET /api/practices/{id}/messages and GET /api/practices/{id}/messages/search use the same filters. An empty filter returns the recent list.

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/practices/$PRACTICE_ID/messages?limit=50"

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.

messageID on /messages/{messageID}, /timeline, and /events is the Werkmail message UUID (id from the send response). The provider message id is rejected with 400 bad_id (retryable false).

Timeline and events

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

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 over polling for automation.