Messages

Retrieve a message by ID

Requires messages:r.

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

Path parameters

idstring required

Response

The message.

idstring required
direction'OUTBOUND' | 'INBOUND' required
fromstring required
tostring required
bodystring nullable required

Null once the body is purged (see body_purged) and on a verification OTP, whose code is never stored.

body_purgedboolean required
status'QUEUED' | 'SENDING' | 'SENT' | 'DELIVERED' | 'FAILED' | 'UNDELIVERED' | 'RECEIVED' required
segment_countinteger 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_verificationboolean 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_centsinteger 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_codestring 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_messagestring nullable required

Human-readable reason for a FAILED or UNDELIVERED message, from the carrier when it gave one.

sent_atstring date-time nullable required
created_atstring 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_exemptionstring nullable required

The CRTC Do Not Call List exemption the send relied on, when one applied.

delivered_atstring date-time nullable required

When the carrier reported the message delivered to the handset.

Changes

No recorded changes to this operation across all 1 revision of this API.