Frequently Asked Questions¶

Find answers to common questions about the ReputeAPI. Can't find what you're looking for? Visit our Support page.

General Questions¶

What is the ReputeAPI?¶

The ReputeAPI is a comprehensive email security validation service that analyzes your domain's SPF, DKIM, and DMARC configuration. It provides a 0-100 Mailflow Security Score along with actionable recommendations and copy-paste DNS configuration snippets.

Who should use this API?¶

The ReputeAPI is designed for:

• Email marketers - Ensure deliverability before sending campaigns
• IT administrators - Monitor and maintain email security configurations
• SaaS platforms - Integrate email validation into your product
• Security teams - Audit and improve email authentication posture
• Developers - Build tools and dashboards for email security

How is this different from manual DNS lookups?¶

While you can manually query DNS records, the ReputeAPI provides:

• Automated validation - All checks in a single API call
• Intelligent analysis - Identifies misconfigurations and best practice violations
• Actionable insights - Copy-paste DNS snippets to fix issues
• Scoring algorithm - Quantifies your security posture (0-100)
• Historical tracking - Monitor changes over time
• Speed - Sub-second responses with intelligent caching

Getting Started¶

How do I get an API key?¶

1. Sign up at reputeapi.com
2. Verify your email address
3. Navigate to your dashboard
4. Copy your API key from the "API Keys" section

See our Authentication Guide for detailed instructions.

Is there a free tier?¶

Yes! Our free tier includes:

• 10 requests per minute
• 1,000 requests per month
• Full access to all API endpoints
• No credit card required

See Rate Limits for all plan tiers.

Can I test the API without an account?¶

Yes, you can explore our Interactive API Reference with a demo API key. However, you'll need a real API key for production use.

What's the quickest way to get started?¶

Follow our 5-Minute Quick Start guide. You'll make your first API request and understand the response format in under 5 minutes.

API Usage¶

Which endpoint should I use?¶

Choose based on your needs:

See Endpoints Overview for details.

How often can I check the same domain?¶

There are no specific limits on checking the same domain. However:

