MailLandDocs

Deliverability Overview

Monitor sender reputation, delivery rates, and DNS health across all your domains

MailLand tracks your sender reputation through a composite score, delivery trends, provider-level breakdowns, and DNS health monitoring. Use the deliverability API to surface these metrics in your own dashboards or trigger alerts when reputation declines.

Sender Score

Get a 0–100 reputation score broken into four weighted components:

GET https://api.mail.land/v1/deliverability/score

Authenticate with Authorization: Bearer <token> or X-API-Key: <api key>.

Get sender score
curl https://api.mail.land/v1/deliverability/score \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Sender score response
{
  "totalScore": 87,
  "label": "Good",
  "hasSufficientData": true,
  "totalSentLast30Days": 142500,
  "dnsScore": {
    "name": "DNS Authentication",
    "score": 25,
    "maxScore": 25,
    "detail": "2/2 domains fully authenticated"
  },
  "bounceScore": {
    "name": "Bounce Rate",
    "score": 20,
    "maxScore": 25,
    "detail": "Bounce rate: 1.80%"
  },
  "complaintScore": {
    "name": "Complaint Rate",
    "score": 25,
    "maxScore": 25,
    "detail": "Complaint rate: 0.020%"
  },
  "engagementScore": {
    "name": "Engagement",
    "score": 25,
    "maxScore": 25,
    "detail": "Open rate: 32.0%"
  },
  "calculatedAt": "2026-02-17T12:00:00Z"
}

Each component contributes up to 25 points. Below 100 sends in the last 30 days, hasSufficientData is false. totalScore is still calculated but is not meaningful at that volume: with zero sends, the bounce and complaint components each score full marks (25), so a brand-new account can show up to 75 before it has sent anything.

Score History

Track how your score changes over time:

GET https://api.mail.land/v1/deliverability/score/history?days=30
Get score history
curl "https://api.mail.land/v1/deliverability/score/history?days=30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
daysint30History window (7–90)
Score history response
[
  {
    "date": "2026-02-17",
    "totalScore": 87,
    "label": "Good",
    "dnsScore": 25,
    "bounceScore": 22,
    "complaintScore": 25,
    "engagementScore": 15,
    "bounceRate": 0.8,
    "complaintRate": 0.02,
    "openRate": 32.0,
    "deliveryRate": 98.5,
    "totalSent": 4750,
    "hasSufficientData": true
  }
]

Deliverability Overview Stats

Get aggregate delivery metrics for a period:

GET https://api.mail.land/v1/deliverability/overview?days=30
Get deliverability overview
curl "https://api.mail.land/v1/deliverability/overview?days=30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
daysint30Period window (normalizes to 7, 30, or 90)
Overview response
{
  "totalSent": 142500,
  "totalDelivered": 140325,
  "totalBounced": 1125,
  "totalComplained": 28,
  "totalOpened": 44878,
  "totalClicked": 5843,
  "totalUnsubscribed": 312,
  "deliveryRate": 98.47,
  "bounceRate": 0.79,
  "complaintRate": 0.02,
  "openRate": 31.49,
  "clickRate": 4.1,
  "unsubscribeRate": 0.22
}

Get per-day delivery metrics to visualize trends:

GET https://api.mail.land/v1/deliverability/trends?days=30
Get daily trends
curl "https://api.mail.land/v1/deliverability/trends?days=30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Trends response (abbreviated)
[
  {
    "date": "2026-02-17T00:00:00Z",
    "sent": 4750,
    "delivered": 4680,
    "bounced": 38,
    "complained": 1,
    "opened": 1498,
    "deliveryRate": 98.53,
    "bounceRate": 0.8,
    "complaintRate": 0.02,
    "openRate": 31.53
  }
]

Provider Breakdown

See deliverability metrics grouped by recipient mailbox provider (Gmail, Yahoo, Outlook, etc.):

GET https://api.mail.land/v1/deliverability/providers?days=30&limit=10
Get provider breakdown
curl "https://api.mail.land/v1/deliverability/providers?days=30&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
ParameterTypeDefaultDescription
daysint30Period window (normalizes to 7, 30, or 90)
limitint10Max providers to return (1–50)
Provider breakdown response
[
  {
    "domain": "gmail.com",
    "sent": 58200,
    "delivered": 57800,
    "bounced": 210,
    "opened": 19500,
    "clicked": 2540,
    "complained": 8,
    "deliveryRate": 99.31,
    "openRate": 33.51,
    "bounceRate": 0.36
  },
  {
    "domain": "outlook.com",
    "sent": 31400,
    "delivered": 30800,
    "bounced": 350,
    "opened": 8650,
    "clicked": 1120,
    "complained": 12,
    "deliveryRate": 98.09,
    "openRate": 27.55,
    "bounceRate": 1.11
  }
]

