Get message status

Check the delivery status of a sent message.

GET  /api/v1/sms/status/:message_id  · Permission: sms.read

Request

cURL

curl https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67 \
  -H "X-API-Key: $API_KEY"

Node.js

const res = await fetch('https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.API_KEY },
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.error_code}: ${err.description}`);
}
const data = await res.json();
console.log(data);

Python

import os
import requests

res = requests.get(
    "https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67",
    headers={"X-API-Key": os.environ["API_KEY"]},
)
res.raise_for_status()
print(res.json())

PHP

<?php
$ch = curl_init('https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('API_KEY')],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new Exception("HTTP $status: $response");
}
$data = json_decode($response, true);
print_r($data);

Ruby

require "net/http"
require "json"

uri = URI("https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("API_KEY")

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)

puts JSON.parse(res.body)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67"))
    .header("X-API-Key", System.getenv("API_KEY"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, err := http.NewRequest("GET", "https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

  res, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

.NET

using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key",
    Environment.GetEnvironmentVariable("API_KEY"));

var response = await client.GetAsync("https://restlink23telecom.com/api/v1/sms/status/api_42_1743667200123456789_a3f8b2c1d9e45f67");

response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Message ID format

api_{user_id}_{nanosecond_timestamp}_{16_char_hex} — for example api_42_1743667200123456789_a3f8b2c1d9e45f67. You receive it in the send response.

Response

200 OK

{
  "status": true,
  "message": {
    "message_id": "api_42_1743667200123456789_a3f8b2c1d9e45f67",
    "telecom_message_id": "6946d0f5-040b-106e-42c7-49026f2b5bc1",
    "recipient": "+14155551234",
    "segments": 1,
    "message": "Your verification code is 847291",
    "sender_id": "MyApp",
    "status": "DELIVRD",
    "status_code": "000",
    "cost": 0.0085,
    "created_at": "2026-02-13T10:30:00Z",
    "delivered_at": "2026-02-13T10:30:04Z"
  }
}

Returns 404 NOT_FOUND if the message does not exist or belongs to another account.

Status values

Status	Description	Final?
pending	Queued, waiting to send	No
sent	Submitted to carrier network	No
DELIVRD	Delivered to recipient’s handset	Yes
UNDELIV	Delivery failed (invalid number, phone off)	Yes
REJECTD	Rejected by carrier (filtered, blacklisted)	Yes
EXPIRED	Delivery timed out	Yes
UNKNOWN	Final status unknown	Yes
failed	Internal error (queue/config failure)	Yes

See delivery statuses for typical status flows.

Polling guidance

If you poll instead of using webhooks:

• Poll every 3–5 seconds, stop on any final status.
• Give up after a few minutes and treat the message as in-flight — some carriers report late; the hourly reconciliation will finalize stuck messages.
• Prefer webhooks for anything beyond low-volume testing: they remove polling load and deliver statuses the moment carriers report them.