Message Status Callbacks

Receive real-time delivery status updates for your sent messages through webhook callbacks.

Overview

Message status callbacks provide real-time updates about the delivery status of your SMS and email messages. By including a CallbackUrl in your message payload, you'll receive HTTP POST notifications as the message status changes.

Callback Setup

Basic Implementation

Include a CallbackUrl field in your message payload:

{
  "messageData": [{
    "CustomerId": "your-customer-id",
    "Password": "your-api-key",
    "Recipients": [
      {  
        "IdaasId": "PL-123654",
        "SendTo": 1
      }
    ],
    "SMSMessage": "Your message content",
    "CallbackUrl": "https://your-app.com/sms-callback"
  }]
}

Dynamic URL Parameters

Use dynamic parameters in your callback URL to include message-specific information:

{
  "messageData": [{
    "CustomerId": "your-customer-id",
    "Password": "your-api-key",
    "Recipients": [
      {
        "IdaasId": "PL-123654",
        "SendTo": 1
      }
    ],
    "SMSMessage": "Your message content",
    "CallbackUrl": "https://your-app.com/sms-callback?msgid={sentid}&ref={clientref}&status={status}&recipient={recipient}"
  }]
}

Available Parameters

Parameter	Description	Example
{sentid}	Unique message identifier	1469.20250715.02516506506657265717
{contactid}	Contact/recipient identifier	12345
{externalid}	External reference ID	EXT-789
{clientref}	Your ClientRef value	MSG-12345
{recipient}	Recipient phone number/email	+447700900123
{status}	Delivery status	Delivered
{err}	Error message (if applicable)	Invalid number
{units}	Number of SMS units used	2

Callback Payload Examples

Successful Delivery

POST /sms-callback?msgid=1469.20250715.02516506506657265717&status=Delivered
Content-Type: application/json

{
  "MessageId": "1469.20250715.02516506506657265717-e0684dbcb71f402ab39d4d6b86d44cbb",
  "Status": "Delivered",
  "Timestamp": "2025-07-15T17:29:12.1234567Z",
  "Recipient": "+447700900123",
  "ClientRef": "MSG-12345",
  "Units": 1,
  "CustomerId": "your-customer-id"
}

Failed Delivery

POST /sms-callback?msgid=1469.20250715.02516506506657265717&status=Failed
Content-Type: application/json

{
  "MessageId": "1469.20250715.02516506506657265717-e0684dbcb71f402ab39d4d6b86d44cbb",
  "Status": "Failed",
  "Timestamp": "2025-07-15T17:30:45.9876543Z",
  "Recipient": "+447700900123",
  "ClientRef": "MSG-12345",
  "Units": 0,
  "Error": "Invalid destination number",
  "CustomerId": "your-customer-id"
}

Status Types

SMS Status Progression

1. Queued - Message accepted and queued for sending
2. Sent - Message sent to carrier
3. Delivered - Message delivered to recipient
4. Failed - Message delivery failed
5. Expired - Message expired before delivery

Email Status Progression

1. Queued - Email accepted and queued for sending
2. Sent - Email sent to mail server
3. Delivered - Email delivered to recipient's mailbox
4. Bounced - Email bounced (hard or soft bounce)
5. Failed - Email delivery failed