check¶

Run complete mailflow security check for a domain.

GET

/api/v1/check

Overview¶

This is the primary endpoint for comprehensive email security analysis. It returns:

Mailflow Security Score (0-100)
SPF, DKIM, DMARC validation results
Security issues with severity levels
Actionable remediations with DNS snippets
Score breakdown showing potential improvements

Request¶

Query Parameters¶

Parameter	Type	Required	Default	Description
`domain`	string	✅ Yes	-	Domain to check (e.g., `example.com`)
`selectors`	string	❌ No	`null`	Comma-separated DKIM selectors (e.g., `default,google`)
`verbose`	boolean	❌ No	`false`	Include verbose DNS details
`refresh`	boolean	❌ No	`false`	Bypass cache and fetch fresh data
`save_snapshot`	boolean	❌ No	`true`	Save result to history

Headers¶

X-API-Key: your-api-key

Response¶

Success Response (200 OK)¶

{
  "domain": "example.com",
  "score": 75,
  "grade": "Good",
  "checked_at": "2025-10-21T10:30:00Z",

  "spf": {
    "present": true,
    "valid": true,
    "record": "v=spf1 include:_spf.google.com ~all",
    "mechanisms": ["include:_spf.google.com", "~all"],
    "warnings": []
  },

  "dkim": {
    "discovered_selectors": ["google", "default"],
    "validated_keys": [
      {
        "selector": "google",
        "valid": true,
        "key_size": 2048,
        "algorithm": "rsa-sha256"
      }
    ]
  },

  "dmarc": {
    "present": true,
    "valid": true,
    "record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
    "policy": "quarantine",
    "subdomain_policy": "none",
    "percentage": 100,
    "aggregate_reports": ["mailto:dmarc@example.com"]
  },

  "issues": [
    {
      "code": "DMARC_POLICY_WEAK",
      "severity": "high",
      "category": "dmarc",
      "message": "DMARC policy set to 'quarantine' instead of 'reject'",
      "score_impact": -10,
      "score_gain_if_fixed": 10,
      "remediation": "Update DMARC policy from 'quarantine' to 'reject' for maximum protection",
      "dns_snippet": {
        "record_type": "TXT",
        "hostname": "_dmarc.example.com",
        "value": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com"
      }
    }
  ],

  "score_breakdown": {
    "base_score": 100,
    "total_deductions": -25,
    "final_score": 75,
    "potential_score_if_fixed": 90,
    "issues_by_severity": {
      "critical": 0,
      "high": 1,
      "medium": 2,
      "low": 1
    }
  },

  "meta": {
    "latency_ms": 450,
    "cached": false,
    "cache_ttl": 900
  }
}

Error Responses¶

400 Bad Request - Invalid domain

{
  "error": "Invalid domain",
  "message": "The domain 'example' is not valid",
  "code": "INVALID_DOMAIN"
}

401 Unauthorized - Missing or invalid API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

429 Too Many Requests - Rate limit exceeded

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Examples¶

cURL¶

Basic Check:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=google.com" \
  -H "X-API-Key: your-api-key"

With DKIM Selectors:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=google.com&selectors=google,default&verbose=true" \
  -H "X-API-Key: your-api-key"

Force Refresh:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=google.com&refresh=true" \
  -H "X-API-Key: your-api-key"

Python¶

requests:

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.reputeapi.com"

response = requests.get(
    f"{BASE_URL}/api/v1/check",
    params={
        "domain": "google.com",
        "selectors": "google,default",
        "verbose": True
    },
    headers={"X-API-Key": API_KEY}
)

result = response.json()

print(f"Domain: {result['domain']}")
print(f"Score: {result['score']}/100 ({result['grade']})")
print(f"\nIssues Found: {len(result['issues'])}")

for issue in result['issues']:
    print(f"  [{issue['severity'].upper()}] {issue['message']}")
    if issue.get('dns_snippet'):
        print(f"  Fix: {issue['dns_snippet']['value']}")

