Project Rules

Project rules control how email validation is performed when you call the Autheona API. Rules let you decide what gets checked, what gets blocked, and how strict validation should be.

What Are Project Rules

Rules are validation settings configured per project. When the API receives an email address, it applies your project's rules to determine if the email should be accepted, rejected, or flagged for review.

Rules give you control over:

Email format requirements
Domain structure validation
Fraud detection sensitivity
Disposable email blocking
Custom domain restrictions

Accessing Project Rules

Open your project page
Click the Settings button
Navigate to the Project Rules section
Configure rules by toggling checkboxes
Add custom values to array fields where applicable

Changes are saved automatically.

Rule Categories

Local Part Structure

Control what characters and formats are allowed in the email address before the @ symbol.

Plus Addressing - Allow user+tag@example.com style addresses. Gmail, Fastmail, and ProtonMail support this.
Dot Variations - Allow u.s.e.r@example.com style addresses. Gmail treats dots as insignificant.
Hyphen in Local Part - Allow first-last@example.com style addresses. Valid per RFC 5321 and common in corporate email.
Underscore in Local Part - Allow first_last@example.com style addresses. Fully RFC-valid and very common.
Numeric Local Part - Allow all-digit local parts such as 1234567@example.com. RFC-valid.
Quoted Local Part - Allow "user name"@example.com with spaces or special chars inside quotes. Rarely supported by mail providers.
Special Chars in Local Part - Allow special characters like !#$%&'*/=?^_{|}~` unquoted in the local part. Technically valid per RFC 5321 but often rejected.
Empty Local Part - Allow @example.com with no local part. Invalid per RFC 5321 - always reject.

Subdomain Structure

Control what subdomain patterns are acceptable in email addresses.

Single Subdomain - Allow addresses with at most 1 subdomain label like user@mail.example.com. Addresses with 2+ subdomain labels are blocked.
Double Subdomain - Allow addresses with at most 2 subdomain labels like user@api.v1.example.com. Addresses with 3+ subdomain labels are blocked.
Triple Subdomain - Allow addresses with at most 3 subdomain labels like user@us.prod.api.example.com. Addresses with 4+ subdomain labels are blocked.
Wildcard Subdomain - Allow wildcard (*) labels anywhere in the subdomain chain like user@*.example.com.
Hyphenated Subdomain - Allow subdomain labels that contain hyphens like user@my-app.example.com.
Numeric Subdomain - Allow subdomain labels that are entirely numeric like user@123.example.com.
UUID/Hash Subdomain - Allow UUID or hex-hash style subdomain labels like user@a1b2c3d4.example.com.
Deeply Nested Subdomain - Allow 4 or more subdomain labels with no upper depth limit enforced like user@a.b.c.d.example.com.

Domain Structure

Control what domain formats are acceptable.

IPv4 Address Domain - Allow bracketed IPv4 literals as the domain per RFC 5321 like user@[192.168.1.1].
IPv6 Address Domain - Allow bracketed IPv6 literals as the domain per RFC 5321 like user@[IPv6:2001:db8::1].
Single-label Domain - Allow domains with no dot (single label), valid in internal contexts like user@localhost.
Numeric-only Domain - Allow all-numeric domain labels with no dots. Effectively unroutable for real mail like user@1234.

Internationalization

Control support for non-ASCII email addresses.

Internationalized Email - Allow RFC 6531 EAI addresses with Unicode local-part and/or domain like 用户@例子.广告.
Punycode Email - Allow ASCII-compatible encoded (Punycode) IDN domains like user@xn--mnchen-3ya.de.
Mixed Script Email - Allow addresses where the local-part is ASCII but the domain contains Unicode like user@münchen.de.

Disposable Structure

Control catch-all and disposable patterns.

Catch-all Wildcard - Allow wildcard local-part (*) which signals a catch-all server configuration like *@example.com.

Length Validation

Enforce RFC-compliant length limits on email components.

Enforce Local Part Max Length - Enforce that the local part is at most 64 characters per RFC 5321.
Enforce Domain Max Length - Enforce that the domain part is at most 255 characters per RFC 5321.
Enforce Total Address Length - Enforce that the full address is at most 320 characters per RFC 5321.
Enforce Label Max Length - Enforce that each DNS label is at most 63 characters per RFC 1035.

DNS & Network Reachability

Verify that email domains have proper DNS configuration.

