recommendations¶

Get deterministic, prioritized recommendations for a domain.

POST

/api/v1/recommendations

Overview¶

Returns actionable recommendations ordered by priority to maximize security score improvements.

Each recommendation includes: - Copy-paste DNS snippets for immediate fixes - Score gain if you implement the fix - Verification steps to confirm the fix worked

Recommendations are sorted by: 1. Severity (critical → high → medium → low) 2. Score gain (highest impact first)

Request¶

Headers¶

X-API-Key: your-api-key
Content-Type: application/json

Body Parameters¶

Parameter	Type	Required	Default	Description
`domain`	string	✅ Yes	-	Domain to analyze
`limit`	integer	❌ No	`10`	Maximum recommendations to return (1-50)

Request Body¶

{
  "domain": "example.com",
  "limit": 10
}

Response¶

Success Response (200 OK)¶

{
  "domain": "example.com",
  "current_score": 65,
  "potential_score": 95,
  "recommendations": [
    {
      "priority": 1,
      "issue_code": "DMARC_MISSING",
      "category": "dmarc",
      "severity": "critical",
      "score_gain": 40,
      "action": "Add DMARC record to enable domain protection and reporting",
      "dns_snippet": {
        "record_type": "TXT",
        "hostname": "_dmarc.example.com",
        "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
      },
      "verification": "Run /api/v1/check?domain=example.com to verify the fix"
    },
    {
      "priority": 2,
      "issue_code": "SPF_SOFTFAIL",
      "category": "spf",
      "severity": "high",
      "score_gain": 10,
      "action": "Change SPF qualifier from '~all' to '-all' for strict enforcement",
      "dns_snippet": {
        "record_type": "TXT",
        "hostname": "example.com",
        "value": "v=spf1 include:_spf.google.com -all"
      },
      "verification": "Run /api/v1/check?domain=example.com to verify the fix"
    }
  ],
  "meta": {
    "latency_ms": 520
  }
}

Response Fields¶

Field	Type	Description
`domain`	string	Domain analyzed
`current_score`	integer	Current Mailflow Security Score (0-100)
`potential_score`	integer	Score if all recommendations implemented
`recommendations`	array	List of prioritized recommendations
`meta.latency_ms`	integer	Response time in milliseconds

Recommendation Object¶

Field	Type	Description
`priority`	integer	Priority rank (1 = highest priority)
`issue_code`	string	Unique issue identifier
`category`	string	`spf`, `dkim`, `dmarc`, or `dns`
`severity`	string	`critical`, `high`, `medium`, `low`
`score_gain`	integer	Points gained if fixed
`action`	string	What to do to fix the issue
`dns_snippet`	object	Copy-paste DNS configuration
`verification`	string	How to verify the fix

Examples¶

cURL¶

curl -X POST "https://api.reputeapi.com/api/v1/recommendations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "limit": 5
  }'

Python¶

Simple Request:

import requests

response = requests.post(
    "https://api.reputeapi.com/api/v1/recommendations",
    json={"domain": "example.com", "limit": 5},
    headers={"X-API-Key": "your-api-key"}
)

result = response.json()

print(f"Current Score: {result['current_score']}/100")
print(f"Potential Score: {result['potential_score']}/100")
print(f"\nTop Recommendations:")

for rec in result['recommendations']:
    print(f"\n{rec['priority']}. [{rec['severity'].upper()}] +{rec['score_gain']} points")
    print(f"   {rec['action']}")

    if rec.get('dns_snippet'):
        dns = rec['dns_snippet']
        print(f"   DNS: {dns['hostname']} {dns['record_type']} {dns['value']}")

Generate DNS Zone File:

import requests

def generate_dns_fixes(domain: str):
    """Generate DNS zone file entries from recommendations"""

    response = requests.post(
        "https://api.reputeapi.com/api/v1/recommendations",
        json={"domain": domain},
        headers={"X-API-Key": "your-api-key"}
    )

    result = response.json()

    print(f"; DNS fixes for {domain}")
    print(f"; Potential score improvement: {result['current_score']} → {result['potential_score']}")
    print()

    for rec in result['recommendations']:
        if rec.get('dns_snippet'):
            dns = rec['dns_snippet']
            print(f"; {rec['action']} (+{rec['score_gain']} points)")
            print(f"{dns['hostname']}. IN {dns['record_type']} \"{dns['value']}\"")
            print()

generate_dns_fixes("example.com")

JavaScript¶

