MailVital API Docs

Overview

The MailVital API lets you programmatically check any domain's email health — SPF, DKIM, DMARC, blacklist status, and MX records — and get a scored report with actionable fix instructions.

Public check endpoints require no authentication. Monitoring and billing endpoints require an API key.

All responses are JSON
All responses include a top-level success boolean
Data is in the data key; errors are in the error key
Checks run in real-time against live DNS — expect 2–8 seconds per call

Base URL

https://mailvital.com

All API paths are relative to this base. For local development, use http://localhost:3000.

Authentication

Public endpoints (check, score, health) require no authentication. Monitoring endpoints require an API key passed in the X-Api-Key header.

# Example authenticated request
curl https://mailvital.com/api/monitor/domains \
  -H "X-Api-Key: your_api_key_here"

API keys are issued with paid plan subscriptions. Find yours in your account dashboard after subscribing.

Rate Limits

The public API is rate-limited to 100 requests per 15 minutes per IP address. Exceeding this returns a 429 Too Many Requests response.

Plan	Rate Limit	Notes
Free	100 req / 15 min	IP-based
Starter	500 req / 15 min	API key-based
Professional	2,000 req / 15 min	API key-based
Business	Unlimited	Fair use policy

Error Handling

All errors return a JSON body with success: false and an error message.

{
  "success": false,
  "error": "Invalid domain format"
}

Status Code	Meaning
400	Bad request — invalid domain or missing parameter
401	Unauthorized — missing or invalid API key
404	Domain not found in monitoring list
429	Rate limit exceeded
500	Internal server error

Public Endpoints

GET /api/check/:domain Full domain health report

Runs all checks (SPF, DKIM, DMARC, blacklist, MX) and returns a complete scored report with per-check details and fix instructions.

Path Parameters

Parameter	Type	Description
domain	string	Domain to check (e.g. `example.com`)

Example Request

curl https://mailvital.com/api/check/gmail.com

Example Response

{
  "success": true,
  "data": {
    "domain": "gmail.com",
    "score": 84,
    "grade": "B",
    "checks": {
      "spf": {
        "score": 1.0,
        "grade": "A",
        "record": "v=spf1 redirect=_spf.google.com",
        "allQualifier": "~all",
        "issues": [],
        "fixes": []
      },
      "dkim": {
        "score": 0.7,
        "grade": "unknown",
        "selectorsChecked": ["google", "default", "mail"],
        "issues": ["No DKIM selectors found in standard locations"],
        "fixes": ["Add your ESP's DKIM selector to DNS"]
      },
      "dmarc": {
        "score": 0.9,
        "grade": "A",
        "record": "v=DMARC1; p=reject; ...",
        "policy": "reject",
        "issues": [],
        "fixes": []
      },
      "blacklist": {
        "score": 1.0,
        "grade": "A",
        "listed": 0,
        "checked": 60,
        "issues": [],
        "fixes": []
      },
      "mx": {
        "score": 1.0,
        "grade": "A",
        "records": [
          { "exchange": "gmail-smtp-in.l.google.com", "priority": 5 }
        ],
        "issues": [],
        "fixes": []
      }
    },
    "checkedAt": "2026-03-27T12:00:00.000Z"
  }
}

GET /api/score/:domain Quick score only

Returns just the overall score and grade for a domain. Faster than a full check — useful for dashboards or badges.

Example Request

curl https://mailvital.com/api/score/gmail.com

Example Response

{
  "success": true,
  "data": {
    "domain": "gmail.com",
    "score": 84,
    "grade": "B",
    "checkedAt": "2026-03-27T12:00:00.000Z"
  }
}

GET /api/check/:domain/:check Run a single check

Run just one check type against a domain. Useful when you only care about one aspect of deliverability.

Path Parameters

Parameter	Type	Description
domain	string	Domain to check
check	string	One of: `spf`, `dkim`, `dmarc`, `blacklist`, `mx`

Example Request

curl https://mailvital.com/api/check/gmail.com/spf

Example Response

{
  "success": true,
  "data": {
    "domain": "gmail.com",
    "check": "spf",
    "score": 1.0,
    "grade": "A",
    "record": "v=spf1 redirect=_spf.google.com",
    "allQualifier": "~all",
    "issues": [],
    "fixes": [],
    "checkedAt": "2026-03-27T12:00:00.000Z"
  }
}

