Reports – Email – single message report
This method returns delivery and engagement metrics for a single sent email. It lets you check key results such as delivered messages, opens, and clicks, together with their percentage rates.
You can view these statistics for the whole message or break them down by domain, domain family, or sending IP. If needed, you can also retrieve basic message details, such as the subject, UTM parameters, and the send date.
Endpoint
GET /reports/email/singleMessage/{id}
Host: https://api.ecdp.app
Request parameters
| Parameter | Type | Required | Description | Allowed values / Notes |
| x-api-key | string | yes | API key for authentication | API key for authentication |
| id | integer | yes | Identifier of the message in ECDP | Path parameter. Must not be empty. |
| startDate | string | conditional | Start of the reporting date range | YYYY-MM-DD. Required for Scenario and Confirmation. Not allowed for Newsletter. |
| endDate | string | conditional | End of the reporting date range | YYYY-MM-DD. Required for Scenario and Confirmation. Not allowed for Newsletter. endDate must be later than startDate. |
| grouping | enum | no | Aggregation level for the response data | Message (default), Domain, DomainFamily, IP |
| domain | string | no | Filter results to a specific recipient domain | Single value, e.g., gmail.com. Cannot be combined with other filters. |
| domainFamily | string | no | Filter results to a domain family | Single value, e.g., gmail. Cannot be combined with other filters. |
| ip | string | no | Filter results to a specific sending IP or IP type | Single value: Premium, Shared, or a specific IP address, e.g., 1.2.3.4. Cannot be combined with other filters. |
| includeDetails | boolean | no | Whether to include message metadata in the response | true or false (default: false). Accepts 1 or 0. |
Filters
Use filters to narrow results to a specific subset of sending traffic. Only one filter type is allowed per request, and each filter accepts exactly one value. Sending multiple filters or multiple values returns 400 Bad Request.
| Filter | Type | Description |
| domain | string | Includes only events for the specified recipient domain, e.g., gmail.com. |
| domainFamily | string | Includes only events for the specified domain family, e.g., gmail. |
| ip | string | Includes only events sent from the specified IP or IP type: Premium, Shared, or a specific address. |
Grouping options
Exactly one grouping value is allowed per request. The grouping determines which column appears in each row of the data[] array.
Default: grouping=Message
| Grouping value | Grouping column in response |
| Message | messageId, messageSubject |
| Domain | domain |
| DomainFamily | domainFamily |
| IP | ip |
Responses
Email report data
Each object in the data array contains exactly one grouping column (determined by the grouping parameter), followed by the KPI fields below.
| Field | Type | Description |
| messageId | string | Present when grouping=Message. |
| messageSubject | string | Email subject. Present when grouping=Message. |
| domain | string | Present when grouping=Domain. |
| domainFamily | string | Present when grouping=DomainFamily. |
| ip | string | Present when grouping=IP. |
| bounced | integer | Number of bounced messages. |
| bouncedPercent | number | Bounces as a share of sent. |
| delivered | integer | Number of successfully delivered messages. |
| deliveredPercent | number | Delivered as a share of sent. |
| opens | integer | Total number of opens (including repeated opens). |
| opensPercent | number | Opens as a share of delivered. |
| uniqueOpens | integer | Number of recipients who opened the message at least once. |
| clicks | integer | Total number of link clicks. |
| clicksPercent | number | Clicks as a share of delivered. |
| uniqueClicks | integer | Number of recipients who clicked at least once. |
| clicksToOpensPercent | number | Clicks as a share of opens. |
| unsubscribes | integer | Number of unsubscribe events. |
| complaints | integer | Number of spam complaints. |
| revenue | number | Revenue attributed to this message. |
| currency | string | Currency code for the revenue value (ISO 4217). |
Message details
Present only when includeDetails=true.
| Field | Type | Description |
| messageId | string | Identifier of the message. |
| type | string | Message type: Newsletter, Scenario, or Confirmation. |
| subject | string | Email subject line. |
| utms[] | array | Array of UTM parameter objects, each with name and value. |
| sentDate | string (ISO-8601 UTC) | Date and time the message was sent. Present only for Newsletter messages. |
Example requests and responses
Newsletter with default grouping and with message details
GET /reports/email/singleMessage/12345?includeDetails=true
Response: OK 200
{
"messageDetails": {
"messageId": "12345",
"type": "Newsletter",
"subject": "February Promo",
"utms": [
{ "name": "utm_source", "value": "newsletter" },
{ "name": "utm_campaign", "value": "feb" }
],
"sentDate": "2025-02-14T10:05:00Z"
},
"data": [
{
"messageId": "12345",
"messageSubject": "February Promo",
"bounced": 20,
"bouncedPercent": 0.002,
"delivered": 9980,
"deliveredPercent": 0.998,
"opens": 5400,
"opensPercent": 0.541,
"uniqueOpens": 4200,
"clicks": 1200,
"clicksPercent": 0.120,
"uniqueClicks": 950,
"clicksToOpensPercent": 0.222,
"unsubscribes": 10,
"complaints": 3,
"revenue": 3500.45,
"currency": "USD"
}
]
}Scenario email message, grouped by domain and filtered to gmail.com
GET /reports/email/singleMessage/123?startDate=2025-03-01&endDate=2025-03-07&grouping=Domain&domain=gmail.com
Response: OK 200
{
"data": [
{
"domain": "gmail.com",
"bounced": 5,
"bouncedPercent": 0.001,
"delivered": 4995,
"deliveredPercent": 0.999,
"opens": 3200,
"opensPercent": 0.640,
"uniqueOpens": 2500,
"clicks": 650,
"clicksPercent": 0.130,
"uniqueClicks": 500,
"clicksToOpensPercent": 0.203,
"unsubscribes": 4,
"complaints": 1,
"revenue": 1780.25,
"currency": "USD"
}
]
}Response codes
| Code | Status | Description |
| 200 | OK | Request processed successfully. Response contains message statistics. |
| 204 | No content | Request is valid, but no data is available for the given parameters. |
| 400 | Bad request | Invalid or missing parameters. Check filter and grouping constraints, date range rules, and required fields. |
| 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. |
Validation and behavior rules
- For Newsletter messages: startDate and endDate are not allowed. Providing them returns 400 Bad Request.
- For Scenario and Confirmation messages: both startDate and endDate are required. Omitting either returns 400 Bad Request.
- Exactly one grouping value is allowed per request. Sending multiple grouping values returns 400 Bad Request.
- Exactly one filter type is allowed per request, with exactly one value. Multiple filters or multiple values return 400 Bad Request.
- includeDetails accepts only true/false (or 1/0). Any other value returns 400 Bad Request.
Reference documentation
Swagger – Reports email