Skip to main content

SMS Campaign Reports & Analytics

SMS campaign reporting provides visibility into message delivery status, DLT compliance outcomes, and overall campaign effectiveness. This guide covers how to retrieve campaign statistics, interpret delivery statuses, analyze failures, and export reports.

Campaign Status Overview​

Every SMS campaign tracks aggregate delivery statistics that update in real time as messages are processed.

Retrieving Campaign Stats​

curl "https://<api_key>:<api_token>@api.exotel.com/v2/accounts/<account_sid>/sms-campaigns/<campaign_id>"

Response:

{
  "response": [{
    "code": 200,
    "status": "success",
    "data": {
      "id": "sms_camp_xyz789",
      "name": "Order Shipment Feb",
      "status": "Completed",
      "stats": {
        "total": 5000,
        "submitted": 4950,
        "delivered": 4720,
        "failed": 230,
        "pending": 0,
        "rejected": 50
      }
    }
  }]
}

Stats Field Reference​

FieldDescription
totalTotal contacts in the campaign
submittedMessages successfully submitted to the telecom operator
deliveredMessages confirmed delivered to the recipient's handset
failedMessages that failed delivery (network error, handset off, etc.)
pendingMessages still being processed or awaiting delivery confirmation
rejectedMessages rejected before submission (DLT mismatch, DND, invalid number)

SMS Delivery Status Lifecycle​

Each SMS message progresses through a series of statuses:

Queued --> Submitted --> Delivered
                     --> Failed (delivery failure)
       --> Rejected (DLT/DND/validation failure)

Detailed Status Codes​

StatusCategoryDescription
queuedIn ProgressMessage is in the send queue
submittedIn ProgressMessage handed off to the telecom operator
deliveredSuccessDelivery confirmed by the recipient's handset
failedTerminalDelivery failed after submission (handset off, network error)
rejectedTerminalMessage rejected before submission (DLT, DND, validation)
expiredTerminalMessage could not be delivered within the validity period

Individual SMS Details​

Retrieve delivery details for individual messages within a campaign:

curl "https://<api_key>:<api_token>@api.exotel.com/v2/accounts/<account_sid>/sms-campaigns/<campaign_id>/sms-details?offset=0&limit=50"

SMS Detail Fields​

FieldDescriptionExample
sms_sidUnique identifier for the messagesm_a1b2c3d4
toRecipient phone number+919876543210
statusCurrent delivery statusdelivered
submitted_atWhen the message was submitted2024-02-15T10:05:32+05:30
delivered_atWhen delivery was confirmed2024-02-15T10:05:35+05:30
error_codeError code if failed/rejectedDLT_TEMPLATE_MISMATCH
error_messageHuman-readable error descriptionMessage body does not match registered template
partsNumber of SMS parts (for long messages)1
costCost in credits for this message1

API Reference: See SMS Campaign SMS Details for complete endpoint documentation.

Pagination​

Results are paginated. Use offset and limit to iterate:

# Page 1
curl "https://.../sms-campaigns/<campaign_id>/sms-details?offset=0&limit=100"

# Page 2
curl "https://.../sms-campaigns/<campaign_id>/sms-details?offset=100&limit=100"

Calculating Key Metrics​

Use campaign data to calculate performance metrics:

MetricFormulaHealthy Range
Delivery Rate(delivered / submitted) x 10092--98%
Rejection Rate(rejected / total) x 100Below 5%
Failure Rate(failed / submitted) x 100Below 8%
Effective Reach(delivered / total) x 10085--95%
Cost per Delivered MessageTotal cost / delivered countVaries by plan
info

Delivery rates above 95% indicate a healthy campaign with clean contact lists and correct DLT configuration. Rates below 90% warrant investigation into failure causes.

Analyzing Delivery Failures​

Common Failure Categories​

CategoryTypical CausesImpactResolution
DLT RejectionTemplate mismatch, Entity ID errorMessage never sentFix template alignment
DND/NDNC BlockRecipient on Do Not Disturb registryPromotional SMS blockedUse transactional type if applicable; remove DND numbers
Invalid NumberWrong format, disconnected numberPermanent failureClean contact list
Network FailureOperator outage, congestionTemporary failureRetry in next campaign
Handset OffRecipient's phone is switched offTemporary failureMessage may deliver when handset is back online (within validity period)
ExpiredDelivery window exceededMessage discardedReduce delay between submit and delivery

DLT-Specific Rejection Codes​

