MailLandDocs

Analytics and deliverability

Sending statistics, engagement analytics and deliverability reports.

Get geographic analytics. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/advanced/geographic

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time
eventType?string
Default"opened"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/geographic"
[  {    "countryCode": "string",    "city": "string",    "eventCount": 0,    "uniqueUsers": 0,    "isProxy": true  }]

Get device analytics. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/advanced/devices

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time
eventType?string
Default"opened"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/devices"
[  {    "deviceType": "string",    "browser": "string",    "emailClient": "string",    "eventCount": 0,    "uniqueUsers": 0,    "isProxy": true  }]

Get time-of-day analytics. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/advanced/time-of-day

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time
eventType?string
Default"opened"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/time-of-day"
[  {    "hour": 0,    "dayOfWeek": 0,    "eventCount": 0  }]

Get email client analytics. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/advanced/email-clients

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/email-clients"
[  {    "emailClient": "string",    "opens": 0,    "clicks": 0,    "uniqueUsers": 0,    "isProxy": true  }]

Get engagement heatmap. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/advanced/engagement-heatmap

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/engagement-heatmap"
[  {    "hour": 0,    "dayOfWeek": 0,    "opens": 0,    "clicks": 0  }]

/v1/transactional/analytics/advanced/export/excel

GET/v1/transactional/analytics/advanced/export/excel

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/export/excel"
{  "fileContents": "string",  "contentType": null,  "fileDownloadName": null,  "lastModified": null,  "entityTag": null,  "enableRangeProcessing": true}

/v1/transactional/analytics/advanced/export/pdf

GET/v1/transactional/analytics/advanced/export/pdf

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string
Formatdate-time
to?string
Formatdate-time

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/advanced/export/pdf"
{  "fileContents": "string",  "contentType": null,  "fileDownloadName": null,  "lastModified": null,  "entityTag": null,  "enableRangeProcessing": true}

Get event counts by type for date range. PERF: Results are cached (5 min default, 3 min custom range). Uses request coalescing to prevent thundering herd on cache miss.

GET/v1/transactional/analytics/events/summary

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string

Start date (default: 30 days ago)

Formatdate-time
to?string

End date (default: now)

Formatdate-time
startDate?string

Alias for 'from' - for frontend compatibility

Formatdate-time
endDate?string

Alias for 'to' - for frontend compatibility

Formatdate-time
emailType?string

Filter by email type: 0 = Transactional, 1 = Marketing, null = all

Value in

  • "transactional"
  • "marketing"
refresh?boolean

If true, bypasses cache and fetches fresh data

Defaultfalse

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/events/summary"
{  "from": "2019-08-24T14:15:22Z",  "to": "2019-08-24T14:15:22Z",  "sent": 0,  "delivered": 0,  "opened": 0,  "clicked": 0,  "bounced": 0,  "complained": 0,  "totalClicks": null,  "uniqueLinkClicks": null,  "uniqueClickers": null,  "filteredBotClicks": null,  "clicksFrom": null,  "clicksTo": null,  "source": "string",  "data_source": "string",  "fallback_reason": null,  "is_degraded": true,  "queryTimeMs": 0}

Get daily statistics. PERF: Results are cached for 3 minutes.

GET/v1/transactional/analytics/stats/daily

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string

