Understanding the Spamova API Response
Every request to /api/v1/check and /api/v1/bulk returns the same set of attributes. Knowing what each field means and how to use it lets you build smarter logic around your signup flow rather than just blocking on a single boolean.
The Full Response Shape
A single check response looks like this:
A bulk response wraps results in an array and adds a meta object:
Response Attributes
The normalized version of the email address that was checked. Always present. Use this to match results back to your input when processing bulk responses, since the API may normalize the address (lowercasing the domain, for example).
syntax
Whether the address has valid syntax. Three possible values:
valid - the address is correctly formatted and can be checked further.
invalid - the address is malformed. Reject it immediately without checking any other field. There is no point evaluating disposable status on an address that cannot receive mail.
suspected_typo - the address is syntactically valid but the domain looks like a common misspelling of a well-known provider. For example, user@gmial.com instead of user@gmail.com. You may want to prompt the user to confirm or correct their address rather than silently rejecting it.
is_disposable
Your primary signal. Three possible values:
true - the domain is confirmed disposable. Block the signup.
false - the domain is not known to be disposable.
null - the domain was encountered for the first time and has not yet been evaluated. Do not treat null as false. A null result means the verdict is pending, not that the domain is clean. See the section on newly discovered domains below.
risk_score
Growth plans and above only. Starter plans receive null.
An integer from 0 to 100 representing the estimated disposable or abuse risk of the domain. Higher values indicate higher risk. A score of 0 means the domain shows no risk signals. A score of 100 means the domain is confirmed disposable with high confidence.
The risk score is most useful for handling the grey area between clearly clean and clearly disposable. A domain that scores 75 may not be on any confirmed blocklist but shows enough suspicious signals to warrant caution. You define the threshold that fits your product's tolerance for false positives versus missed detections.
A common starting point:
Newly discovered domains return null until evaluated.
mx
Growth plans and above only. Starter plans receive null.
Whether the domain has usable mail exchange records. Four possible values:
valid - the domain has MX records pointing to functioning mail servers. Email sent to this address has a real destination.
invalid - the domain has no MX records or its mail servers are unreachable. Even if the address passes syntax checks, no mail can be delivered to it.
unknown - the MX lookup could not be completed, typically due to a DNS timeout. Treat this the same way you treat null - do not assume valid or invalid.
null - newly discovered domain, not yet evaluated.
An invalid MX result is a strong signal to reject the address even when is_disposable is false. A domain with no mail infrastructure cannot receive email, which means either the user made a mistake or is submitting a fabricated address.
website_status
Growth plans and above only. Starter plans receive null.
What the domain returns when checked as a website. Five possible values:
active - the domain resolves to a live website. A normal signal for legitimate email providers and company domains.
redirect - the domain redirects to another domain. Common among disposable email services that use multiple domains pointing to the same infrastructure.
restricted - the domain resolves but returns an access-denied or login-required response. Neutral signal on its own.
not_found - the domain resolves but returns a 404 or equivalent. A domain with no website and no MX records is a strong combined signal for a throwaway or fabricated address.
unknown - the website check could not be completed. Treat as neutral.
null - newly discovered domain, not yet evaluated.
Newly Discovered Domains
When the API encounters a domain for the first time, it queues it for evaluation. Until that evaluation completes, domain-derived fields return null rather than a potentially incorrect value.
This means a response can look like this for an unseen domain:
Never treat a null is_disposable as a clean result. The domain is unknown, not confirmed safe. How you handle this depends on your product's risk tolerance:
Fail open - allow the signup and accept that some unknown domains may turn out to be disposable. Lower friction, higher risk.
Fail closed - reject or flag signups from domains with null is_disposable until a verdict is available. Higher friction, lower risk.
A middle-ground approach is to allow the signup but flag the account for closer monitoring until the domain has been evaluated.
Starter vs Growth Plans
Starter plan responses return null for risk_score, mx, and website_status. Only syntax and is_disposable are populated.
If you are on a Starter plan and see null for these fields, this is expected behavior, not an error. Upgrade to a Growth plan or above to receive the full response.
The meta Object (Bulk Only)
Bulk responses include a meta object alongside the results array.
checks_used - the number of checks consumed by this request. Equal to the number of emails in the request.
checks_remaining - the number of checks remaining on your plan immediately after this request was processed. Use this to monitor your quota and avoid hitting the limit unexpectedly.