Reports – SMS – single message report

This method returns delivery and engagement statistics for a single newsletter or scenario SMS message. Use it to retrieve metrics such as sent count, delivery rate, clicks, and revenue for a specific message.

Endpoint

GET reports/sms/singleMessage/{id}

Host: https://api.ecdp.app

Request parameters

Parameter	Location	Type	Required	Description	Allowed values / Notes
x-api-key	header	string	yes	API key for authentication	Available in Settings > API
id	path	integer	yes	Identifier of the SMS message in ECDP	Path parameter. Must not be empty.
includeDetails	query	integer	no	Whether to include message metadata in the response	0 (default) or 1
startDate	query	string	conditional	Start of the reporting date range	YYYY-MM-DD. Required for Scenario messages. Must not be used for Newsletter messages.
endDate	query	string	conditional	End of the reporting date range	YYYY-MM-DD. Required for Scenario messages. Must not be used for Newsletter messages. endDate must be later than startDate.
sender	query	string	no	Filter results to a specific sender name.	Only one filter type is allowed per request. Providing multiple filters or multiple values returns 400 Bad Request.
grouping	query	string	no	Aggregation level for the response data.	Message (default), Sender. Exactly one grouping value is allowed per request. Providing multiple grouping values returns 400 Bad Request.
messgeDetails	query	boolean	no	Lists message details in the response	True or false (default)

Grouping options

Exactly one grouping value is allowed per request. The default is grouping=Message.

Grouping value	Grouping column in response
Message	messageId, messageName
Sender	sender

Response

The response contains the following data depending on used filters

SMS message details

Present only when includeDetails=1.

Field	Type	Description
messageId	string	Identifier of the SMS message
name	string	Message name as configured in ECDP
type	string	Message type: Newsletter or Scenario
sender	string	Sender name displayed to recipients
sentDate	string	Date and time the message was sent. Format: YYYY-MM-DD
utms[]	array	UTM tracking parameters. Each item contains name and value.

SMS report data

Each object in the array represents one row of aggregated statistics, determined by the selected grouping.

Field	Type	Description
messageId	string	Present when grouping=Message
messageName	string	Present when grouping=Message
sender	string	Present when grouping=Sender
sent	integer	Total number of SMS messages submitted for delivery
partsSent	integer	Total number of SMS parts sent (a long message may count as multiple parts)
bounced	integer	Number of messages that failed to deliver
bouncedPercent	number	Bounced / sent. Returns 0.0 if sent = 0.
delivered	integer	Number of messages confirmed as delivered
deliveredPercent	number	Delivered / sent. Returns 0.0 if sent = 0.
clicks	integer	Total number of link clicks
clicksPercent	number	Clicks / sent. Returns 0.0 if sent = 0.
clickers	integer	Number of unique recipients who clicked at least one link
clicksToDeliveredPercent	number	Clicks / delivered. Returns 0.0 if delivered = 0.
unsubscribes	integer	Number of recipients who opted out after receiving this message
revenue	number	Total attributed revenue from this message
currency	string	Currency code for the revenue value (ISO 4217)

Response codes

Code	Status	Description
200	OK	Request processed successfully. Response contains message statistics.
204	No content	Request is valid but no data matches the specified parameters.
400	Bad request	Invalid or missing parameters. Check date range rules, filter, and grouping constraints.
401	Unauthorized	API key is missing, invalid, or expired. Verify your key in Settings > API.
403	Forbidden	Your API key does not have permission to access this resource.
500	Internal server error	Server-side error. Retry the request or contact support if the issue persists.

Example requests and responses

Get details of a specific newsletter message

Request:

GET /reports/sms/singleMessage/8421?includeDetails=1

Response: 200 OK

{
  "messageDetails": {
    "messageId": "8421",
    "type": "Newsletter",
    "name": "my SMS message",
    "sender": "SHOPNOW",
    "sentDate": "2025-01-18T09:30:00Z",
    "utms": [
      { "name": "utm_source", "value": "sms" },
      { "name": "utm_campaign", "value": "winter_sale" }
    ]
  },
  "data": [
    {
      "messageId": "8421",
      "messageName": "my SMS message",
      "sent": 10000,
      "partsSent": 11250,
      "bounced": 15,
      "bouncedPercent": 0.0015,
      "delivered": 9985,
      "deliveredPercent": 0.9985,
      "clicks": 720,
      "clicksPercent": 0.0720,
      "clickers": 610,
      "clicksToDeliveredPercent": 0.0721,
      "unsubscribes": 22,
      "revenue": 5140.90,
      "currency": "USD"
    }
  ]
}

Get scenario message details according to a selected date range and sender filter

Request:

GET /reports/sms/singleMessage/301?startDate=2025-03-01&endDate=2025-03-07&sender=ECOMMERCE

Response: 200 OK

{
  "data": [
    {
      "messageId": "301",
      "messageName": "my SMS message",
      "sent": 5200,
      "partsSent": 5650,
      "bounced": 6,
      "bouncedPercent": 0.0012,
      "delivered": 5194,
      "deliveredPercent": 0.9988,
      "clicks": 390,
      "clicksPercent": 0.0751,
      "clickers": 335,
      "clicksToDeliveredPercent": 0.0755,
      "unsubscribes": 11,
      "revenue": 1896.40,
      "currency": "USD"
    }
  ]
}

Validation and behavior rules

id must reference an existing SMS message in ECDP.
includeDetails accepts only 0 or 1. Any other value returns 400 Bad Request.
Newsletter messages do not support date range filtering. Providing startDate or endDate for a Newsletter message returns 400 Bad Request.
Scenario messages require both startDate and endDate. Omitting either returns 400 Bad Request.
When both date parameters are provided: startDate must be less than or equal to endDate.
Only one grouping value is allowed per request. Multiple grouping values return 400 Bad Request.
Only one filter type is allowed per request, with exactly one value. Multiple filters or multiple values return 400 Bad Request.
Division by zero in any percentage field returns 0.0.

Reference documentation

Swagger – Reports SMS

https://api.ecdp.app/swagger/index.html