GET /api/trust/:domain Domain trust intelligence report

Returns a comprehensive trust score based on SSL certificates, domain age, web presence, and typosquat exposure. Powered by TrustPulse.

Note: This endpoint makes several external lookups (crt.sh, RDAP, DNS, HTTPS) so responses typically take 3-8 seconds.

curl https://mailvital.com/api/trust/gmail.com

{
  "success": true,
  "data": {
    "domain": "gmail.com",
    "timestamp": "2026-03-27T23:00:00.000Z",
    "elapsed_ms": 4200,
    "trust": {
      "score": 95,
      "letter": "A",
      "summary": "Highly trusted domain...",
      "breakdown": {
        "ssl": { "grade": "pass", "points": 30, "maxPoints": 30 },
        "domainAge": { "grade": "pass", "points": 20, "maxPoints": 20 },
        "webPresence": { "grade": "pass", "points": 30, "maxPoints": 30 },
        "typosquat": { "grade": "warn", "points": 14, "maxPoints": 20 }
      }
    },
    "checks": {
      "ssl": { "grade": "pass", "certCount": 42, "latestIssuer": "Google Trust Services", ... },
      "domainAge": { "grade": "pass", "ageDays": 9800, ... },
      "webPresence": { "grade": "pass", "resolves": true, "hasHttps": true, ... },
      "typosquat": { "grade": "warn", "checked": 15, "registered": [...], ... }
    },
    "issues": [...],
    "fixes": [...]
  }
}

Trust Score Components

SSL (30pts)	Certificate transparency — valid cert, not expired, trusted issuer
Domain Age (20pts)	RDAP registration date — older domains score higher
Web Presence (30pts)	DNS resolution + HTTPS reachability
Typosquat (20pts)	Brand risk — how many typo variants of the domain are registered

GET /api/badge/:domain Embeddable SVG score badge

Returns an SVG badge showing the domain's email health score — perfect for embedding in READMEs, websites, or dashboards. Results are cached for 5 minutes.

Parameters

`style`	`flat` (default) or `flat-square`
`label`	Custom left-side text (default: `email health`, max 30 chars)

Usage

Markdown (GitHub README, etc.):