• Results are cached for 5 minutes
• Repeated identical requests within 5 minutes return cached results (don't count toward rate limits)
• For monitoring, we recommend checking critical domains every 6-24 hours

What happens if I exceed my rate limit?¶

You'll receive a 429 Too Many Requests response with headers indicating:

• X-RateLimit-Limit - Your rate limit
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - When the limit resets (Unix timestamp)

The response body includes a retry_after value in seconds. See Rate Limits for more details.

Can I increase my rate limits?¶

Yes! Upgrade your plan:

Need higher limits? Contact us about enterprise plans.

Technical Questions¶

What DNS records does the API check?¶

The API validates:

• SPF Records - TXT records at the domain root
• DKIM Records - TXT records at selector._domainkey.domain
• DMARC Records - TXT records at _dmarc.domain
• MX Records - Mail exchange records for context

How does DKIM validation work without a selector?¶

The API automatically checks common DKIM selectors including:

• default, google, k1, k2, s1, s2
• dkim, mail, email, smtp
• Selectors from popular email providers (Google Workspace, Office 365, etc.)

You can also specify custom selectors using the dkim_selector parameter. See DKIM Explained for more details.

How is the security score calculated?¶

The 0-100 Mailflow Security Score is based on:

• SPF Configuration (30 points) - Record presence, syntax, and best practices
• DKIM Configuration (30 points) - Key strength, selector validity
• DMARC Configuration (40 points) - Policy strength, alignment, reporting

Points are deducted based on issue severity:

• Critical issues - 20-30 point deduction
• High severity - 10-15 point deduction
• Medium severity - 5-10 point deduction
• Low severity - 1-5 point deduction

See Mailflow Security Score for the complete algorithm.

Why is my score different from other tools?¶

Different tools use different scoring algorithms. Our score emphasizes:

• Email deliverability - Configurations that maximize inbox placement
• Security posture - Protection against spoofing and phishing
• Industry best practices - Alignment with RFC standards and expert recommendations

We prioritize actionable insights over perfect scores.

What DNS resolvers does the API use?¶

We use a multi-tier DNS resolution strategy:

1. Primary: Google Public DNS (8.8.8.8, 8.8.4.4)
2. Secondary: Cloudflare DNS (1.1.1.1, 1.0.0.1)
3. Tertiary: Quad9 DNS (9.9.9.9)

If all fail, the API returns a timeout error. See DNS Configuration for details.

How long does a validation take?¶

Typical response times:

• Cached results: 50-100ms
• Fresh validation: 200-500ms
• Complex domains: 500ms-2s (many SPF includes or DNS delays)
• Timeout threshold: 10 seconds

99% of requests complete within 500ms.

Authentication & Security¶

How do I authenticate API requests?¶

Include your API key in the request header:

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

See Authentication for all methods.

Are API keys secure?¶

Yes. Best practices:

• Keys are transmitted over HTTPS only
• Keys are hashed in our database
• Keys can be rotated anytime
• Keys can be scoped to specific IP ranges (Enterprise plans)

Never commit API keys to version control or share them publicly.

Can I rotate my API key?¶

Yes! In your dashboard:

1. Navigate to "API Keys"
2. Click "Generate New Key"
3. Update your applications with the new key
4. Delete the old key once migration is complete

Old keys remain valid until explicitly deleted.

Can I restrict API keys by IP address?¶

IP-based restrictions are available on Enterprise plans. Contact sales@reputeapi.com for details.

Results & Recommendations¶

What do the severity levels mean?¶

Issues are classified by impact:

• Critical - Immediate threat or complete misconfiguration (e.g., no DMARC policy)
• High - Significant vulnerability or deliverability issue (e.g., DMARC policy "none")
• Medium - Best practice violation or minor misconfiguration (e.g., missing DMARC reporting)
• Low - Optimization opportunity (e.g., SPF record could be simplified)

Focus on fixing critical and high-severity issues first.

How do I fix the issues found?¶

Each issue includes:

• Description - What the problem is
• Remediation - How to fix it
• DNS Snippet - Copy-paste DNS configuration

For example:

{
  "code": "DMARC_POLICY_NONE",
  "remediation": "Change your DMARC policy to 'quarantine' or 'reject'",
  "dns_snippet": {
    "generic": "_dmarc.example.com. IN TXT \"v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com\""
  }
}

See Common Scenarios for step-by-step guides.

Can I customize the recommendations?¶

Custom scoring and recommendation rules are available on Enterprise plans. This allows you to:

• Define organization-specific security policies
• Adjust severity levels
• Add custom validation rules
• Exclude specific checks

Contact us about enterprise features.

Why doesn't the API detect all my DKIM selectors?¶

The API checks common selectors automatically, but some organizations use custom selectors. You can specify them explicitly:

curl "https://api.reputeapi.com/api/v1/check?domain=example.com&dkim_selector=custom123"

See DKIM Explained for selector discovery strategies.

Billing & Plans¶

How does billing work?¶

Billing is based on your plan tier:

• Free - No billing, 1,000 requests/month
• Basic - $29/month, 10,000 requests/month
• Premium - $99/month, 50,000 requests/month

Monthly quotas reset on the 1st of each month. Unused requests don't roll over.

What happens if I exceed my monthly quota?¶

Requests beyond your quota receive a 402 Payment Required response. Options:

1. Upgrade - Move to a higher tier instantly
2. Wait - Quota resets on the 1st of next month
3. One-time top-up - Purchase additional requests (contact support)

Can I downgrade my plan?¶

Yes, anytime. Downgrades take effect at the end of your current billing period. You won't lose access immediately.

Do you offer annual billing?¶

Yes! Annual billing includes a 20% discount:

• Basic - $278/year (save $70)
• Premium - $950/year (save $238)

Select annual billing during checkout or contact support to switch.

Is there a refund policy?¶

Yes. We offer a 30-day money-back guarantee on all paid plans. No questions asked. Contact support@reputeapi.com for refunds.

Integration & Development¶

Do you have SDKs or client libraries?¶

Official SDKs are in development:

• Python SDK - Q1 2025 (coming soon)
• JavaScript/TypeScript SDK - Q1 2025 (coming soon)
• CLI Tool - Q2 2025 (planned)

In the meantime, see our integration guides:

• Python Guide
• JavaScript Guide
• cURL Examples

Can I use this in a web browser?¶

Yes, but be careful with API keys! Recommendations:

• Backend proxy - Call the API from your server, not client-side JavaScript
• CORS - The API supports CORS for trusted origins (configure in dashboard)
• Read-only keys - Use keys with limited permissions for client-side use (Enterprise feature)

Never expose full API keys in frontend code.

How do I handle errors?¶

The API uses standard HTTP status codes:

• 200 - Success
• 400 - Bad request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 429 - Rate limit exceeded
• 500 - Server error

Response bodies include detailed error messages. See Error Codes.

Can I use this in CI/CD pipelines?¶

Absolutely! Common use cases:

• Pre-deployment validation - Check DNS configuration before deploying
• Scheduled monitoring - Daily/weekly security audits
• Pull request checks - Validate DNS changes in PRs

We're developing a GitHub Action for this purpose (Q2 2025).

Data & Privacy¶

What data do you store?¶

We store:

• API request metadata (timestamp, domain, endpoint)
• Validation results (for historical tracking)
• DNS query responses (cached for 5 minutes)

We do NOT store:

• Email addresses found in DNS records (except as part of cached responses)
• Any data beyond DNS public records

Is my data shared with third parties?¶

No. Your validation data is private and never shared with third parties. We use DNS query results solely to provide the service.

Can I delete my data?¶

Yes. Contact privacy@reputeapi.com to request data deletion. We'll remove all associated data within 30 days.

Is the API GDPR compliant?¶

Yes. We're committed to GDPR compliance:

• Data processing agreements available
• Data deletion requests honored
• Minimal data retention
• EU data residency options (Enterprise plans)

Troubleshooting¶

Why is my domain's score low?¶

Common reasons:

• No DMARC policy - 40-point penalty
• SPF missing or invalid - 30-point penalty
• DKIM not configured - 30-point penalty
• DMARC policy "none" - 10-15 point penalty

Review the issues array in the API response for specific problems.

The API says my SPF record is invalid, but it works¶

The API enforces best practices and RFC standards more strictly than some mail servers. Common issues:

• Too many DNS lookups - SPF limited to 10 lookups
• Invalid syntax - Extra spaces, typos
• Deprecated mechanisms - Using ptr mechanism

Follow the recommendations to ensure maximum deliverability.

Why doesn't the API find my DKIM record?¶

Possible reasons:

1. Custom selector - Specify it explicitly with dkim_selector parameter
2. DNS propagation - Wait 5-10 minutes after DNS changes
3. Invalid syntax - Check for typos in your DNS records
4. Subdomain DKIM - Ensure selector is at selector._domainkey.domain

See DKIM Explained for troubleshooting steps.

I'm getting timeout errors¶

Causes:

• Slow DNS servers - Your domain's DNS servers are slow to respond
• DNS configuration issues - Circular SPF includes, invalid records
• Network issues - Temporary connectivity problems

Try again in a few minutes. If the issue persists, check your DNS provider's status page.

Still Have Questions?¶