Skip to main content

DLR Processor — Event Schemas

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: API_CONTRACTS · APPLICATION_LOGIC

1. Schema Versioning​

All events carry a schemaVersion field ("1.0"). Breaking changes require a new major version and parallel consumption period of ≥ 30 days.

2. Inbound: sms.dlr.inbound​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/sms.dlr.inbound/v1.json",
  "type": "object",
  "required": ["eventId", "operatorMessageId", "operatorId", "stat", "deliveredAt"],
  "properties": {
    "eventId":           { "type": "string", "format": "uuid" },
    "schemaVersion":     { "type": "string", "const": "1.0" },
    "operatorMessageId": { "type": "string", "maxLength": 64 },
    "operatorId":        { "type": "string", "format": "uuid" },
    "stat":              { "type": "string", "maxLength": 32 },
    "errorCode":         { "type": "string", "maxLength": 32 },
    "deliveredAt":       { "type": "string", "format": "date-time" },
    "sourceAddr":        { "type": "string" },
    "destAddr":          { "type": "string" },
    "rawPayload":        { "type": "object" }
  }
}

Example​

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schemaVersion": "1.0",
  "operatorMessageId": "OP-MSG-20240418-00123",
  "operatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "stat": "DELIVRD",
  "deliveredAt": "2026-04-18T10:23:45Z",
  "destAddr": "+441234567890"
}

3. Outbound: billing.events​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/billing.events/v1.json",
  "type": "object",
  "required": ["eventId", "eventType", "messageId", "accountId", "dlrStatus", "segmentCount", "operatorId", "occurredAt"],
  "properties": {
    "eventId":      { "type": "string", "format": "uuid" },
    "schemaVersion":{ "type": "string", "const": "1.0" },
    "eventType":    { "type": "string", "const": "DLR_TERMINAL" },
    "messageId":    { "type": "string", "format": "uuid" },
    "accountId":    { "type": "string", "format": "uuid" },
    "dlrStatus":    { "type": "string", "enum": ["DELIVERED","FAILED","UNDELIVERED","EXPIRED","REJECTED"] },
    "segmentCount": { "type": "integer", "minimum": 1 },
    "operatorId":   { "type": "string", "format": "uuid" },
    "occurredAt":   { "type": "string", "format": "date-time" }
  }
}

Example​

{
  "eventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "schemaVersion": "1.0",
  "eventType": "DLR_TERMINAL",
  "messageId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "accountId": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "dlrStatus": "DELIVERED",
  "segmentCount": 1,
  "operatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "occurredAt": "2026-04-18T10:23:46Z"
}

4. Outbound: webhook.dispatch​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/webhook.dispatch/v1.json",
  "type": "object",
  "required": ["eventId", "accountId", "messageId", "dlrStatus", "to", "operatorId", "occurredAt"],
  "properties": {
    "eventId":    { "type": "string", "format": "uuid" },
    "schemaVersion": { "type": "string", "const": "1.0" },
    "accountId":  { "type": "string", "format": "uuid" },
    "messageId":  { "type": "string", "format": "uuid" },
    "dlrStatus":  { "type": "string", "enum": ["DELIVERED","FAILED","UNDELIVERED","EXPIRED","REJECTED","UNKNOWN"] },
    "to":         { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" },
    "operatorId": { "type": "string", "format": "uuid" },
    "occurredAt": { "type": "string", "format": "date-time" },
    "metadata":   { "type": "object", "additionalProperties": { "type": "string" } }
  }
}

5. Outbound: sms.dlr.unmatched​

{
  "$schema": "https://schemas.ghasi.io/sms-gateway/sms.dlr.unmatched/v1.json",
  "type": "object",
  "required": ["eventId", "operatorMessageId", "operatorId", "rawStat", "receivedAt", "orphanId"],
  "properties": {
    "eventId":           { "type": "string", "format": "uuid" },
    "schemaVersion":     { "type": "string", "const": "1.0" },
    "operatorMessageId": { "type": "string" },
    "operatorId":        { "type": "string", "format": "uuid" },
    "rawStat":           { "type": "string" },
    "receivedAt":        { "type": "string", "format": "date-time" },
    "orphanId":          { "type": "string", "format": "uuid" }
  }
}