---
title: "Email Verification API Reference"
description: "Verify an email address in real time — confirm the domain has live mail infrastructure, detect disposable addresses, and retrieve domain age as a trust signal."
canonical: "https://eps.eko.in/docs/check-email"
---


> **Canonical URL:** https://eps.eko.in/docs/check-email
> This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above.

# Email Verification API Reference

`POST https://staging.eko.in/ekoapi/v3/tools/kyc/check-email`

Verify an email address in real time — confirm the domain has live mail infrastructure, detect disposable addresses, and retrieve domain age as a trust signal.

**Behaviour**

- **Read-only**: Changes nothing; only returns data.
- **[₹8.40 + GST / check](https://eps.eko.in/pricing?apis=email-check#calculator)**: Charged per successful call; failed calls are free.

> [!WARNING]
> The UAT / Sandbox environment is not available for this API — requests to `https://staging.eko.in/ekoapi/v3` return an error response. Test it in Production.

Validates whether an email address is genuine and deliverable by checking MX (mail exchange) records for the domain. Returns domain age in days, the resolved MX record list, and flags for validity and disposability — giving you the signals needed to block fake signups, catch typos, and assess account trust during onboarding.

> View product & pricing details: [Email Verification](https://eps.eko.in/products/email-verification-api.md)

## Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| initiator_id | string | yes | Registered mobile number of the API user (see Platform Credentials). e.g. 9962981729 |
| client_ref_id | string | no | Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't. e.g. 2026010100123456789 |
| email | string | yes | The email address to verify, e.g. rajesh.kumar@example.com. e.g. rajesh.kumar@example.com |

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| developer_key | string | yes | Static API key issued to your account after KYC. |
| secret-key | string | yes | Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))). |
| secret-key-timestamp | string | yes | Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time. |
| content-type | string | yes | application/json e.g. application/json |

## Response

⭐ marks fields highlighted as verifiable.

| Field | Type | Description |
| --- | --- | --- |
| status | number | Primary success indicator (0 = success). |
| message | string | Human-readable response / error message. |
| response_status_id | number | UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented. |
| response_type_id | number | A unique id for every possible response shape (success or error) — useful for client logic branching and analytics. |
| data | object | API-specific response payload. |
| data.email | string | The email address that was checked, echoed back for confirmation. |
| data.domain ⭐ | string | Domain portion of the email address (part after @). Used to anchor all domain-level checks. |
| data.is_valid ⭐ | boolean | Whether the email address is valid and deliverable. true = domain has live MX records and can receive mail; false = domain has no mail server or is otherwise undeliverable. |
| data.is_disposable ⭐ | boolean | Whether the email domain belongs to a known disposable / temporary email provider. true = disposable (high fraud risk); false = regular email domain. |
| data.domain_age_days ⭐ | number | Age of the email domain in days since registration. Newly created domains (< 30 days) are a strong fraud signal; legitimate email providers have domains that are years old. |
| data.mx_records ⭐ | array | List of MX (mail exchange) hostnames discovered for the domain, ordered by priority. An empty array means the domain cannot receive email. |

## Example request

```json
{
  "initiator_id": "9962981729",
  "client_ref_id": "2026010100123456789",
  "email": "rajesh.kumar@example.com"
}
```

## Example response

```json
{
  "status": 0,
  "response_status_id": 0,
  "message": "Email verification successful",
  "response_type_id": 1388,
  "data": {
    "email": "rajesh.kumar@example.com",
    "domain": "example.com",
    "is_valid": true,
    "is_disposable": false,
    "domain_age_days": 6970,
    "mx_records": [
      "aspmx.l.google.com",
      "alt1.aspmx.l.google.com",
      "alt2.aspmx.l.google.com",
      "alt3.aspmx.l.google.com",
      "alt4.aspmx.l.google.com"
    ]
  }
}
```

## Error scenarios

| Status | response_type_id | Scenario |
| --- | --- | --- |
| 200 | `1388` | Invalid email — domain has no MX records or does not exist |
| 200 | `1388` | Disposable / temporary email address detected |
| 200 | `1388` | User (retailer) not found |