API Endpoints Overview¶

Complete reference of all ReputeAPI endpoints.

Mailflow Security API (Primary)¶

The main API for comprehensive email security analysis.

When to Use Each Endpoint¶

Use /api/v1/check when: - You need detailed SPF/DKIM/DMARC results - You want actionable remediation steps - You need DNS snippets for fixes - You're doing a comprehensive audit

Use /api/v1/score when: - You only need the score number - You're building a dashboard - You want faster responses - You're checking many domains quickly

Use /api/v1/recommendations when: - You want prioritized action items - You need copy-paste DNS fixes - You're guiding users through improvements - You want score impact calculations

Use /api/v1/history when: - Tracking improvements over time - Generating compliance reports - Detecting regressions - Creating trend charts

Validation API (Legacy)¶

Simpler validation endpoints for basic checks.

Usage & Management¶

Endpoint Comparison¶

Response Size¶

Caching¶

Use ?refresh=true to bypass cache.

Common Patterns¶

Pattern 1: Quick Health Check¶

# Check score only
response = requests.get(
    f"{API_URL}/api/v1/score",
    params={"domain": "example.com"},
    headers={"X-API-Key": API_KEY}
)

if response.json()['score'] < 70:
    print("⚠️ Security issues detected!")

Pattern 2: Full Audit¶

# Get full details
response = requests.get(
    f"{API_URL}/api/v1/check",
    params={"domain": "example.com"},
    headers={"X-API-Key": API_KEY}
)

result = response.json()

# Show issues
for issue in result['issues']:
    print(f"[{issue['severity']}] {issue['message']}")

Pattern 3: Guided Remediation¶

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

result = response.json()

# Show fixes
print(f"Current score: {result['current_score']}")
print(f"Potential score: {result['potential_score']}")

for rec in result['recommendations']:
    print(f"\n{rec['priority']}. {rec['action']}")
    if rec.get('dns_snippet'):
        print(f"   DNS: {rec['dns_snippet']['value']}")

Pattern 4: Bulk Check¶

# Check multiple domains
domains = ["domain1.com", "domain2.com", "domain3.com"]

response = requests.post(
    f"{API_URL}/v1/validate/bulk",
    json={"domains": domains},
    headers={"X-API-Key": API_KEY}
)

for result in response.json()['results']:
    print(f"{result['domain']}: {result['score']}/100")

Pattern 5: Trend Analysis¶

# Get historical data
response = requests.get(
    f"{API_URL}/api/v1/history",
    params={"domain": "example.com", "days": 30},
    headers={"X-API-Key": API_KEY}
)

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

# Calculate trend
first_score = snapshots[-1]['score']
latest_score = snapshots[0]['score']
improvement = latest_score - first_score

print(f"Score trend: {improvement:+d} points over 30 days")

Rate Limits¶

All endpoints share the same rate limits based on your plan tier:

See Rate Limits for details.

Authentication¶

All endpoints require an API key via the X-API-Key header:

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

See Authentication for details.

Error Handling¶

All endpoints return consistent error responses:

{
  "error": "Error type",
  "message": "Detailed error message",
  "code": "ERROR_CODE"
}

Common HTTP status codes: - 200 OK - Success - 400 Bad Request - Invalid parameters - 401 Unauthorized - Missing/invalid API key - 404 Not Found - Resource not found - 429 Too Many Requests - Rate limit exceeded - 500 Internal Server Error - Server error

See Common Errors for troubleshooting.

Next Steps¶

• Interactive API - Try endpoints in your browser
• Quick Start - Make your first request
• Code Examples - Ready-to-use code