API reference

Validate email

Verify that an email address exists and accepts mail.

POST/v1/validate

Parameters

ParameterTypeDescription
emailreq
stringThe email address to validate.

Request

curl -X POST https://api.gtmcli.com/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response

200 OKjson
{
  "email": "user@example.com",
  "status": "valid",
  "provider": "google"
}

Response fields

ParameterTypeDescription
email
stringThe email address that was validated.
status
stringValidation result: valid, invalid, catchall, valid_catchall, disposable, risky, unknown.
provider
stringEmail provider if detected (google, microsoft, icloud, other).

Status values

validMailbox exists and accepts mail.0.25 credits
invalidMailbox does not exist or is rejected.Free
catchallDomain accepts all addresses. Cannot confirm this specific one.Free
valid_catchallCatchall domain, but high confidence this person exists.0.25 credits
disposableTemporary or throwaway email service.Free
riskyExists but may have deliverability issues (role-based, etc).Free
unknownCould not determine status. Server timeout or temporary error.Free

TIP

You only pay for valid and valid_catchall results. Everything else is free.

Errors

401Missing or invalid API key.
402Insufficient credits.
429Rate limit exceeded. Check Retry-After header.