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 GET 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

GET /sms-callback?msgid=1469.20250715.02516506506657265717&status=Delivered

Failed Delivery

GET /sms-callback?msgid=1469.20250715.02516506506657265717&status=Failed

Status Types

SMS Status Progression

1. In Queue - Message accepted and queued for sending
2. Sent - Message sent to carrier
3. Delivered - Message delivered to recipient

• Failed - Message delivery failed
• Expired - Message expired before delivery

Email Status Progression

1. In Queue - Email accepted and queued for sending
2. Submitted - Email sent to mail server
3. Delivered - Email delivered to recipient's mailbox
4. Opened - Email content has been viewed
5. Clicked - Tracked links in the email have been followed

• Dropped - Email delivery was not attempted
• Bounced - Email bounced (hard or soft bounce)
• Failed - Email delivery failed
• Deferred - Email delievery was delayed and will be retried

Push Status Progression

1. In Queue - Notification accepted and queued for sending
2. Submitted - Notification sent to server
3. Delivered - Notification received at the target device

• Device offline - Notification could not be delivered
• Device offline, SMS sent - Notification could not be delivered, an SMS fallback was activated

Eduspot Status Progression

1. In Queue - Timeline accepted and queued for sending
2. Created - Timeline entry added to feed