MailLandDocs

Advanced Analytics

Geographic, device, email client, and time-of-day analytics with data export

MailLand provides advanced analytics endpoints for deeper insight into where, when, and how recipients engage with your emails. All data is sourced from ClickHouse and cached for 5 minutes.

Opens and clicks include machine activity, Apple Mail Privacy Protection prefetch and security link scanners, which MailLand does not filter out today. Every metric on this page derived from opens or clicks (geographic, device, email client, time-of-day) is an upper bound on human engagement, not a precise count.

For eventType=bounced and eventType=complained, the geographic and device endpoints exclude rows with no country_code or no device_type, since bounce and complaint events don't carry that data, these two endpoints normally return an empty array for those event types. Time-of-day has no such filter and returns real counts for any event type.

Geographic Analytics

See where your recipients are engaging, broken down by country and city:

GET https://api.mail.land/v1/transactional/analytics/advanced/geographic
Get geographic analytics
curl "https://api.mail.land/v1/transactional/analytics/advanced/geographic" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date
eventTypestringopenedEvent to analyze: opened, clicked, bounced, complained
Geographic analytics response
[
  {
    "countryCode": "US",
    "city": "San Francisco",
    "eventCount": 3420,
    "uniqueUsers": 2850
  },
  {
    "countryCode": "DE",
    "city": "Berlin",
    "eventCount": 1280,
    "uniqueUsers": 1100
  },
  {
    "countryCode": "GB",
    "city": "London",
    "eventCount": 950,
    "uniqueUsers": 820
  }
]

Device Analytics

See which devices and browsers your recipients use:

GET https://api.mail.land/v1/transactional/analytics/advanced/devices
Get device analytics
curl "https://api.mail.land/v1/transactional/analytics/advanced/devices" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date
eventTypestringopenedEvent to analyze: opened, clicked, bounced, complained
Device analytics response
[
  {
    "deviceType": "desktop",
    "browser": "Chrome",
    "emailClient": "Gmail",
    "eventCount": 5200,
    "uniqueUsers": 4100
  },
  {
    "deviceType": "mobile",
    "browser": "Safari",
    "emailClient": "Apple Mail",
    "eventCount": 3800,
    "uniqueUsers": 3200
  },
  {
    "deviceType": "desktop",
    "browser": "Firefox",
    "emailClient": "Thunderbird",
    "eventCount": 420,
    "uniqueUsers": 380
  }
]

Time of Day

Discover when recipients engage most, broken down by hour and day of week:

GET https://api.mail.land/v1/transactional/analytics/advanced/time-of-day
Get time of day analytics
curl "https://api.mail.land/v1/transactional/analytics/advanced/time-of-day" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date
eventTypestringopenedEvent to analyze: opened, clicked, bounced, complained
Time of day response
[
  { "hour": 9, "dayOfWeek": 1, "eventCount": 1240 },
  { "hour": 10, "dayOfWeek": 1, "eventCount": 1580 },
  { "hour": 14, "dayOfWeek": 2, "eventCount": 1120 },
  { "hour": 9, "dayOfWeek": 3, "eventCount": 1350 }
]
FieldDescription
hourHour of day (0–23, UTC)
dayOfWeekDay of week (0 = Sunday, 6 = Saturday)
eventCountNumber of events in this time slot

Email Clients

See which email clients your recipients use for opens and clicks:

GET https://api.mail.land/v1/transactional/analytics/advanced/email-clients
Get email clients
curl "https://api.mail.land/v1/transactional/analytics/advanced/email-clients" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date
Email clients response
[
  {
    "emailClient": "Gmail",
    "opens": 15200,
    "clicks": 1980,
    "uniqueUsers": 12500
  },
  {
    "emailClient": "Apple Mail",
    "opens": 8400,
    "clicks": 1100,
    "uniqueUsers": 7200
  },
  {
    "emailClient": "Outlook",
    "opens": 6800,
    "clicks": 850,
    "uniqueUsers": 5900
  }
]

Engagement Heatmap

Get a combined opens + clicks heatmap by hour and day of week, ideal for visualizing optimal send times:

GET https://api.mail.land/v1/transactional/analytics/advanced/engagement-heatmap
Get engagement heatmap
curl "https://api.mail.land/v1/transactional/analytics/advanced/engagement-heatmap" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date
Engagement heatmap response
[
  { "hour": 9, "dayOfWeek": 1, "opens": 1240, "clicks": 160 },
  { "hour": 10, "dayOfWeek": 1, "opens": 1580, "clicks": 205 },
  { "hour": 14, "dayOfWeek": 2, "opens": 1120, "clicks": 145 },
  { "hour": 9, "dayOfWeek": 3, "opens": 1350, "clicks": 175 }
]

This provides 168 data points (24 hours x 7 days) when data is available for a full week.

Export Data

Download analytics reports as Excel or PDF:

Excel Export

GET https://api.mail.land/v1/transactional/analytics/advanced/export/excel
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date

Returns a .xlsx file with content type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. The filename follows the format MailLand_Analytics_{from}_{to}.xlsx.

PDF Export

GET https://api.mail.land/v1/transactional/analytics/advanced/export/pdf
ParameterTypeDefaultDescription
fromdatetime30 days agoStart date
todatetimeNowEnd date

Returns a .pdf file with content type application/pdf. The filename follows the format MailLand_Analytics_{from}_{to}.pdf.

Download Excel report
curl -o analytics.xlsx \
  "https://api.mail.land/v1/transactional/analytics/advanced/export/excel?from=2026-01-01&to=2026-02-01" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Caching

All advanced analytics endpoints are cached for 5 minutes. Cache keys include the tenant ID, date range, and event type filter, so different queries are cached independently.

Next Steps

On this page

Geographic AnalyticsDevice AnalyticsTime of DayEmail ClientsEngagement HeatmapExport DataExcel ExportPDF ExportCachingNext Steps