API Documentation

Everything you need to integrate NovaCheck into your application.

Quick Start

Sign up at novacheck.io/dashboard
Create an API key in the dashboard
Make your first validation request:

curl -X GET "https://api.novacheck.io/v1/email?email=test@example.com" \
  -H "X-API-Key: nc_live_your_api_key_here"

Test Keys

When you create an API key, you can choose between Live or Test environment. Test keys return mock results without making real DNS lookups — perfect for development and CI/CD.

Test keys don't count against your monthly quota, so you can test as much as you want.

Known Test Domains

Domain	Result	MX Records
test.com	Deliverable	Yes
gmail.com	Deliverable	Yes
yahoo.com	Deliverable	Yes
example.com	Undeliverable	No
invalid.com	Undeliverable	No
(any other domain)	Deliverable	Mocked

Note: Test key responses are deterministic and fast, but they don't reflect real email deliverability. Always use live keys for production validation.

API Reference

GET/v1/email

Validate a single email address

Query Parameters

Parameter	Type	Description
email	string	The email address to validate (URL encoded)
smtp	boolean	Enable SMTP validation (see SMTP section below)

Response

{
  "success": true,
  "requestId": "req_abc123",
  "email": "test@example.com",
  "valid": true,
  "status": "VALID",
  "confidence": 95,
  "checks": {
    "format": true,
    "domain": true,
    "mx": true,
    "disposable": false,
    "freeProvider": false
  },
  "suggestion": null
}

POST/v1/email-bulk

Validate multiple email addresses at once

Request Body

{
  "emails": ["test1@example.com", "test2@example.com"],
  "smtp": false
}

Response

{
  "success": true,
  "requestId": "req_abc123",
  "results": [
    {
      "email": "test1@example.com",
      "valid": true,
      "status": "VALID",
      "confidence": 95
    },
    {
      "email": "test2@example.com", 
      "valid": false,
      "status": "INVALID_MX",
      "confidence": 100
    }
  ],
  "summary": {
    "total": 2,
    "valid": 1,
    "invalid": 1
  }
}

Domain Lookup

GET/v1/domain

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	The domain name to look up (e.g., example.com)

Response

{
  "domain": "example.com",
  "dns": {
    "a": ["93.184.216.34"],
    "aaaa": ["2606:2800:220:1:248:1893:25c8:1946"],
    "mx": ["10 mail.example.com"],
    "ns": ["ns1.example.com", "ns2.example.com"],
    "txt": ["v=spf1 -all"],
    "caa": ["0 issue "pki.example.com""]
  },
  "whois": {
    "registrar": "MarkMonitor Inc.",
    "registrarUrl": "http://www.markmonitor.com",
    "creationDate": "1997-09-15",
    "expiryDate": "2028-09-14",
    "updatedDate": "2019-09-09",
    "nameservers": ["ns1.google.com", "ns2.google.com"],
    "status": ["clientTransferProhibited"],
    "redacted": false
  },
  "request_id": "req_abc123"
}

DNS Response Fields

Field	Type	Description
a	string[]	IPv4 addresses
aaaa	string[]	IPv6 addresses
mx	string[]	Mail servers (priority + host)
ns	string[]	Name servers
txt	string[]	TXT records (SPF, DKIM, etc.)
caa	string[]	Certification Authority Authorization

WHOIS Response Fields

Field	Type	Description
registrar	string	Domain registrar name
registrarUrl	string	Registrar website
creationDate	string	Registration date
expiryDate	string	Expiration date
updatedDate	string	Last update date
nameservers	string[]	Authoritative name servers
status	string[]	Domain status codes
redacted	boolean	True if data is hidden due to GDPR

Code Examples

Validate Email

curl -X GET "https://api.novacheck.io/v1/email?email=test@example.com" \
  -H "X-API-Key: nc_live_your_api_key_here"

Domain Lookup

curl -X GET "https://api.novacheck.io/v1/domain?domain=example.com" \
  -H "Authorization: Bearer nc_live_your_api_key_here"

Error Codes

Code	HTTP Status	Description
VALID	200	Email is valid
INVALID	200	Email format is invalid
CATCH_ALL	200	Email domain accepts all addresses (verify manually)
DISPOSABLE	200	Email uses a disposable domain
FREE_PROVIDER	200	Email uses a free email provider (Gmail, etc.)
TYPO	200	Email likely has a typo (suggestion provided)
INVALID_MX	200	Domain has no valid MX records
UNVERIFIABLE	200	Could not verify email (server blocks verification)
RATE_LIMITED	429	Rate limit exceeded
QUOTA_EXCEEDED	403	Monthly quota exceeded
INVALID_API_KEY	401	API key is invalid or revoked

SMTP Validation

By default, the API performs DNS/MX lookups to validate email domains. For higher accuracy, you can enable SMTP validationwhich connects to the mail server to verify the mailbox actually exists.

⚠️ Warning: SMTP validation significantly increases response time (typically 3-10 seconds per email) because it must connect to external mail servers. Use sparingly and only when higher accuracy is critical.

Usage

Single email with SMTP validation:

curl -X GET "https://api.novacheck.io/v1/email?email=test@example.com&smtp=true" \
  -H "X-API-Key: nc_live_your_api_key_here"

Bulk validation with SMTP:

curl -X POST "https://api.novacheck.io/v1/email-bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nc_live_your_api_key_here" \
  -d '{"emails": ["test1@example.com", "test2@example.com"], "smtp": true}'

How It Works

• SMTP validation only runs if DNS/MX checks pass first
• Connects to mail server on ports 587, 465, then 25 (in order)
• Sends RCPT TO command to check if mailbox exists
• 3 second timeout per server
• Returns smtp_valid in the response details

Response Field

{
  "email": "test@example.com",
  "valid": true,
  "details": {
    "syntax": true,
    "mx": true,
    "disposable": false,
    "role": false,
    "free": false,
    "smtp_valid": true  // SMTP validation result
  }
}

Rate Limits

API requests are rate-limited based on your plan:

Free

10/min

Starter

100/min

Pro

300/min

Business

1,000/min

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset