API Documentation

Welcome to the DeGhost API. Our endpoints allow you to validate users in real-time by analyzing their Email, Domain, and IP address.

Authentication

Currently, all endpoints are public for integration testing. Rate limits apply per IP. Contact us for production API keys.

Base URL

https://deghostapi.hexbyte.dev

All API requests use this base URL. Append the endpoint paths shown below.

1. Email Validation

Validates an email address by checking syntax, domain existence, and MX records. Also checks internal blacklists for disposable providers.

GET

https://deghostapi.hexbyte.dev/email/:email

Example Request

cURL

curl -X GET "https://deghostapi.hexbyte.dev/email/[email protected]"

Response

JSON

{
  "status": "allowed",
  "has_mx": true,
  "disposable": false,
  "spam": false,
  "public_domain": false,
  "relay_domain": false,
  "blacklisted": false,
  "domain_age_in_days": 365
}

Field	Type	Description
`status`	string	Overall validation status: 'allowed', 'not_allowed', or 'not_applicable'
`has_mx`	boolean	Whether the domain has valid MX records
`disposable`	boolean	True if from a disposable email provider
`spam`	boolean	True if domain is known for spam
`public_domain`	boolean	True if public email provider (Gmail, etc.)
`relay_domain`	boolean	True if used as email relay
`blacklisted`	boolean	True if domain is blacklisted
`domain_age_in_days`	number	Domain age in days since registration

Status Codes

Status Code	Description
200	Email validated successfully (Allowed)
400	Invalid input format
403	Forbidden: Email is disposable, spam, or has no MX records
429	Rate limit exceeded
499	Client Closed Request
504	Gateway Timeout (>5s)

2. Domain Validation

Isolates the check to the domain level. Useful if you want to allow specific email patterns but block entire domain providers.

GET

https://deghostapi.hexbyte.dev/domain/:domain

Example Request

cURL

curl -X GET "https://deghostapi.hexbyte.dev/domain/example.com"

Response

JSON

{
  "status": "allowed",
  "has_mx": true,
  "disposable": false,
  "spam": false,
  "public_domain": false,
  "relay_domain": false,
  "blacklisted": false,
  "domain_age_in_days": 365
}

Field	Type	Description
`status`	string	Overall validation status: 'allowed', 'not_allowed', or 'not_applicable'
`has_mx`	boolean	Whether the domain has valid MX records
`disposable`	boolean	True if from a disposable email provider
`spam`	boolean	True if domain is known for spam
`public_domain`	boolean	True if public email provider (Gmail, etc.)
`relay_domain`	boolean	True if used as email relay
`blacklisted`	boolean	True if domain is blacklisted
`domain_age_in_days`	number	Domain age in days since registration

Status Codes

Status Code	Description
200	Domain validated successfully
400	Invalid domain format
403	Forbidden: Domain is disposable, spam, or invalid
429	Rate limit exceeded
499	Client Closed Request
504	Gateway Timeout (>5s)

3. IP Intelligence

Checks the IP address against global threat databases. Returns detailed security flags to help you decide whether to block the user.

GET

https://deghostapi.hexbyte.dev/ip/:ip

Example Request

cURL

curl -X GET "https://deghostapi.hexbyte.dev/ip/8.8.8.8"

Response

JSON

{
  "ip": "8.8.8.8",
  "status": "success",
  "ip_version": 4,
  "risk_score": 0,
  "security": {
    "is_abuser": false,
    "is_attacker": false,
    "is_bogon": false,
    "is_cloud_provider": true,
    "is_proxy": false,
    "is_relay": false,
    "is_tor": false,
    "is_tor_exit": false,
    "is_vpn": false,
    "is_anonymous": false,
    "is_threat": false
  }
}

Security Recommendation

We recommend blocking the user if any of these fields are true:

• is_abuser
• is_attacker
• is_threat

Field	Type	Description
`ip`	string	The requested IP address
`status`	string	Response status: 'success' or error type
`ip_version`	number	IP version (4 or 6)
`risk_score`	number	Risk score from 0 (safe) to 100 (malicious)
`security.is_abuser`	boolean	IP has history of abusive behavior
`security.is_attacker`	boolean	IP is known for attacks
`security.is_bogon`	boolean	IP is unallocated or reserved
`security.is_cloud_provider`	boolean	IP belongs to cloud hosting
`security.is_proxy`	boolean	IP is a known proxy server
`security.is_relay`	boolean	IP is used as relay
`security.is_tor`	boolean	IP is part of Tor network
`security.is_tor_exit`	boolean	IP is a Tor exit node
`security.is_vpn`	boolean	IP associated with VPN services
`security.is_anonymous`	boolean	IP used for anonymous browsing
`security.is_threat`	boolean	IP identified as active threat

Status Codes

Status Code	Description
200	IP validated successfully
403	Forbidden: Private/Reserved/Localhost IP
429	Rate limit exceeded
500	Internal Server Error

Need help with integration?

Contact Support