DEV Community

BridgeXAPI
BridgeXAPI

Posted on

SMS API returned success but the message never arrived: track SMS delivery in Python

#python #api #backend #sms

SMS API returned success but the message never arrived.

Your request succeeded.

The API returned success.

But that does not mean the message was delivered.

Most SMS APIs stop at submission.

You get a success response, but that usually only means:

  • the request was accepted
  • the message entered the queue
  • the provider took control

What happens after that is often hidden.

The problem

Submission is not delivery.

Without delivery tracking:

  • you don’t know if the message actually arrived
  • you can’t explain missing messages
  • you can’t inspect message state after send
  • you can’t debug delivery failures properly

You are blind after the API call.

What this example does

This example shows how to send an SMS, capture the returned bx_message_id, and use it to track delivery status with BridgeXAPI.

That means you can follow the message after submission.

Python example 

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://hi.bridgexapi.io"

response = requests.post(
    f"{BASE_URL}/api/v1/send_sms",
    headers={
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "route_id": 1,
        "caller_id": "BRIDGEXAPI",
        "numbers": ["31612345678"],
        "message": "Delivery test",
    },
    timeout=30,
)

data = response.json()
print(data)

bx_message_id = data["messages"][0]["bx_message_id"]
print("BX ID:", bx_message_id)
Enter fullscreen mode Exit fullscreen mode

Track delivery status

Once you have the bx_message_id, request delivery status directly:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://hi.bridgexapi.io"
BX_MESSAGE_ID = "BX-22559-7c840d813121b159"

dlr_response = requests.get(
    f"{BASE_URL}/api/v1/dlr/{BX_MESSAGE_ID}",
    headers={"X-API-KEY": API_KEY},
    timeout=30,
)

print(dlr_response.json())
Enter fullscreen mode Exit fullscreen mode

Example lifecycle 

Send → status: success
↓

Message object → status: QUEUED
↓

DLR lookup via bx_message_id → DELIVERED or FAILED
Enter fullscreen mode Exit fullscreen mode

Success does not mean delivery.

It means the message entered the system.

Real send response

A real submission can look like this:

{
  "status": "success",
  "message": "SMS batch accepted via route 1",
  "order_id": 22559,
  "route_id": 1,
  "count": 1,
  "messages": [
    {
      "bx_message_id": "BX-22559-7c840d813121b159",
      "msisdn": "31651860670",
      "status": "QUEUED"
    }
  ],
  "cost": 0.088,
  "balance_after": 201.88
}
Enter fullscreen mode Exit fullscreen mode

This shows:

  • submission succeeded
  • the message has a unique execution ID
  • the current state is QUEUED, not final delivery

Why bx_message_id matters

The bx_message_id is the link between submission and execution.

It lets you inspect what happened after the message was sent.

Without it, delivery becomes guesswork.

What this exposes

Instead of stopping at a generic success response, you can inspect:

  • queue state
  • delivery status
  • per-message execution
  • full lifecycle after send

You are no longer guessing.

You are observing.

Why this matters

In most systems:

Success = request accepted

Not:

Success = message delivered

That difference is critical.

Closing

Most SMS APIs tell you when a request was accepted.

This lets you see what actually happens after that.

This is not about sending.

This is about delivery observability.

Next

→ estimate cost before sending

→ debug failed SMS

→ build OTP flows

Top comments (0)