-MX Record Check - Verify that at least one MX record exists for the domain. No MX means the address is undeliverable. -Fallback A Record Check - If no MX exists, check for an A/AAAA record as an implicit MX fallback per RFC 5321.

Typo Detection & Correction

Catch common typos in popular email domains.

Enable Typo Detection - Detect common domain typos such as gmial.com, gmal.com, yaho.com, and hotmial.com.
Enable Suggestion Engine - Return a corrected email suggestion when a typo is detected like user@gmial.com becomes user@gmail.com.
Soft Warning Mode - Instead of hard-blocking on typo detection, return a suggest_correction status to reduce signup friction.

Fraud Detection

Identify suspicious patterns in email addresses.

Fraud Pattern Detection - Detect suspicious local-part patterns such as high-entropy strings, keyboard walks like asdfgh@example.com, or sequential numbers like user123456@example.com.
Soft Warning Mode (Fraud Detection) - Instead of hard-blocking on fraud detection, return a warning status to allow signup but flag for review.

Provider & Account Classification

Control which types of email providers and accounts are checked during validation.

Free Provider Domain - Check if the domain is a known free provider (e.g. Gmail, Yahoo, Outlook). When enabled, this check contributes to risk scoring and action determination.
Role-based Domain - Check if the local part is role-based such as admin@, support@, info@, and noreply@. When enabled, this check contributes to risk scoring and action determination.
Disposable Domain - Check if the domain is a known disposable/temporary email provider. When enabled, this check contributes to risk scoring and action determination.
Known Abuse Domain - Check if the domain is flagged as a source of abuse or spam. When enabled, this check contributes to risk scoring and action determination.
Spam Trap Domain - Check if the domain is associated with known spam traps. When enabled, this check contributes to risk scoring and action determination.
Educational Domain - Check if the domain is a known educational institution domain like .edu. When enabled, non-educational domains contribute to risk scoring and action determination.
Government Domain - Check if the domain is a known government domain like .gov. When enabled, non-government domains contribute to risk scoring and action determination.
Only Use Custom Roles - When enabled, only use the custom role local parts list instead of the built-in role list.
Only Use Custom Educational Domains - When enabled, only use the custom educational domains list instead of the built-in educational domains list.
Only Use Custom Government Domains - When enabled, only use the custom government domains list instead of the built-in government domains list.
Only Use Specific Domains - When enabled, only accept email addresses from the domains specified in the Specific Domains Only list. All other domains will be rejected.
Custom Role Local Parts - Additional local parts to treat as role-based addresses like billing, ops. Add values one at a time.
Custom Educational Domains - Additional domains to treat as educational institutions beyond the built-in list. Add values one at a time.
Custom Government Domains - Additional domains to treat as government domains beyond the built-in list. Add values one at a time.
Specific Domains Only - Restrict accepted addresses to only these specific domains. All other domains will be rejected. Add values one at a time.

Subdomain Risk Detection

Flag potentially risky subdomain patterns.

Random Subdomain Signal - Flag subdomains that appear randomly generated (high entropy) like user@xk4j2.example.com - common in fraud and temp-mail setups.
Deep Nesting Risk Signal - Flag domains with 3 or more subdomain labels as suspicious, since they are rarely used in legitimate mail.
UUID Subdomain Risk Signal - Flag UUID or hash-style subdomains like user@a1b2c3d4fe56.example.com - a common burner or preview domain pattern.

Abuse Prevention

Detect newly registered domains often used in fraud campaigns.

Domain Age Signal - Heuristic flag for newly registered domains (less than 30 days old) via WHOIS/RDAP. New domains are common in fraud campaigns.

Deliverability Protection

Score and classify email deliverability.

Deliverability Score - Compute a 0-100 likelihood score that the address can receive mail, based on MX and domain health signals.
Domain Health Classification - Classify the domain as healthy, risky, or unknown based on DNS health, MX quality, and abuse signals.

Risk Scoring

Compute overall risk metrics for email addresses.

Enable Risk Score - Compute a composite 0-100 risk score per email based on all enabled checks. 0 = clean, 100 = high risk.
Include Score Breakdown - Include per-signal score contributions in the API response risk breakdown object. Useful for transparency and debugging.

Track Velocity

Monitor and detect suspicious account creation patterns.

