REST API

API Documentation

The NeuraMail API lets you verify email addresses and query your account programmatically. All endpoints return JSON. Authentication is via a per-user API key.

Base URL:

https://neuramail.cl

Authentication

Include your API key in every request using the Authorization. Generate or rotate your key from the API Keys page in the dashboard.

Request header

Authorization: Bearer nm_live_xxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Never expose it in client-side code or public repos. Rotate it immediately if you suspect it's been compromised.

GET/api/v1/verify

Verify a single email address. Returns status, sub-status, MX info, and whether the result was cached.

Parameters

email

stringrequiredThe email address to verify.

Response

200 OK · application/json

{
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "sub_status": null,
    "is_catchall": false,
    "mx_found": true,
    "credits_used": 1,
    "cached": false
  }
}

POST/api/v1/verify/batch

Verify up to 1,000 email addresses in a single request.

Parameters

emails

string[]requiredArray of email addresses (max 1,000).

Response

200 OK · application/json

{
  "data": {
    "results": [
      { "email": "a@example.com", "status": "valid",   "cached": true  },
      { "email": "b@fake.io",     "status": "invalid", "sub_status": "disposable" }
    ],
    "total": 2,
    "credits_used": 1,
    "credits_cached": 1
  }
}

GET/api/v1/credits

Return the current credit balance and recent transaction history for the authenticated user.

Response

200 OK · application/json

{
  "data": {
    "balance": 4820,
    "transactions": [
      { "amount": -1, "type": "verification", "created_at": "2025-03-14T10:00:00Z" }
    ]
  }
}

Response statuses

validMailbox exists and is likely to receive mail.

invalidMailbox does not exist or the domain is non-functional.

riskyRole address, recently deactivated, or low-confidence result.

catch_allServer accepts all mail; individual mailbox cannot be confirmed.

unknownServer timed out or blocked the verification handshake.

Sub-statuses

disposablerole_basedspam_trapmx_not_foundsmtp_errorbouncesyntax_error

Error codes

400Bad RequestMissing or invalid parameters.

401UnauthorizedAPI key missing or invalid.

402Insufficient CreditsYour account balance is too low.

422Unprocessable EntityEmail address failed syntax validation.

429Too Many RequestsRate limit exceeded. Retry after the Retry-After header value.

500Server ErrorUnexpected error. Contact support if it persists.

Ready to integrate?

Create a free account and get your API key in 60 seconds.