const response = await fetch(
  'https://api.reputeapi.com/api/v1/recommendations',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domain: 'example.com',
      limit: 5
    })
  }
);

const result = await response.json();

console.log(`Current Score: ${result.current_score}/100`);
console.log(`Potential Score: ${result.potential_score}/100`);

result.recommendations.forEach(rec => {
  console.log(`\n${rec.priority}. [${rec.severity}] +${rec.score_gain} points`);
  console.log(`   ${rec.action}`);

  if (rec.dns_snippet) {
    console.log(`   DNS: ${rec.dns_snippet.value}`);
  }
});

Use Cases¶

1. Security Audit Report¶

def generate_audit_report(domain):
    response = requests.post(
        f"{API_URL}/api/v1/recommendations",
        json={"domain": domain},
        headers={"X-API-Key": API_KEY}
    )

    result = response.json()

    report = f"""
Email Security Audit Report
Domain: {domain}
Date: {datetime.now().strftime('%Y-%m-%d')}

Current Security Score: {result['current_score']}/100
Potential Score: {result['potential_score']}/100
Improvement Potential: +{result['potential_score'] - result['current_score']} points

Priority Recommendations:
"""

    for rec in result['recommendations']:
        report += f"""
{rec['priority']}. [{rec['severity'].upper()}] {rec['action']}
   Score Impact: +{rec['score_gain']} points
   Category: {rec['category'].upper()}

   Implementation:
   {rec['dns_snippet']['hostname']} {rec['dns_snippet']['record_type']}
   "{rec['dns_snippet']['value']}"
"""

    return report

print(generate_audit_report("example.com"))

2. Automated Remediation¶

def auto_remediate_cloudflare(domain, api_token):
    """Automatically apply DNS fixes via Cloudflare API"""

    # Get recommendations
    response = requests.post(
        f"{API_URL}/api/v1/recommendations",
        json={"domain": domain},
        headers={"X-API-Key": API_KEY}
    )

    recommendations = response.json()['recommendations']

    # Apply each DNS fix
    for rec in recommendations:
        if rec.get('dns_snippet'):
            dns = rec['dns_snippet']

            # Create DNS record via Cloudflare API
            cloudflare_response = requests.post(
                f"https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records",
                headers={
                    "Authorization": f"Bearer {api_token}",
                    "Content-Type": "application/json"
                },
                json={
                    "type": dns['record_type'],
                    "name": dns['hostname'],
                    "content": dns['value']
                }
            )

            if cloudflare_response.status_code == 200:
                print(f"✓ Applied fix: {rec['action']}")
            else:
                print(f"✗ Failed to apply: {rec['action']}")

3. Progressive Deployment¶

def get_safe_recommendations(domain):
    """Get only safe, non-breaking recommendations for gradual deployment"""

    response = requests.post(
        f"{API_URL}/api/v1/recommendations",
        json={"domain": domain},
        headers={"X-API-Key": API_KEY}
    )

    all_recs = response.json()['recommendations']

    # Filter for safe changes (start with DMARC p=none, avoid breaking changes)
    safe_recs = [
        rec for rec in all_recs
        if rec['issue_code'] in [
            'DMARC_MISSING',  # Start with p=none (safe)
            'DKIM_MISSING',   # Add DKIM (safe, won't break email)
            'SPF_MISSING'     # Add SPF with ~all first (safe)
        ]
    ]

    return safe_recs

# Deploy in phases
phase_1 = get_safe_recommendations("example.com")
for rec in phase_1:
    print(f"Phase 1: {rec['action']}")

Severity Priority¶

Recommendations are ordered by severity:

CRITICAL - Issues that leave your domain completely unprotected
HIGH - Serious security gaps that should be addressed soon
MEDIUM - Moderate issues that reduce effectiveness
LOW - Minor improvements for best practices

Within each severity level, recommendations are sorted by score gain (highest impact first).

DNS Implementation¶

All DNS snippets follow this format:

hostname.example.com. IN TXT "record value"

Where to Add DNS Records¶

Most DNS providers: Use the hostname exactly as shown (e.g., _dmarc.example.com)
Cloudflare/Route53: Enter just the prefix (e.g., _dmarc)
cPanel: Usually requires the full hostname

Verification¶

After applying DNS changes:

Wait 5-10 minutes for DNS propagation
Run GET /api/v1/check?domain=example.com&refresh=true
Verify the issue is resolved and score increased

GET /api/v1/check - Get current issues to fix
GET /api/v1/score - Check score improvement
GET /api/v1/history - Track improvements over time