Delivery Status

Message Identifier

messageId is the Notify Africa UUID returned by a single or personalized bulk send.

d9b54c80-8a63-4f8b-83c8-71f2439f5429

Do not use a provider identifier, sender identifier, batch identifier, or legacy numeric value in the status path.

Retrieve Status

curl --request GET \
  "$NOTIFY_API_BASE_URL/api/v1/api/messages/status/d9b54c80-8a63-4f8b-83c8-71f2439f5429" \
  --header "Authorization: Bearer $NOTIFY_SMS_API_KEY"

Example response:

{
  "status": 200,
  "message": "Message status retrieved successfully",
  "timestamp": "2026-09-09T12:20:00.000Z",
  "path": "/api/v1/api/messages/status/d9b54c80-8a63-4f8b-83c8-71f2439f5429",
  "data": {
    "messageId": "d9b54c80-8a63-4f8b-83c8-71f2439f5429",
    "status": "DELIVERED",
    "sentAt": "2026-09-09T12:00:02.000Z",
    "deliveredAt": "2026-09-09T12:00:08.000Z"
  }
}

sentAt and deliveredAt are nullable. A null timestamp means the corresponding provider update has not been recorded.

Status Values

Polling Strategy

1. Store every returned message UUID with your application record.
2. Poll after the send response when a final state is required.
3. Increase the interval between unchanged responses.
4. Stop on DELIVERED or FAILED.
5. Set an application deadline for messages that remain non-terminal.

Notify Africa does not expose an API-key-authenticated SMS callback or webhook endpoint. Do not design the SMS integration around WABA webhook behavior.

Ownership-Safe Errors

Malformed UUIDs, unknown UUIDs, and UUIDs owned by another customer return the same response:

{
  "status": 403,
  "message": "Message not found or not authorized",
  "code": "FORBIDDEN",
  "timestamp": "2026-09-09T12:21:00.000Z",
  "path": "/api/v1/api/messages/status/not-an-owned-message",
  "error": "Message not found or not authorized"
}

This prevents message existence from leaking across customer boundaries. Verify the stored UUID and the API key that created it.