Multiple Accounts from the Same IP Address - Check whether a user has attempted to create multiple accounts using different email addresses from the same IPv4 or IPv6 address. When enabled, tracks and returns the history of email addresses validated from the same IP, including time-based counts (last 5, 10, 15, 30 minutes, 2 hours, 3 hours) and total count across the entire project.

Rule Presets

Autheona provides presets for common use cases. Select a preset to automatically configure rules:

Verified Sign Up - For signup flows that have email verification. Balanced validation with moderate strictness.
Unverified Sign Up - For signup flows without email verification. Stricter validation to compensate for lack of verification step.
Magic Link - For magic link via email sign in/up flows. Optimized for deliverability to ensure links arrive.
Newsletter - For email subscriptions in newsletters. Focused on deliverability and blocking disposable addresses.

Presets are starting points. After applying a preset, you can customize individual rules to fit your specific needs.

Best Practices

Start with a preset - Choose the preset that matches your use case, then customize.
Test in sandbox - Try different rule configurations in a sandbox project before applying to production.
Balance friction and security - Stricter rules improve security but may reject legitimate users. Find the right balance for your product.
Use soft warning modes - For typos and fraud detection, consider soft warnings instead of hard blocks to reduce false positives.
Monitor analytics - Watch your project dashboard to see how rules affect validation rates.
Adjust based on data - If you see high rejection rates, review which rules are causing blocks and adjust accordingly.

Rule Examples

Here are practical examples of how different rule configurations affect validation:

Example 1: Strict B2B SaaS

For enterprise software requiring corporate emails only:

Enabled Rules:

Free Provider Domain
Disposable Domain
Role-based Domain
MX Record Check
Enable Typo Detection with Suggestion Engine
Enable Risk Score

Result:

john@company.com - Action: allow
john@gmail.com - Action: block or challenge (free provider detected, high risk score)
support@company.com - Action: block or warn (role-based detected)
john@tempmail.com - Action: block (disposable detected, high risk score)
john@compnay.com - Action: allow with suggestion to john@company.com

Example 2: Consumer App with Verification

For apps with email verification step:

Enabled Rules:

Disposable Domain
MX Record Check
Plus Addressing (allowed)
Dot Variations (allowed)
Enable Typo Detection with Soft Warning Mode
Enable Risk Score

Result:

user@gmail.com - Action: allow
user+tag@gmail.com - Action: allow (plus addressing allowed)
u.s.e.r@gmail.com - Action: allow (dot variations allowed)
user@10minutemail.com - Action: block (disposable detected, high risk score)
user@gmial.com - Action: allow with warning and suggestion

Example 3: Newsletter Subscription

For email lists focused on deliverability:

Enabled Rules:

Disposable Domain
Role-based Domain
MX Record Check
Fallback A Record Check
Deliverability Score Enabled
Domain Health Classification
Enable Risk Score

Result:

user@gmail.com - Action: allow (high deliverability score)
newsletter@company.com - Action: block or warn (role-based detected)
user@newdomain.xyz - Action: allow_with_review (low deliverability score)
user@10minutemail.com - Action: block (disposable detected, high risk score)

Example 4: Educational Platform

For platforms restricted to students:

Enabled Rules:

Educational Domain
Role-based Domain
Only Use Specific Domains (with educational domains list)
MX Record Check
Enable Risk Score

Result:

student@university.edu - Action: allow
john@gmail.com - Action: block (not in allowed domains list)
admin@university.edu - Action: block or warn (role-based detected)
student@school.k12.us - Action: allow (educational domain)

Example 5: Magic Link Authentication

For passwordless login flows:

Enabled Rules:

Disposable Domain
MX Record Check
Deliverability Score Enabled
Enable Typo Detection with Suggestion Engine
Fraud Pattern Detection with Soft Warning Mode
Enable Risk Score

Result:

user@gmail.com - Action: allow (high deliverability)
user@tempmail.com - Action: block (disposable detected, magic link won't work)
asdfghjkl@example.com - Action: allow_with_review with warning (fraud pattern detected but soft mode)
user@gmial.com - Action: allow with suggested correction before sending magic link

Example 6: Custom Domain Whitelist

For internal tools or partner portals:

Enabled Rules:

Only Use Specific Domains
Specific Domains Only: company.com, partner1.com, partner2.com
MX Record Check

Result:

employee@company.com - Action: allow
user@partner1.com - Action: allow
user@gmail.com - Action: block (not in whitelist)
contractor@external.com - Action: block (not in whitelist)