Trust Verification API

The Trust Verification API validates and analyzes email addresses in real-time based on your project's configured rules.

The response, validations, and internal behavior of this API always depend on the enabled project rules. You can read more about project rules here.

Endpoint

https://api.autheona.com/v1/public/verify

Method

POST

Authentication

All requests must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens are created in your project settings. Each token is unique to a project.

Security Best Practices:

• Never expose tokens in client-side code
• Store tokens securely using environment variables
• Never commit tokens to version control
• Rotate tokens periodically
• Revoke compromised tokens immediately
• Use separate tokens for different environments

Request Headers

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Rate Limits

Rate limits are enforced per access token:

• Limit: 10 requests per second
• Window: 1 second
• TTL: 3 seconds

If you exceed the rate limit, implement exponential backoff in your integration.

Request Parameters

Body Parameters (JSON)

Sample Request Body:

{
  "email_address": "test@test.com",
  "ipv4_address": "192.168.1.1",
  "ipv6_address": "2001:db8:3333:4444:5555:6666:7777:8888",
  "soft_check": false,
  "show_results": true,
  "show_steps": false
}

Response

Success Response (HTTP 200)

{
  "action": "allow",
  "errors": ["error_code"],
  "warnings": ["warning_code"],
  "risk_score": 15,
  "risk_level": "low",
  "risk_score_breakdown": {},
  "corrected_email": "corrected@example.com",
  "punycode_email": "xn--example@domain.com",
  "is_free_provider_domain": false,
  "is_role_based_domain": false,
  "is_disposable_domain": false,
  "is_known_abuse_domain": false,
  "is_spam_trap_domain": false,
  "is_education_domain": false,
  "is_government_domain": false,
  "has_multiple_emails_in_ip": false,
  "steps": ["structure", "mx_record", "..."],
  "checked_types": ["mx_record", "disposable_domain"],
  "analyzed_data": {}
}

Response Fields

Validation Steps

When show_steps is true, the response includes which validation steps were executed:

Error Codes

When show_results is true and validation fails, error codes are returned:

Format Errors:

Local Part Errors:

Subdomain Errors:

Domain Errors:

Provider/Classification Errors:

• not_in_specific_domains - Not in allowed domains list

DNS Errors:

Detection Errors:

Internationalization Errors:

Other Errors:

Warning Codes

Warnings indicate soft failures that don't block validation:

Checked Types

When show_results is true, the checked_types array indicates which validation types were performed:

Analyzed Data Fields

When show_results is true, the analyzed_data object may include:

DNS Information:

Domain Analysis:

Deliverability Scores:

Risk Detection:

IP Analysis:

Velocity Tracking:

Examples

Basic Validation

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"email_address": "user@example.com"}'

Response:

{
  "action": "allow"
}

Validation with Details

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "user@example.com",
    "show_results": true,
    "show_steps": true
  }'

Response:

{
  "action": "allow",
  "is_free_provider_domain": false,
  "is_role_based_domain": false,
  "is_disposable_domain": false,
  "is_known_abuse_domain": false,
  "is_spam_trap_domain": false,
  "is_education_domain": false,
  "is_government_domain": false,
  "has_multiple_emails_in_ip": false,
  "steps": [
    "structure",
    "local_plus",
    "local_dot",
    "mx_record",
    "disposable_domain",
    "deliverability_score",
    "domain_health"
  ],
  "checked_types": [
    "address_format",
    "mx_record",
    "disposable_domain"
  ],
  "analyzed_data": {
    "mx_record_count": "3",
    "mx_record_status": "valid",
    "a_record_fallback": "not_needed",
    "domain_age_days": "168",
    "domain_age_signal": "established",
    "domain_health": "excellent",
    "deliverability_score": "95",
    "deliverability_mx_score": "35",
    "deliverability_age_score": "20",
    "deliverability_subdomain_score": "10",
    "subdomain_count": "0"
  }
}

Failed Validation

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "admin@tempmail.com",
    "show_results": true
  }'

Response:

{
  "action": "block",
  "errors": [
    "invalid_address_format"
  ],
  "checked_types": [
    "address_format"
  ]
}

Typo Detection

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "user@gmial.com",
    "show_results": true
  }'

Response (with soft warning mode):

{
  "action": "allow",
  "corrected_email": "user@gmail.com",
  "warnings": ["domain_typo_detected"],
  "checked_types": ["typo_detection"]
}

Response (with hard block mode):

{
  "action": "block",
  "corrected_email": "user@gmail.com",
  "errors": ["domain_typo_detected"],
  "checked_types": ["typo_detection"]
}

Soft Check

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "user@example.com",
    "soft_check": true
  }'

Performs validation without storing domain information. Analytics data is still stored, but detailed domain data is not saved. Use this for preliminary checks where you don't need full domain tracking.

Risk Scoring

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "user@xk4j2.newdomain.xyz",
    "show_results": true
  }'

Response:

{
  "action": "challenge",
  "risk_score": 75,
  "risk_level": "high",
  "warnings": ["fraud_pattern_detected"],
  "is_free_provider_domain": false,
  "is_role_based_domain": false,
  "is_disposable_domain": false,
  "is_known_abuse_domain": false,
  "is_spam_trap_domain": false,
  "is_education_domain": false,
  "is_government_domain": false,
  "has_multiple_emails_in_ip": false,
  "analyzed_data": {
    "domain_age_days": "5",
    "domain_age_signal": "new_domain",
    "domain_health": "suspicious",
    "random_subdomain_signal": "detected",
    "subdomain_entropy": "high",
    "risk_breakdown_signals": "new_domain,random_subdomain"
  }
}

