Insights
Analytics API
3 endpoints under https://api.mailneo.co/api/v2. Every request carries your key in the X-API-Key header. The scope used here: analytics:read. Each endpoint below states the one it requires. Start with the guide →
getAnalyticsOverviewDelivery and engagement totals
Event counts by type over a period, optionally narrowed to one campaign. Defaults to the last 30 days; the window may not exceed 366 days.
These are EVENT counts, not unique recipients — one person opening a message five times contributes five to opened. No rates are published for that reason; compute them yourself if you know how you want them denominated.
/analytics/overviewanalytics:readExample request
curl "https://api.mailneo.co/api/v2/analytics/overview" \ -H "X-API-Key: $MAILNEO_API_KEY"
Authorization
- Required scope
analytics:read. A key without it is refused before the endpoint runs.- Credential
X-API-Key: mk_live_...Authorization: Bearer mk_live_...
Query parameters3
| Name | Type | Required | Notes |
|---|---|---|---|
| start | string · date-time | No | ISO 8601 |
| end | string · date-time | No | ISO 8601 |
| campaign_id | string | No | max 64 chars |
Response · 200
Success
data
| Field | Type | Always present | Notes |
|---|---|---|---|
| object | "analytics_overview" | Yes | |
| period_start | string | Yes | |
| period_end | string | Yes | |
| events | object | Yes | |
| events.delivered | number | Yes | |
| events.opened | number | Yes | |
| events.clicked | number | Yes | |
| events.bounced | number | Yes | |
| events.soft_bounced | number | Yes | |
| events.complained | number | Yes | |
| events.unsubscribed | number | Yes | |
| events.deferred | number | Yes | |
| events.dropped | number | Yes | |
| events.spam_reported | number | Yes |
meta
| Field | Type | Always present | Notes |
|---|---|---|---|
| request_id | string | Yes |
getAnalyticsDevicesDevice, OS and browser breakdown
Where recipients engaged from, by volume. Counts OPEN and CLICK events only — every other event type is generated server-side and carries no user agent, so including them would add a large unknown bucket that means "not applicable" rather than "could not be parsed".
Values that could not be parsed are reported as unknown rather than dropped, so the buckets sum to the engagement-event total.
/analytics/devicesanalytics:readExample request
curl "https://api.mailneo.co/api/v2/analytics/devices" \ -H "X-API-Key: $MAILNEO_API_KEY"
Authorization
- Required scope
analytics:read. A key without it is refused before the endpoint runs.- Credential
X-API-Key: mk_live_...Authorization: Bearer mk_live_...
Query parameters3
| Name | Type | Required | Notes |
|---|---|---|---|
| start | string · date-time | No | ISO 8601 |
| end | string · date-time | No | ISO 8601 |
| campaign_id | string | No | max 64 chars |
Response · 200
Success
data
| Field | Type | Always present | Notes |
|---|---|---|---|
| object | "analytics_devices" | Yes | |
| period_start | string | Yes | |
| period_end | string | Yes | |
| devices | object[] | Yes | |
| devices[].device_type | string | Yes | |
| devices[].events | number | Yes | |
| operating_systems | object[] | Yes | |
| operating_systems[].os | string | Yes | |
| operating_systems[].events | number | Yes | |
| browsers | object[] | Yes | |
| browsers[].browser | string | Yes | |
| browsers[].events | number | Yes |
meta
| Field | Type | Always present | Notes |
|---|---|---|---|
| request_id | string | Yes |
getAnalyticsGeographyCountry breakdown
Where recipients engaged from, by country, ordered by volume. Counts OPEN and CLICK events only, for the same reason as the device breakdown.
Country is derived from the IP address seen at engagement time. Treat it as indicative: opens routed through a proxy or an image-caching relay resolve to the relay, not the recipient.
/analytics/geographyanalytics:readExample request
curl "https://api.mailneo.co/api/v2/analytics/geography" \ -H "X-API-Key: $MAILNEO_API_KEY"
Authorization
- Required scope
analytics:read. A key without it is refused before the endpoint runs.- Credential
X-API-Key: mk_live_...Authorization: Bearer mk_live_...
Query parameters3
| Name | Type | Required | Notes |
|---|---|---|---|
| start | string · date-time | No | ISO 8601 |
| end | string · date-time | No | ISO 8601 |
| campaign_id | string | No | max 64 chars |
Response · 200
Success
data
| Field | Type | Always present | Notes |
|---|---|---|---|
| object | "analytics_geography" | Yes | |
| period_start | string | Yes | |
| period_end | string | Yes | |
| countries | object[] | Yes | |
| countries[].country | string | Yes | |
| countries[].events | number | Yes |
meta
| Field | Type | Always present | Notes |
|---|---|---|---|
| request_id | string | Yes |