Retrieve Message
GET
api.ziett.co/c/v1 /messages/{message_id}
Fetch the complete execution and routing details of a specific message using its unique identifier. This endpoint is crucial for auditing individual communications, inspecting transaction costs, tracking carrier delivery timestamps, or debugging delivery failures via network error codes.
To query and browse multiple records with custom filter subsets instead, see List Messages.
Request
Required scope: apikey:messages:read
Path Parameters
| Parameter | Type | Description |
|---|---|---|
message_id | uuid | The unique UUID v7 tracking identifier assigned to the message during ingestion. |
Examples
import httpx
message_id = "019b4b56-e704-7c30-83a0-527df63c3e00"
response = httpx.get(
f"[https://api.ziett.co/c/v1/messages/](https://api.ziett.co/c/v1/messages/){message_id}",
headers={
"X-API-KEY": "zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}
)
print(response.json())
curl -X GET "[https://api.ziett.co/c/v1/messages/019b4b56-e704-7c30-83a0-527df63c3e00](https://api.ziett.co/c/v1/messages/019b4b56-e704-7c30-83a0-527df63c3e00)" \
-H "X-API-KEY: zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
const messageId = "019b4b56-e704-7c30-83a0-527df63c3e00";
const response = await fetch(`https://api.ziett.co/c/v1/messages/${messageId}`, {
method: "GET",
headers: {
"X-API-KEY": "zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
const data = await response.json();
console.log(data);
Responses
200 OK — Message Details Retrieved
The resource was located successfully within your organization's record logs.
{
"id": "019b4b56-e704-7c30-83a0-527df63c3e00",
"organization_id": "019b4b56-ab10-7210-81a1-527df63c3111",
"billing_account_id": "019b4b56-bc20-7315-92b2-627df63c3222",
"campaign_id": "019b4b56-cd30-7420-a3c3-727df63c3333",
"contact_id": "019b4b56-fa21-7210-91b1-127df63c3eef",
"sms_remitter_id": "019b4b56-de40-7530-b4d4-827df63c3444",
"sms_remitter": {
"id": "019b4b56-de40-7530-b4d4-827df63c3444",
"name": "InfoZiett"
},
"external_id": "client_ref_981242",
"channel_type": "SMS",
"channel_destination": "UNITEL",
"provider_name": "UNITEL_DIRECT",
"e164_format": "+244990090990",
"content": "Your validation protocol code is 99201.",
"trigger_source": "API",
"cost": "15.000000",
"is_refunded": false,
"status": "DELIVERED",
"error_code": null,
"created_at": "2026-05-14T10:30:00.000000+00:00",
"updated_at": "2026-05-14T10:30:04.000000+00:00"
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | uuid | Unique UUID v7 tracking identifier for this message. |
organization_id | uuid | The organization owner account ID that triggered this communication. |
billing_account_id | uuid | The specific balance account debt-linked to this transaction. |
campaign_id | uuid | null | Populated if this individual single dispatch belonged to a parent batch execution instance. |
contact_id | uuid | null | Reference mapping token pointing to the recipient's internal CRM record ledger. |
sms_remitter_id | uuid | null | The exact approved Sender ID configuration identifier used for delivery. |
sms_remitter | object | null | Embedded sub-object detailing basic name parameters of the SMS Sender ID signature. |
external_id | string | null | An optional lookup reference string mapping passed by your system during ingestion. |
channel_type | string | The message structure layer medium format classification choice (SMS, WHATSAPP). |
channel_destination | string | The destination network provider operator routing map (e.g., UNITEL, AFRICELL_AO). |
provider_name | string | null | Internal partner integration gateway handler used to drop the payload over the network. |
e164_format | string | Recipient destination phone target sanitized under E.164 standardization format rules. |
content | string | The text string content body dispatched over the carrier lines. |
trigger_source | string | Origin pipeline vector execution structure context (API_CLIENT,CUSTOMER_PORTAL). |
cost | string | Decimal formatted financial cost consumed on account balance to process this message. |
is_refunded | boolean | Flag pointing out if a delivery failure reversed balance transactions back to your wallet. |
status | string | The exact real-time network state (PENDING, SENT, DELIVERED, FAILED, UNDELIVERED, EXPIRED, REJECTED, CANCELLED). |
error_code | string | null | Categorized error identifier value indicating the reason behind structural delivery blockages. |
created_at | datetime | Precise timestamp marking when the transaction was securely received by the API. |
updated_at | datetime | Precise timestamp marking the latest carrier tracking updates or state transitions. |
401 Unauthorized — Invalid API Key
The X-API-KEY header verification layer check failed.
{
"code": "AUTH_INVALID_API_KEY",
"message": "The provided API key is invalid or has been revoked.",
"status": 401,
"trace_id": "b2c3d4e5f644358a9e7011c123c831a1",
"timestamp": "2026-05-14T10:30:00.000000+00:00",
"service": "core"
}
404 Not Found — Message Not Found
The requested tracking ID does not exist, or it belongs to a different organization account workspace.
{
"code": "NOT_FOUND",
"message": "The requested message resource could not be found.",
"status": 404,
"trace_id": "c3d4e5f644358a9e7011c123c831a1b2",
"timestamp": "2026-05-14T10:30:00.000000+00:00",
"service": "core"
}
422 Unprocessable Entity — Validation Error
The provided message_id variable path value fails standard validation compliance patterns (e.g., malformed UUID structure).
{
"code": "VALIDATION_ERROR",
"message": "One or more fields failed validation.",
"status": 422,
"trace_id": "f812a3bc91e044358a9e7011c456d901",
"timestamp": "2026-05-14T10:30:00.000000+00:00",
"service": "core",
"fields": {
"message_id": "Value must conform to a valid UUID v7 format rule pattern structure."
}
}
Related Endpoints
- List Messages — Browse and audit historical data with multi-variable filters.
- Send Message — Trigger a new high-priority message dispatch transaction immediately.