IP-Based Validation

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "user@example.com",
    "ipv4_address": "1.2.3.4",
    "show_results": true
  }'

Response:

{
  "action": "allow_with_review",
  "warnings": ["vpn_detected"],
  "is_free_provider_domain": true,
  "is_role_based_domain": false,
  "is_disposable_domain": false,
  "is_known_abuse_domain": false,
  "is_spam_trap_domain": false,
  "is_education_domain": false,
  "is_government_domain": false,
  "has_multiple_emails_in_ip": false,
  "analyzed_data": {
    "ipv4_provider": "aws",
    "vpn": "detected"
  }
}

When an IP address is provided, the API performs additional checks:

• VPN/proxy detection
• Cloud provider identification (AWS, GCP, Azure, etc.)
• Bot detection (OpenAI, Mistral, etc.)

These checks contribute to the risk score and can trigger warnings for enhanced fraud prevention.

Velocity Tracking

curl -X POST https://api.autheona.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "email_address": "test@test.com",
    "ipv4_address": "203.0.113.42",
    "show_results": true
  }'

Response:

{
  "action": "block",
  "has_multiple_emails_in_ip": true,
  "risk_score": 85,
  "risk_level": "high",
  "warnings": ["multiple_accounts_detected"],
  "is_free_provider_domain": false,
  "is_role_based_domain": false,
  "is_disposable_domain": false,
  "is_known_abuse_domain": false,
  "is_spam_trap_domain": false,
  "is_education_domain": false,
  "is_government_domain": false,
  "checked_types": [
    "address_format",
    "multiple_emails_in_ip",
    "risk_score"
  ],
  "analyzed_data": {
    "emails_in_ip": [
      {
        "email_address": "user1@example.com",
        "created_time": "2026-04-29 16:18:42 +0530"
      },
      {
        "email_address": "user2@example.com",
        "created_time": "2026-04-29 16:18:51 +0530"
      },
      {
        "email_address": "user3@example.com",
        "created_time": "2026-04-29 16:20:10 +0530"
      },
      {
        "email_address": "admin@example.org",
        "created_time": "2026-04-29 16:25:16 +0530"
      },
      {
        "email_address": "contact@sample.com",
        "created_time": "2026-04-29 16:30:12 +0530"
      },
      {
        "email_address": "info@demo.net",
        "created_time": "2026-04-29 16:34:01 +0530"
      },
      {
        "email_address": "hello@placeholder.org",
        "created_time": "2026-04-29 16:34:10 +0530"
      },
      {
        "email_address": "support@testmail.com",
        "created_time": "2026-04-29 16:34:25 +0530"
      },
      {
        "email_address": "noreply@example.net",
        "created_time": "2026-04-29 16:52:12 +0530"
      },
      {
        "email_address": "webmaster@sample.org",
        "created_time": "2026-04-29 16:52:19 +0530"
      }
    ],
    "total_email_in_ip": "10",
    "emails_in_ip_last_5_minutes": "0",
    "emails_in_ip_last_10_minutes": "0",
    "emails_in_ip_last_15_minutes": "0",
    "emails_in_ip_last_30_minutes": "0",
    "emails_in_ip_last_2_hour": "10",
    "emails_in_ip_last_3_hour": "10"
  }
}

When velocity tracking is enabled, the API monitors multiple account attempts from the same IP address. This helps detect:

• Account creation abuse
• Automated bot attacks
• Fraudulent bulk registrations

The emails_in_ip array shows the complete history, while the time-based counters help identify burst patterns.

Error Responses

Bad Request (HTTP 400)

Returned when request parameters are invalid.

Internal Server Error (HTTP 500)

Returned when an unexpected error occurs:

{
  "code": 500,
  "error": "Error message describing what went wrong",
  "id": "a7db4e2b-7bc1-4a82-bc19-4ff6a2e7f778",
  "status": false
}

The id field contains a unique identifier for tracking the error.

Best Practices

• Use show_results sparingly - Only enable when you need detailed analysis to reduce response size and improve performance.
• Cache results - Cache validation results for frequently used domains to reduce API calls and stay within rate limits.
• Handle corrected emails - When typo detection returns a corrected_email field, prompt users to correct their email before proceeding.
• Use action field - The action field provides recommended actions (allow, challenge, block, etc.) based on validation results and risk levels. Use this to implement appropriate user experiences.
• Check classification flags - Use the is_* boolean fields to understand what type of domain/address was detected. These flags are returned when their corresponding checks are enabled in your project rules.
• Monitor velocity patterns - When Multiple Accounts from Same IP is enabled, use the has_multiple_emails_in_ip flag and time-based counters to detect and prevent account creation abuse.
• Interpret risk scores - Use risk scores for additional fraud checks and scoring, not as hard blocks on signups.
• Leverage IP validation - Include IP addresses in requests for enhanced fraud detection through VPN detection and provider identification.
• Test with sandbox - Use sandbox projects to test rule configurations before production. Sandbox calls don't count toward quota.
• Monitor soft checks - Use soft checks for non-critical validations where you don't need full domain tracking.
• Implement rate limit handling - Respect the 10 requests per second limit. Implement exponential backoff if you receive rate limit errors.
• Secure your tokens - Never expose access tokens in frontend code. Always call the API from your backend.

Response Time

Average response time is under 200ms. Response time may vary based on:

• Number of enabled validation rules
• DNS lookup requirements
• Domain age lookup requirements