---
title: "Retrieve a message by ID"
method: GET
path: "/v1/messages/{id}"
tags: ["Messages"]
---

# Retrieve a message by ID

`GET /v1/messages/{id}`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/messages/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Requires `messages:r`.

## Path parameters

- `id` string, required

## Response `200`

The message.

- Message: An SMS message, outbound or inbound. The same shape from the send, the lookup and the list.
  - `id` string, required
  - `direction` 'OUTBOUND' | 'INBOUND', required
  - `from` string, required
  - `to` string, required
  - `body` string, nullable, required: Null once the body is purged (see body_purged) and on a verification OTP, whose code is never stored.
  - `body_purged` boolean, required
  - `status` 'QUEUED' | 'SENDING' | 'SENT' | 'DELIVERED' | 'FAILED' | 'UNDELIVERED' | 'RECEIVED', required
  - `segment_count` integer, nullable, required: Number of SMS parts the carrier split the body into (inbound: as received). Billing is per part.
  - `mode` 'LIVE' | 'TEST', required: TEST messages are simulated: never sent to a carrier and never billed.
  - `is_verification` boolean, required: The OTP SMS behind a verification. Its body is never stored.
  - `auto_reply_keyword` 'STOP' | 'START' | 'HELP' | 'null', nullable, required: Set on the automatic confirmation sent when a recipient texts STOP, START or HELP. You did not send it and are never charged for it. Its body can be null for a few minutes after it is sent, until the carrier reports the text. Null on every other message.
  - `cost_cents` integer, required: What this message actually cost, in cents CAD: message_cost_cents times the parts the carrier split it into, settled to the carrier's count once it accepts the send (so it can differ from a pre-send estimate). 0 when the carrier refused the send outright (refunded or never charged), and on an automatic STOP/START/HELP confirmation (auto_reply_keyword), which is never charged. A message the carrier accepted but could not deliver keeps its charge. Inbound messages carry the inbound charge. On a TEST message this is what the send would have cost; nothing was charged.
  - `error_code` string, nullable, required: Set on FAILED and UNDELIVERED messages: the carrier's code from the delivery receipt (e.g. 30003), or the platform code for a synchronous rejection (CARRIER_ERROR, INVALID_PHONE_NUMBER, NOT_A_MOBILE_NUMBER, INSUFFICIENT_BALANCE). CARRIER_THROTTLED when the carrier asked us to slow down, or dropped the message from the sending number's full queue before trying the recipient: refunded, and safe to send again.
  - `error_message` string, nullable, required: Human-readable reason for a FAILED or UNDELIVERED message, from the carrier when it gave one.
  - `sent_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `casl_consent_type` 'EXPRESS' | 'IMPLIED' | 'null', nullable, required: The CASL consent an outbound send went out on. Null for inbound and test-mode messages, carrier-mandated STOP/HELP/START replies, and sends made before this was recorded (18 September 2026).
  - `dncl_exemption` string, nullable, required: The CRTC Do Not Call List exemption the send relied on, when one applied.
  - `delivered_at` string, date-time, nullable, required: When the carrier reported the message delivered to the handset.

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: The API key lacks the permission this operation requires, or the account is suspended or closed.
- `404`: NOT_FOUND: no such message on this account. A test key finds TEST messages only.
- `429`: Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).
- `500`: Unexpected server error.

---

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