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
Send it with the Authorization header as a Bearer token
Make your first validation request:

curl -X POST "https://api.novacheck.io/v1/email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nc_live_your_api_key_here" \
  -d '{"emails": ["[email protected]"]}'

Authentication

All authenticated API endpoints use Bearer token authentication.

Authorization: Bearer nc_live_your_api_key_here

Test keys use the same format and begin with nc_test_.

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

POST/v1/email

Validate one or more email addresses

Request Body

{
  "emails": ["[email protected]", "[email protected]"],
  "smtp": true,
  "cache": true
}

Send 1 to 100 email addresses. Usage is counted per uncached email address. Set optional smtp to true to run best-effort SMTP checks. Set optional cache to false to bypass cache reads and writes.

Catch-all detection only runs when smtp is true, real MX records are found, and the requested recipient is accepted by SMTP. NovaCheck then probes a random address at the same domain; if that random address is also accepted, details.catch_all is true. If there are no MX records, only an A-record fallback, a rejected recipient, or an inconclusive SMTP probe, catch-all remains null.

Response

{
  "results": [
    {
      "email": "[email protected]",
      "valid": true,
      "reason": "deliverable",
      "sub_reason": null,
      "syntax_valid": true,
      "score": 95
    },
    {
      "email": "[email protected]",
      "valid": false,
      "reason": "undeliverable",
      "sub_reason": "no_mx",
      "syntax_valid": true,
      "score": 35
    }
  ],
  "summary": {
    "total": 2,
    "deliverable": 1,
    "undeliverable": 1,
    "risky": 0,
    "unknown": 0
  },
  "request_id": "req_abc123"
}

Domain Lookup

GET/v1/domain

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	The domain name to look up (e.g., example.com)
cache	boolean	No	Set to false to bypass cache reads and writes. Cached domain lookups do not count against usage.

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 POST "https://api.novacheck.io/v1/email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nc_live_your_api_key_here" \
  -d '{"emails": ["[email protected]"]}'

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 appears deliverable based on available signals
INVALID	200	Email format is invalid
CATCH_ALL	200	Email domain may accept all addresses (confirm with your own flow)
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 determine deliverability from available signals
RATE_LIMITED	429	Rate limit exceeded
QUOTA_EXCEEDED	403	Monthly quota exceeded
INVALID_API_KEY	401	API key is invalid or revoked

Validation Accuracy

NovaCheck validates addresses using syntax checks, domain signals, DNS/MX lookups, SMTP recipient probing, catch-all detection, disposable-domain detection, role-account detection, and typo suggestions. A valid result means the address appears deliverable based on those signals.

Important: Email validation is a best-effort signal, not concrete proof that a mailbox exists. Mail providers can accept mail and later bounce it, reject legitimate messages, use catch-all routing, or change behavior after validation. Use NovaCheck results as one input in your own validation and delivery flow.

How It Works

• Checks whether the email format is syntactically valid
• Looks up DNS/MX records to confirm the domain can receive mail
• Probes SMTP recipients when requested and real MX records are available
• Tests for catch-all domains only after the requested recipient is accepted by SMTP
• Flags disposable and role-based addresses
• Identifies common free providers and suggests fixes for known domain typos
• Returns unknown when DNS signals are inconclusive or time out

Response Details

{
  "email": "[email protected]",
  "valid": true,
  "reason": "deliverable",
  "details": {
    "syntax": true,
    "mx": true,
    "smtp": true,
    "catch_all": false,
    "disposable": false,
    "role": false,
    "free": false,
    "suggestion": null
  }
}

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