Error CodeDescriptionFix
DLT_TEMPLATE_MISMATCHMessage body does not match the registered templateEnsure variable substitutions produce text matching the template
DLT_ENTITY_NOT_FOUNDEntity ID is not validVerify your DLT Entity ID in the campaign configuration
DLT_TEMPLATE_NOT_FOUNDTemplate ID is not registered or not yet propagatedCheck DLT portal for template approval; wait for propagation
DLT_SENDER_MISMATCHSender ID does not match the template's associated Sender IDUse the Sender ID registered with this template
DLT_BLACKLISTEDEntity or template has been blacklisted by the operatorContact your DLT portal for clarification
tip

If you see a high percentage of DLT_TEMPLATE_MISMATCH errors, test your message substitution with a few sample records first. The most common cause is variable values that introduce characters or formatting that deviate from the template pattern.

Real-Time Monitoring with Webhooks​

SMS Delivery Callback​

Configure sms_status_callback to receive delivery status updates in real time:

{
  "SmsSid": "sm_a1b2c3d4",
  "To": "+919876543210",
  "Status": "delivered",
  "DeliveredAt": "2024-02-15T10:05:35+05:30",
  "ErrorCode": null,
  "CampaignSid": "sms_camp_xyz789"
}

Use cases:

  • Update your CRM with delivery confirmation
  • Trigger follow-up actions for failed deliveries
  • Build a real-time delivery dashboard

Campaign Status Callback​

Configure status_callback for campaign-level events:

{
  "CampaignSid": "sms_camp_xyz789",
  "Status": "Completed",
  "Stats": {
    "total": 5000,
    "delivered": 4720,
    "failed": 230,
    "rejected": 50
  }
}

Use cases:

  • Generate final campaign report
  • Trigger post-campaign analysis workflows
  • Notify stakeholders of campaign completion

Dashboard Reports​

The Exotel dashboard provides visual SMS campaign reporting without API calls.

Accessing SMS Campaign Reports​

  1. Log in to my.exotel.com
  2. Navigate to Campaigns in the left sidebar
  3. Select the SMS tab
  4. Click on a specific campaign for detailed reporting

Dashboard Report Features​

FeatureDescription
Delivery pie chartVisual breakdown of delivered, failed, rejected, and pending
Timeline graphMessages sent over time showing throughput patterns
Contact listSearchable list of all recipients with delivery status
Error summaryGrouped view of failure reasons with counts
Export to CSVDownload the complete campaign report

Exporting Campaign Data​

  1. Open the campaign detail page
  2. Click Export in the top-right corner
  3. Select fields to include (phone number, status, timestamp, error code)
  4. Download the CSV file

The exported CSV contains one row per recipient with delivery status, timestamps, error details, and message cost.

Building Custom Analytics​

Track delivery rates across campaigns to identify trends:

CampaignDateTotalDeliveredDelivery RateNotes
Promo Jan2024-01-1510,0009,20092%Baseline
Promo Feb2024-02-1512,00011,40095%Cleaned list
Promo Mar2024-03-1515,00014,55097%Added DND pre-filter

Error Category Distribution​

Group failures by category to prioritize fixes:

Error CategoryCountPercentageAction
DND blocked12048%Pre-filter DND numbers
Invalid number7530%Improve number validation at collection
Network failure3514%Temporary; no action needed
DLT rejection208%Review template alignment
Total Failures250100%

Time-of-Day Analysis​

Track delivery speed by submission time to find optimal send windows:

Send TimeAvg Delivery TimeDelivery RateNotes
9:00 AM3 seconds96%Low congestion
12:00 PM5 seconds95%Moderate traffic
3:00 PM4 seconds95%Moderate traffic
6:00 PM8 seconds93%Peak hours

Bulk Campaign Details​

For accounts running many campaigns, use the bulk campaign details endpoint to retrieve summary data across multiple campaigns:

curl "https://<api_key>:<api_token>@api.exotel.com/v2/accounts/<account_sid>/sms-campaigns?status=Completed&offset=0&limit=20"

API Reference: See Bulk Campaign Details for filtering and pagination options.

Troubleshooting Report Issues​

IssueCauseSolution
Stats show pending after campaign completedDelivery receipts still being processedWait 15-30 minutes for final delivery confirmations
Delivery count lower than expectedMessages still in operator queueCheck again after the message validity period expires
Webhook not receiving delivery updatesEndpoint returning non-200 responseEnsure webhook endpoint returns HTTP 200 within 5 seconds
CSV export is incompleteExport initiated before campaign completedWait for campaign status to be Completed before exporting
Error codes not showingOperator did not provide detailed failure reasonSome operators return generic failure codes; no additional detail available

Next Steps​