API Docs

Introduction

Zeruh is an email verification service that lets you verify email addresses in real-time. Our API is designed to be simple and easy to use, allowing you to integrate email verification into your applications with minimal effort.

To obtain an API key, sign up for an account and then navigate to the API page to generate your API key.

Authentication

To authenticate your requests, you need to include your API key in the request. There are three ways to include your API key in your requests:

Include your API key in the X-Api-Key header of your request.
Include your API key as a query parameter named api_key.
Include your API key as a form parameter named api_key.

The quicker and easier way to authenticate your requests is by including your API key in the api_key query parameter.

Base Endpoint

Requests to the Zeruh API should be made to the following base URL and can be made using either the GET or POST method.

Base URL: https://api.zeruh.com
API Version: v1
Method: GET or POST

Endpoints

Get Account Details

Get details about your account, including your account balance and the number of email verifications you have remaining.

Endpoint: https://api.zeruh.com/v1/account
Method: GET or POST

Example Request

curl -X GET "https://api.zeruh.com/v1/account?api_key=YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "We have fetched your account information.",
  "data": {
    "user_id": 100,
    "full_name": "Arthur Morgan",
    "user_email": "[email protected]",
    "permanent_credits": 50000,
    "recurring_credits": 48540
  }
}

Verify Email Address

Verify an email address to determine if it is valid and deliverable. If you want to include the IP address of the user making the request, you can include it as a query parameter named ip_address. When provided, we will supplement additional information about the IP address in the response.

Endpoint: https://api.zeruh.com/v1/verify
Method: GET or POST
Parameters: email_address (required), ip_address (optional), timeout (optional)

Example Request

curl -X GET "https://api.zeruh.com/v1/verify?api_key=YOUR_API_KEY&[email protected]&ip_address=8.8.8.8"

Example Response (Without IP Address)

{
  "success": true,
  "message": "The results have been fetched. Please check the 'result' field for more information.",
  "result": {
    "email_address": "[email protected]",
    "gravatar_url": "https://www.gravatar.com/avatar/593429bcf7ccf2f630a5ed05bbe9e003392f910cc492c8222111df9a524a6e9b",
    "account": "hello",
    "domain_details": {
      "domain": "zeruh.com",
      "domain_age": 839,
      "did_you_mean": null
    },
    "validation_details": {
      "format_valid": true,
      "mx_found": true,
      "smtp_check": true,
      "catch_all": true,
      "role": true,
      "disposable": false,
      "free": false,
      "tagged": false,
      "mailbox_full": false,
      "mailbox_disabled": false,
      "no_reply": false
    },
    "selected_mx_record": "mx1.maileroo.com",
    "service_provider": "Maileroo",
    "character_stats": {
      "alphabetical_characters": 5,
      "numerical_characters": 0,
      "unicode_symbols": 0
    },
    "ip_details": null,
    "time_taken_to_verify": "0.00",
    "reason": "low_deliverability",
    "status": "risky",
    "score": 65
  }
}

Example Response (With IP Address)

{
  "success": true,
  "message": "The results have been fetched. Please check the 'result' field for more information.",
  "result": {
    "email_address": "[email protected]",
    "gravatar_url": "https://www.gravatar.com/avatar/593429bcf7ccf2f630a5ed05bbe9e003392f910cc492c8222111df9a524a6e9b",
    "account": "hello",
    "domain_details": {
      "domain": "zeruh.com",
      "domain_age": 839,
      "did_you_mean": null
    },
    "validation_details": {
      "format_valid": true,
      "mx_found": true,
      "smtp_check": true,
      "catch_all": true,
      "role": true,
      "disposable": false,
      "free": false,
      "tagged": false,
      "mailbox_full": false,
      "mailbox_disabled": false,
      "no_reply": false
    },
    "selected_mx_record": "mx1.maileroo.com",
    "service_provider": "Maileroo",
    "character_stats": {
      "alphabetical_characters": 5,
      "numerical_characters": 0,
      "unicode_symbols": 0
    },
    "ip_details": {
      "ip_address": "8.8.8.8",
      "asn": "AS15169",
      "city": "Mountain View",
      "region": "California",
      "country": "US",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "proxy_or_vpn": false
    },
    "time_taken_to_verify": "0.12",
    "reason": "low_deliverability",
    "status": "risky",
    "score": 65
  }
}

Note: The timeout parameter is used to specify the maximum time in seconds to wait for the email verification to complete. The default value is 20 seconds, and the minimum and maximum values are 5 and 120 seconds, respectively. While we make every effort to complete the verification within the specified time, the actual time may vary depending on the email server's response time.

Grading / Scoring

The Zeruh API provides a grading system to help you determine the quality of an email address. The grading system is based on the deliverability and quality of the email address. The following table lists the possible reasons for an email address and their corresponding status.

Reason	Status
deliverable	deliverable
low_deliverability	risky
low_quality	risky
invalid_email	undeliverable
invalid_domain	undeliverable
mailbox_not_found	undeliverable
mailbox_full_inbox	undeliverable
mailbox_disabled	undeliverable
exhausted_credits	unknown
internal_error	unknown
connection_failed	unknown
connection_timed_out	unknown
smtp_failure	unknown
greylisted	unknown

For failed verifications, the status will be unknown, and you are automatically refunded credits for these verifications.

Recommendations

To ensure the best performance and accuracy when using the Zeruh API, we recommend the following best practices:

When looking to identify email addresses that are likely to be associated with a real person and are deliverable, we recommend using the following combination of parameters:

status = "deliverable"
AND catch_all = false
AND disposable = false

For cold email campaigns, we recommend using the following combination of parameters:

status IN ("deliverable", "risky", "unknown")
AND (free = true OR role = true OR catch_all = true)
AND (disposable = false)

For identifying spammy or low-quality signups using our API, we highly recommend excluding disposable email addresses by using the following combination of parameters:

disposable = false

Furthermore, if you provide an IP address, you can use it to identify the location of the user making the request and check if they are using a VPN or proxy server. This information can be useful in determining the legitimacy of the request.

Rate Limiting

By default, the Zeruh API has a rate limit of 30 requests per second. This limit can be increased upon request.

Response Handling

The Zeruh API uses standard HTTP status codes to indicate the success or failure of a request. The following table lists the possible HTTP status codes and their meanings.

HTTP Code	Reason
200 OK	The request was successful. Verification may not necessarily be successful.
403 Forbidden	Invalid API key or IP address is not in the allowed list.
429 Too Many Requests	Rate limit exceeded. Please try again later.
500 Internal Server Error	An unexpected error occurred. Please try again later.

If you want to dig deeper into the response, you can check the success field in the response body. The success field will be true if the request was successful, and false if there was an error. For more information, check the message field in the response body.

If success is false, then you should always assume that the request failed, and the response may not contain the expected data.