httpx (async):

import httpx
import asyncio

async def check_domain(domain: str):
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.reputeapi.com/api/v1/check",
            params={"domain": domain},
            headers={"X-API-Key": "your-api-key"}
        )
        return response.json()

result = asyncio.run(check_domain("google.com"))
print(f"Score: {result['score']}/100")

JavaScript¶

fetch:

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.reputeapi.com';

async function checkDomain(domain) {
  const response = await fetch(
    `${BASE_URL}/api/v1/check?domain=${domain}`,
    {
      headers: {
        'X-API-Key': API_KEY
      }
    }
  );

  const result = await response.json();

  console.log(`Domain: ${result.domain}`);
  console.log(`Score: ${result.score}/100 (${result.grade})`);
  console.log(`\nIssues:`);

  result.issues.forEach(issue => {
    console.log(`  [${issue.severity}] ${issue.message}`);
  });

  return result;
}

checkDomain('google.com');

axios:

const axios = require('axios');

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.reputeapi.com';

axios.get(`${BASE_URL}/api/v1/check`, {
  params: {
    domain: 'google.com',
    selectors: 'google,default'
  },
  headers: {
    'X-API-Key': API_KEY
  }
})
.then(response => {
  const result = response.data;
  console.log(`Score: ${result.score}/100`);
})
.catch(error => {
  console.error('Error:', error.response.data);
});

Response Fields¶

Root Fields¶

Field	Type	Description
`domain`	string	Domain that was checked
`score`	integer	Mailflow Security Score (0-100)
`grade`	string	Letter grade: Excellent (90+), Good (75-89), Fair (50-74), Poor (<50)
`checked_at`	string	ISO 8601 timestamp

SPF Object¶

Field	Type	Description
`present`	boolean	SPF record found
`valid`	boolean	SPF record is valid
`record`	string	Raw SPF record
`mechanisms`	array	Parsed SPF mechanisms
`warnings`	array	SPF-specific warnings

DKIM Object¶

Field	Type	Description
`discovered_selectors`	array	DKIM selectors found via BIMI/discovery
`validated_keys`	array	List of validated DKIM keys

DMARC Object¶

Field	Type	Description
`present`	boolean	DMARC record found
`valid`	boolean	DMARC record is valid
`record`	string	Raw DMARC record
`policy`	string	DMARC policy: `none`, `quarantine`, or `reject`
`subdomain_policy`	string	Subdomain policy
`percentage`	integer	Percentage of messages subject to policy (0-100)
`aggregate_reports`	array	Email addresses for aggregate reports

Issue Object¶

Field	Type	Description
`code`	string	Unique issue code (e.g., `DMARC_MISSING`)
`severity`	string	`critical`, `high`, `medium`, `low`, or `info`
`category`	string	`spf`, `dkim`, `dmarc`, or `dns`
`message`	string	Human-readable issue description
`score_impact`	integer	Negative score impact
`score_gain_if_fixed`	integer	Potential score gain if fixed
`remediation`	string	How to fix the issue
`dns_snippet`	object	Copy-paste DNS configuration

DNS Snippet Object¶

Field	Type	Description
`record_type`	string	DNS record type (e.g., `TXT`)
`hostname`	string	DNS hostname (e.g., `_dmarc.example.com`)
`value`	string	DNS record value

Caching¶

Results are cached for 15 minutes by default to improve performance and reduce DNS queries.

Set refresh=true to bypass cache
Check meta.cached to see if result was cached
meta.cache_ttl shows remaining cache time in seconds

Score Interpretation¶

Score Range	Grade	Security Level
90-100	Excellent	Strong email security
75-89	Good	Good security with minor improvements possible
50-74	Fair	Moderate security, several issues to address
0-49	Poor	Weak security, urgent action required

GET /api/v1/score - Quick score check (faster)
POST /api/v1/recommendations - Get prioritized fixes
GET /api/v1/history - View historical trends