---
title: "List messages"
method: GET
path: "/api/v1/messages"
tags: ["messages"]
---

# List messages

`GET /api/v1/messages`

Returns up to 100 of the most recent messages on the account's numbers.

## Query parameters

- `numberId` string
- `direction` 'inbound' | 'outbound'
- `since` string, date-time

## Headers

- `Authorization` string, required

## Response `200`

Messages, newest first.

- MessagesListMessagesResponse200
  - `messages` Message[]
    - `id` string
    - `phoneNumberId` string
    - `from` string — Sender in E.164 format.
    - `to` string — Recipient in E.164 format.
    - `body` string
    - `direction` 'inbound' | 'outbound'
    - `channel` 'sms' | 'imessage' | 'rcs' | 'unknown' — The channel the message was delivered on. `sms` for SMS/call numbers. For iMessage numbers, inbound messages report the channel actually used — `imessage`, `rcs`, or `sms`. Outbound iMessage sends report `unknown`, because the iMessage channel does not confirm which channel was ultimately used.
    - `service` 'imessage' | 'rcs' | 'sms' — For iMessage numbers, the confirmed delivery channel. Null for SMS/call numbers (where `channel` already says `sms`). Deprecated — prefer `channel`, which is authoritative.
    - `status` 'sent' | 'delivered' | 'undelivered' | 'failed' | 'unknown' | 'received' — Delivery status. Outbound SMS/call messages start at `sent` and reach a terminal `delivered`, `undelivered`, or `failed`. Outbound iMessage messages are `unknown` (the iMessage channel does not report delivery). Inbound messages are `received`.
    - `statusError` string, nullable — A human-readable reason, present only when `status` is `undelivered` or `failed` (for example, when a carrier rejects the message). Null otherwise.
    - `media` MessageMedia[] — Media attachments on the message, in send order. Empty for plain text messages.
      - `id` string — Public media ID — an unguessable 32-character token.
      - `url` string, uri — Stable public URL serving the media (see Get public media). Safe to use directly as an image source; requires no authentication.
      - `contentType` string — MIME type of the media.
      - `originalUrl` string, nullable — The caller-supplied source URL on outbound messages. Null on inbound messages and when the media was uploaded directly as bytes — inbound media is always served from `url`.
    - `replyToId` string, nullable — ID of the message this one replies or reacts to. Set on messages created via Reply to a message, and on inbound threaded replies and reactions received on iMessage numbers. Null for ordinary messages, or when the target of an inbound reply isn't a message on your account.
    - `reaction` string, nullable — The reaction this message carries — a reaction name (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) or an emoji — when the message is a reaction, sent or received. Null otherwise. A reaction delivered natively has an empty `body`; a reaction delivered as a regular message over SMS carries the emoji in `body` too.
    - `createdAt` string, date-time

## Other responses

- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/versions/cfa621230237/schema)