Get a message

GET/v1/messages/{message_id}

Returns one message with its status history. An unknown ID, a malformed ID and another account's ID all return 404.

Scope: messages:read

Request

Every request needs an API key in the Authorization header, and the key needs the scope the endpoint names.

Parameters

message_idpathstringRequired
The message ID, msg_….
- Matches ^msg_[0-9A-HJKMNP-TV-Z]{26}$

Example request

GET /v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP

Responses

200 OK

ReturnsMessageWithHistoryEnvelope

dataMessageWithHistoryRequired
The message with its status history.

Headers

Cache-ControlstringRequired
Responses are never cached.
RateLimit-Limitinteger
Requests per second your account may sustain.
RateLimit-Remaininginteger
Whole requests left in your account's bucket.
RateLimit-Resetinteger
Seconds until the bucket is full again.
X-Request-IdstringRequired
This request's ID, also given as request_id in error bodies. Quote it to support.

Example response

{  "data": {    "id": "msg_01M3KR6CEGVQVV5PV6Q9J1G6SP",    "object": "message",    "amount": "3.2000",    "body": "Your ACME code is 482913. It expires in 5 minutes.",    "campaign_id": null,    "channel": "sms",    "client_reference": "order-78123",    "completed_at": "2026-09-28T10:15:39.870Z",    "created_at": "2026-09-28T10:15:30.000Z",    "currency": "NGN",    "direction": "outbound",    "encoding": "gsm7",    "error": null,    "from": "ACME",    "held_amount": "3.5000",    "mode": "live",    "scheduled_at": null,    "segments": 1,    "sent_at": "2026-09-28T10:15:31.412Z",    "source": "api",    "status": "delivered",    "status_history": [      {        "error": null,        "occurred_at": "2026-09-28T10:15:30.000Z",        "status": "queued"      },      {        "error": null,        "occurred_at": "2026-09-28T10:15:31.412Z",        "status": "sent"      },      {        "error": null,        "occurred_at": "2026-09-28T10:15:39.870Z",        "status": "delivered"      }    ],    "to": "+2348031234567",    "unit_price": "3.2000",    "updated_at": "2026-09-28T10:15:39.870Z"  }}

Errors

Each code links to its page. Branch on the code, never on the title or detail.

401 Unauthorized
- unauthenticated
403 Forbidden
- insufficient_scope
- ip_not_allowed
404 Not Found
- not_found
413 Content Too Large
- payload_too_large
415 Unsupported Media Type
- unsupported_media_type
429 Too Many Requests
- rate_limited
500 Internal Server Error
- internal_error
503 Service Unavailable
- service_unavailable

Code samples

Each sample reads your key from the API_KEY_500CALLS environment variable.

cURL

curl 'https://api.messaging.500calls.com/v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP' \  -H "Authorization: Bearer $API_KEY_500CALLS"

Python

import osimport requestsresponse = requests.get(    "https://api.messaging.500calls.com/v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",    },    timeout=30,)print(response.status_code, response.json())

Node.js

const response = await fetch("https://api.messaging.500calls.com/v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP", {  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,  },});console.log(response.status, await response.json());

PHP

<?php$curl = curl_init('https://api.messaging.500calls.com/v1/messages/msg_01M3KR6CEGVQVV5PV6Q9J1G6SP');curl_setopt_array($curl, [    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),    ],    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;