---
title: "List message delivery logs"
method: GET
path: "/api/v1/message-logs"
tags: ["Message logs"]
---

# List message delivery logs

`GET /api/v1/message-logs`

## Request

- Base URL: `https://www.useboom.ai`
- URL: `https://www.useboom.ai/api/v1/message-logs`
- Auth: HTTP bearer

List the messages your organization sent or received and what happened to each one — delivered, failed, or blocked — with the recipient and the failure reason. The same rows as Settings → Logs, so you can review delivery in bulk instead of opening conversations one at a time.

Statuses are a lifecycle, not a set of outcomes. SENT, DELIVERED and READ all mean the message went out; they differ only in how far it got. SENT means it left Boom and no receipt has come back yet. To count what you sent, ask for all three — asking for SENT alone returns only the ones still unconfirmed.

How far a message can get depends on the channel. WhatsApp reaches READ. Email never does: there is no read receipt, so an email resting at DELIVERED is fully settled. PENDING on an inbound message is normal and permanent — nobody sends a receipt for a message a customer wrote to you.

This is a log of messages, not a delivery-rate report. A few send failures never create a row at all, so an absent message is not proof that nothing was attempted.

## Query parameters

- `status` union: Keep only these statuses. Omit for every status. Several as a list, or over HTTP as one comma-separated value: `?status=SENT,DELIVERED,READ`.
  - 'PENDING' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED'
  - string[]
  - string
- `channel` union: Keep only these channels. Omit for every channel. Several as a list, or over HTTP as one comma-separated value: `?channel=WHATSAPP,SMS`.
  - 'WHATSAPP' | 'EMAIL' | 'SMS' | 'VOICE' | 'WEB_CHAT' | 'WEB_WIDGET' | 'FACEBOOK_MESSENGER' | 'INSTAGRAM'
  - string[]
  - string
- `direction` 'INBOUND' | 'OUTBOUND': Defaults to OUTBOUND — a delivery status only means something for a message you sent. Pass INBOUND for what customers sent you.
- `createdAfter` string: Only messages created at or after this moment. A date (2026-08-01) or a full ISO 8601 timestamp.
- `createdBefore` string: Only messages created at or before this moment. A date (2026-08-01) or a full ISO 8601 timestamp.
- `search` string: Match the recipient's name, phone or email address. A phone matches in any format. Over MCP, refused with sensitive_field when the organization hid any of those fields.
- `limit` integer: Page size, up to 1000.
- `cursor` string: Opaque cursor from a previous page.

## Response `200`

Success

- object
  - `range` object, required: The window these rows actually cover. Quote it alongside any count you report — with no dates given the read covers a recent window, not all time.
    - `from` string, nullable, required
    - `to` string, nullable, required
  - `data` object[], required
    - `id` string, required
    - `direction` 'INBOUND' | 'OUTBOUND', required
    - `channel` 'WHATSAPP' | 'EMAIL' | 'SMS' | 'VOICE' | 'WEB_CHAT' | 'WEB_WIDGET' | 'FACEBOOK_MESSENGER' | 'INSTAGRAM', nullable, required: Which channel carried the message. Statuses do not mean the same thing on every channel — see `status`.
    - `status` 'PENDING' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED', required
    - `createdAt` string, required: ISO 8601 timestamp.
    - `sentAt` string, nullable, required
    - `deliveredAt` string, nullable, required
    - `readAt` string, nullable, required
    - `failedAt` string, nullable, required
    - `errorMessage` string, nullable, required: Why it failed, in words. Populated for email (from the bounce or complaint notice); usually null on WhatsApp, where `errorCode` is what you get.
    - `errorCode` union, required: The provider's numeric failure code on WhatsApp. The ones you will actually see: 63024 — the number is not reachable on WhatsApp (wrong number, or it never had an account); 63049 — the recipient's provider chose not to deliver a marketing message; 63032 — the recipient has blocked this business; 63050 — the business is not allowed to message this recipient. Any other code is passed through as-is. Null on rows sent before codes were recorded, which is not a data error.
      - string
      - number
    - `imported` boolean, required: Carried over from a previous system rather than sent by Boom, so its status reflects whatever that system last knew and will never settle further.
    - `recipient` object, required
      - `name` string, nullable, required
      - `phone` string, nullable, required
      - `email` string, nullable, required: Read the handle that matches the row's channel: the email address on an email row, the phone on a WhatsApp or SMS one.
  - `next_cursor` string, nullable, required

## Other responses

- `400`: Validation failed or the request cannot proceed.
- `401`: Missing, malformed, or revoked API key.
- `404`: The resource does not exist in this organization.
- `409`: Conflicts with the current state (duplicates, wrong lifecycle state).
- `422`: The request is well-formed but semantically invalid.
- `429`: Rate limit exceeded — retry after `Retry-After`.
- `500`: Internal server error.
- `503`: Transient error — retry with a narrower request.

## Changes

- **2026-11-03** `7c7a773b12ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/message-logs/get.md)

---

[API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)