Start date (default: the last 7 whole UTC days, the dashboard's window)

Formatdate-time
to?string

End date (default: end of today, UTC)

Formatdate-time
startDate?string

Alias for 'from' - for frontend compatibility

Formatdate-time
endDate?string

Alias for 'to' - for frontend compatibility

Formatdate-time
emailType?string

Filter by email type: 0 = Transactional, 1 = Marketing, null = all

Value in

  • "transactional"
  • "marketing"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/stats/daily"
[  {    "date": "2019-08-24T14:15:22Z",    "sent": 0,    "delivered": 0,    "opened": 0,    "clicked": 0,    "bounced": 0  }]

Get top clicked links. PERF: Results are cached for 5 minutes.

GET/v1/transactional/analytics/links/top

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string

Start date (default: 30 days ago)

Formatdate-time
to?string

End date (default: now)

Formatdate-time
startDate?string

Alias for 'from' - for frontend compatibility

Formatdate-time
endDate?string

Alias for 'to' - for frontend compatibility

Formatdate-time
limit?|

Maximum number of links to return (default: 10)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default10
emailType?string

Filter by email type: 0 = Transactional, 1 = Marketing, null = all

Value in

  • "transactional"
  • "marketing"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/links/top"
[  {    "url": "string",    "clicks": 0,    "uniqueRecipients": 0  }]

Get delivery, open, and click rates. PERF: Results are cached for 3 minutes. Queries run in parallel.

GET/v1/transactional/analytics/rates

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string

Start date (default: 30 days ago)

Formatdate-time
to?string

End date (default: now)

Formatdate-time
startDate?string

Alias for 'from' - for frontend compatibility

Formatdate-time
endDate?string

Alias for 'to' - for frontend compatibility

Formatdate-time
emailType?string

Filter by email type: 0 = Transactional, 1 = Marketing, null = all

Value in

  • "transactional"
  • "marketing"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/rates"
{  "from": "2019-08-24T14:15:22Z",  "to": "2019-08-24T14:15:22Z",  "deliveryRate": 0,  "openRate": 0,  "clickRate": 0}

UNG-137 / D-174 (3) — the share of opened messages that were seen only through a mail provider's proxy (Gmail/Yahoo image proxy, Apple Mail Privacy Protection, a Google-operated fetcher), shown beside the open rate. It does NOT change the open rate: proxied opens still count there, and in open-triggered automations. Cached like the rates.

GET/v1/transactional/analytics/proxy-share

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

from?string

Start date (default: 30 days ago)

Formatdate-time
to?string

End date (default: now)

Formatdate-time
startDate?string

Alias for 'from'

Formatdate-time
endDate?string

Alias for 'to'

Formatdate-time
emailType?string

Filter by email type: 0 = Transactional, 1 = Marketing, null = all

Value in

  • "transactional"
  • "marketing"

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/proxy-share"
{  "from": null,  "to": null,  "openedMessages": 0,  "proxyOnlyMessages": 0,  "proxyShare": 0,  "byProvider": {    "google": 0,    "yahoo": 0,    "apple": 0  }}

Get hourly sending volume with optional baseline overlay. Used by the volume trend chart on the dashboard.

GET/v1/transactional/analytics/volume/hourly

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Number of days to look back (default: 7, max: 30)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default7

Response Body

application/json

curl -X GET "https://example.com/v1/transactional/analytics/volume/hourly"
[  {    "hour": "2019-08-24T14:15:22Z",    "sent": 0,    "baseline": null  }]

Get sender score (0-100) with component breakdown. Cached for 15 minutes.

GET/v1/deliverability/score

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/score"
{  "totalScore": 0,  "label": "string",  "hasSufficientData": true,  "totalSentLast30Days": 0,  "dnsScore": {    "name": "string",    "score": 0,    "maxScore": 0,    "detail": "string"  },  "bounceScore": {    "name": "string",    "score": 0,    "maxScore": 0,    "detail": "string"  },  "complaintScore": {    "name": "string",    "score": 0,    "maxScore": 0,    "detail": "string"  },  "engagementScore": {    "name": "string",    "score": 0,    "maxScore": 0,    "detail": "string"  },  "engagementIncluded": true,  "calculatedAt": "2019-08-24T14:15:22Z"}

Get aggregated deliverability overview for a period.

GET/v1/deliverability/overview

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Period: 7, 30, or 90 days (default: 30)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default30

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/overview"
{  "totalSent": 0,  "totalDelivered": 0,  "totalBounced": 0,  "totalPlatformRefused": 0,  "totalAttemptsExpired": 0,  "totalMarketingSent": 0,  "totalComplained": 0,  "totalOpened": 0,  "totalClicked": 0,  "totalUnsubscribed": 0,  "deliveryRate": 0,  "bounceRate": 0,  "complaintRate": 0,  "openRate": 0,  "clickRate": 0,  "unsubscribeRate": 0}
GET/v1/deliverability/trends

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Period: 7, 30, or 90 days (default: 30)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default30

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/trends"
[  {    "date": "2019-08-24T14:15:22Z",    "sent": 0,    "delivered": 0,    "bounced": 0,    "complained": 0,    "opened": 0,    "deliveryRate": 0,    "bounceRate": 0,    "complaintRate": 0,    "openRate": 0  }]

Get per-recipient-domain stats (Gmail, Yahoo, Outlook, etc.).

GET/v1/deliverability/providers

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Period: 7, 30, or 90 days (default: 30)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default30
limit?|

Max number of domains (default: 10, max: 50)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default10

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/providers"
[  {    "domain": "string",    "sent": 0,    "delivered": 0,    "bounced": 0,    "opened": 0,    "clicked": 0,    "complained": 0,    "deliveryRate": 0,    "openRate": 0,    "bounceRate": 0  }]

Get bounce type breakdown (hard, soft, unknown) with top bounce reasons.

GET/v1/deliverability/bounce-breakdown

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Period: 7, 30, or 90 days (default: 30)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default30

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/bounce-breakdown"
{  "hardBounces": 0,  "softBounces": 0,  "blockedBounces": 0,  "unknownBounces": 0,  "platformRefusedBounces": 0,  "attemptsExpiredBounces": 0,  "totalBounces": 0,  "topReasons": [    {      "reason": "string",      "count": 0    }  ]}

Get DNS authentication status for all tenant domains.

GET/v1/deliverability/dns-status

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/dns-status"
[  {    "domainId": "string",    "domainName": "string",    "spfStatus": "string",    "dkimStatus": "string",    "dmarcStatus": "string",    "lastCheckedAt": null,    "isFullyAuthenticated": true  }]

Get historical sender score data for trend charts.

GET/v1/deliverability/score/history

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Query Parameters

days?|

Number of days of history (default: 30, max: 90)

Match^-?(?:0|[1-9]\d*)$
Formatint32
Default30

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/score/history"
[  {    "date": "2019-08-24",    "totalScore": 0,    "label": "string",    "dnsScore": 0,    "bounceScore": 0,    "complaintScore": 0,    "engagementScore": 0,    "bounceRate": 0,    "complaintRate": 0,    "openRate": 0,    "deliveryRate": 0,    "totalSent": 0,    "hasSufficientData": true  }]

Get actionable recommendations to improve sender score.

GET/v1/deliverability/recommendations

Authorization

ApiKey
X-API-Key<token>

Your API key, created in the dashboard under API keys. Production sending keys start with ml_pet_ (transactional) or ml_pem_ (marketing); sandbox keys with ml_set_ or ml_sem_.

In: header

Response Body

application/json

curl -X GET "https://example.com/v1/deliverability/recommendations"
[  {    "id": "string",    "category": "string",    "severity": "string",    "titleKey": "string",    "descriptionKey": "string",    "actionUrl": null,    "impact": 0,    "parameters": null  }]