Bounce Breakdown

See bounces categorized by type and reason:

GET https://api.mail.land/v1/deliverability/bounce-breakdown?days=30
Get bounce breakdown
curl "https://api.mail.land/v1/deliverability/bounce-breakdown?days=30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Bounce breakdown response
{
  "hardBounces": 450,
  "softBounces": 625,
  "blockedBounces": 40,
  "unknownBounces": 10,
  "totalBounces": 1125,
  "topReasons": [
    { "reason": "InvalidRecipient", "count": 380 },
    { "reason": "QuotaIssues", "count": 290 },
    { "reason": "SpamBlock", "count": 40 },
    { "reason": "BadDomain", "count": 70 },
    { "reason": "PolicyRelated", "count": 95 },
    { "reason": "TransientFailure", "count": 55 }
  ]
}

topReasons uses the MTA's own classification names (see Bounces for the full vocabulary), not the keyword-derived snake_case categories used by the transactional bounce endpoints.

See Bounces for full bounce category details and handling behavior.

DNS Status

Check DNS authentication status across all your domains:

GET https://api.mail.land/v1/deliverability/dns-status
Get DNS status
curl https://api.mail.land/v1/deliverability/dns-status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
DNS status response
[
  {
    "domainId": "k3v9x2m8q1w7z4",
    "domainName": "yourdomain.com",
    "spfStatus": "Valid",
    "dkimStatus": "Valid",
    "dmarcStatus": "Valid",
    "lastCheckedAt": "2026-02-17T10:00:00Z",
    "isFullyAuthenticated": true
  },
  {
    "domainId": "n7p2q9x4m8w1z3",
    "domainName": "notifications.yourdomain.com",
    "spfStatus": "Valid",
    "dkimStatus": "Valid",
    "dmarcStatus": "Invalid",
    "lastCheckedAt": "2026-02-17T10:00:00Z",
    "isFullyAuthenticated": false
  }
]

A domain is isFullyAuthenticated only when SPF, DKIM, and DMARC are all Valid.

StatusDescription
PendingRecord not yet checked
ValidRecord correctly configured
InvalidRecord missing or misconfigured

Recommendations

Get actionable recommendations to improve your sender reputation:

GET https://api.mail.land/v1/deliverability/recommendations
Get recommendations
curl https://api.mail.land/v1/deliverability/recommendations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Recommendations response
[
  {
    "id": "dns_dmarc_missing_notifications.yourdomain.com",
    "category": "dns",
    "severity": "critical",
    "titleKey": "deliverability.recommendations.dns.dmarcMissing.title",
    "descriptionKey": "deliverability.recommendations.dns.dmarcMissing.description",
    "actionUrl": "/domains",
    "impact": 8,
    "parameters": {
      "domain": "notifications.yourdomain.com"
    }
  },
  {
    "id": "bounce_high",
    "category": "bounce",
    "severity": "warning",
    "titleKey": "deliverability.recommendations.bounce.high.title",
    "descriptionKey": "deliverability.recommendations.bounce.high.description",
    "actionUrl": "/deliverability",
    "impact": 15
  }
]
FieldTypeDescription
idstringRecommendation identifier. Not a stable enum: DNS ids embed the domain name (for example dns_dmarc_missing_{domain}), so the same issue on two domains produces two different ids.
categorystringdns, bounce, complaint, engagement, warmup, or volume
severitystringcritical, warning, or info
impactintPotential score improvement (0–100) if fixed
actionUrlstringFrontend route to address the issue: one of /domains, /deliverability, /suppression-lists, /analytics, or /dashboard. These are hints for your own UI, not a guaranteed dashboard URL: in the Mail.Land dashboard the matching pages are Domains, Deliverability, Suppressions and Analytics in the sidebar
parametersobjectValues for i18n interpolation. Only present on DNS recommendations ({"domain": "..."}); bounce, complaint, engagement, warmup and volume recommendations have no parameters.

At most 10 recommendations are returned, sorted by severity (critical first) then by impact descending.

Caching

All deliverability endpoints are cached server-side to reduce query load on ClickHouse:

EndpointCache TTL
/score15 minutes
/overview5 minutes
/trends3 minutes
/providers5 minutes
/bounce-breakdown5 minutes
/score/historyNot cached
/dns-statusNot cached (real-time)
/recommendations10 minutes

The days parameter normalizes to 7, 30, or 90: values ≤ 7 round to 7, 8–30 round to 30, and anything over 30 rounds to 90. A value like 14 rounds to 30, not 7.

Next Steps

On this page

Sender ScoreScore HistoryDeliverability Overview StatsDaily TrendsProvider BreakdownBounce BreakdownDNS StatusRecommendationsCachingNext Steps