![Email Health](https://mailvital.com/api/badge/yourdomain.com)

HTML:

<a href="https://mailvital.com">
  <img src="https://mailvital.com/api/badge/yourdomain.com" alt="Email Health Score">
</a>

Custom label & style:

![Score](https://mailvital.com/api/badge/yourdomain.com?label=deliverability&style=flat-square)

Example response: Returns image/svg+xml — an SVG image showing something like:

┌──────────────┬──────────────────┐
│ email health │  84/100 (B)      │
└──────────────┴──────────────────┘

💡 Tip: Embedding a badge in your site creates a backlink to MailVital and shows visitors you care about email deliverability.

GET /health Server health check

Returns server status and uptime. Useful for uptime monitors.

curl https://mailvital.com/health

{
  "success": true,
  "data": {
    "status": "ok",
    "uptime": 3721.4,
    "emailConfigured": true
  }
}

Monitoring Endpoints 🔑 API Key Required

Pro feature. Monitoring endpoints track domains over time, alert you to score changes, and surface historical trends. All require an X-Api-Key header.

GET /api/monitor/domains List monitored domains

Returns all domains currently enrolled in monitoring for your account.

curl https://mailvital.com/api/monitor/domains \
  -H "X-Api-Key: YOUR_KEY"

{
  "success": true,
  "data": [
    {
      "id": 1,
      "domain": "example.com",
      "alertEmail": "alerts@example.com",
      "intervalMinutes": 60,
      "lastChecked": "2026-03-27T11:00:00.000Z",
      "lastScore": 88,
      "addedAt": "2026-03-01T00:00:00.000Z"
    }
  ]
}

POST /api/monitor/domains Add domain to monitoring

Request Body

Field	Type	Required	Description
domain	string	Yes	Domain to monitor
alertEmail	string	No	Email address for score-change alerts
intervalMinutes	number	No	Check interval in minutes (default: 60)

curl -X POST https://mailvital.com/api/monitor/domains \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","alertEmail":"you@example.com","intervalMinutes":60}'

GET /api/monitor/domains/:domain/history Check history

Returns past check results for a monitored domain.

Query Parameters

Parameter	Type	Default	Description
limit	number	30	Number of results to return

curl "https://mailvital.com/api/monitor/domains/example.com/history?limit=10" \
  -H "X-Api-Key: YOUR_KEY"

GET /api/monitor/domains/:domain/trend Score trend over time

Returns score history suitable for charting. Daily data points for the specified window.

Query Parameters

Parameter	Type	Default	Description
days	number	30	Number of days of history

curl "https://mailvital.com/api/monitor/domains/example.com/trend?days=14" \
  -H "X-Api-Key: YOUR_KEY"

GET /api/monitor/domains/:domain/alerts Alert history

Returns recent alerts triggered for a domain (score drops, new blacklist listings, etc.).

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Number of alerts to return

curl https://mailvital.com/api/monitor/domains/example.com/alerts \
  -H "X-Api-Key: YOUR_KEY"

POST /api/monitor/domains/:domain/check Trigger immediate check

Manually trigger a check for a monitored domain, outside the normal schedule.

curl -X POST https://mailvital.com/api/monitor/domains/example.com/check \
  -H "X-Api-Key: YOUR_KEY"

{
  "success": true,
  "data": {
    "score": 88,
    "checkId": 42
  }
}

DELETE /api/monitor/domains/:id Remove domain from monitoring

Removes a domain from monitoring by its numeric ID (returned in the list response).

curl -X DELETE https://mailvital.com/api/monitor/domains/1 \
  -H "X-Api-Key: YOUR_KEY"

{
  "success": true
}

Billing Endpoints

GET /api/plans Available plans

Returns available subscription plans with pricing and features.

curl https://mailvital.com/api/plans

{
  "success": true,
  "data": {
    "starter":      { "name": "Starter",      "price": 19, "domains": 1,  "interval": "daily"  },
    "professional": { "name": "Professional", "price": 39, "domains": 5,  "interval": "hourly" },
    "business":     { "name": "Business",     "price": 79, "domains": -1, "interval": "realtime" }
  }
}

POST /api/checkout Create checkout session

Creates a Lemon Squeezy checkout session and returns the checkout URL.

Request Body

Field	Type	Required	Description
plan	string	Yes	`starter`, `professional`, or `business`
email	string	No	Pre-fill customer email
name	string	No	Pre-fill customer name

curl -X POST https://mailvital.com/api/checkout \
  -H "Content-Type: application/json" \
  -d '{"plan":"starter","email":"you@example.com"}'

{
  "success": true,
  "data": {
    "checkoutUrl": "https://mailvital.lemonsqueezy.com/checkout/..."
  }
}

Response Schema

Every response follows the same envelope format:

Field	Type	Description
success	boolean	`true` on success, `false` on error
data	object \| array	Present on success — the response payload
error	string	Present on error — human-readable error message

Score & Grades

Scores are integers from 0–100. Each check contributes a weighted fraction of the total.

Grade	Score Range	Meaning
A	90–100	Excellent — minimal deliverability risk
B	75–89	Good — minor issues worth addressing
C	50–74	Fair — significant issues that may cause problems
F	0–49	Poor — high risk of spam folder or rejection

Check-level scores are floats from 0.0–1.0, where 1.0 is perfect. An unknown grade (score 0.7) means the check couldn't fully verify the setting — not a failure, but investigate.

Check Types

Check	What it verifies
`spf`	SPF record — which servers are authorized to send email for this domain. Follows `redirect=` chains.
`dkim`	DKIM public key records — checks common selectors. Scores `unknown` if selectors not found (custom selectors are common).
`dmarc`	DMARC policy — enforcement level (`none`, `quarantine`, `reject`), reporting config.
`blacklist`	Blacklist status across 60+ DNSBLs. Uses a 3-tier weighting: critical lists tank the score; minor/regional lists have reduced weight.
`mx`	MX records — confirms the domain can receive email (required for reply deliverability).

API Reference

Overview

Base URL

Authentication

Rate Limits

Error Handling

Public Endpoints

Path Parameters

Example Request

Example Response

Example Request

Example Response

Path Parameters

Example Request

Example Response

Trust Score Components

Parameters

Usage

Monitoring Endpoints 🔑 API Key Required

Request Body

Query Parameters

Query Parameters

Query Parameters

Billing Endpoints

Request Body

Response Schema

Score & Grades

Check Types

Ready to integrate?