API Key Documentation

Overview

API Key allows premium users to access the email verification API without requiring login authentication. API Key endpoints use a separate prefix /api/v1/ and do not require encryption.

Requirements

Premium Plan Only: API Key feature is exclusively available for premium users
Each user can have only one API key
API key endpoints do not use encryption (plain text requests/responses)

Getting Started

1. Generate API Key

First, you need to generate an API key through the web interface:

Login to your account
Click on your profile menu
Select "API Key" (only visible for premium users)
Click "Generate API Key"
Important: Copy and save your API key immediately - you won't be able to see it again!

⚠️ Warning: You will not be able to see your API key again after generation. Please save it securely.

2. Using API Key

API Key can be provided in three ways:

X-API-Key Header (Recommended):
```
X-API-Key: your-api-key-here
```
Authorization Header:
```
Authorization: Bearer your-api-key-here
```
Query Parameter (Less secure):
```
?apiKey=your-api-key-here
```

API Endpoints

All API key endpoints use the /api/v1/ prefix and do not require encryption.

1. Check Emails

Submit a job to check email addresses.

Endpoint:

POST /api/v1/check-emails

Request:

{
  "input": "[email protected]\[email protected]\[email protected]"
}

Response:

{
  "success": true,
  "code": "JOB_SUBMITTED",
  "message": "Job submitted successfully",
  "data": {
    "jobId": "job-123-1234567890",
    "status": "pending",
    "emailsCount": 3
  }
}

2. Get Job History

Get paginated list of your jobs.

Endpoint:

GET /api/v1/jobs/history?page=1&limit=20

3. Get Job Stats

Get summary statistics for a specific job.

Endpoint:

GET /api/v1/jobs/:jobId/stats

4. Get Job Detail

Get full job details including all results.

Endpoint:

GET /api/v1/jobs/:jobId

5. Get Usage Statistics

Get your current usage statistics.

Endpoint:

GET /api/v1/usage

Code Examples

cURL Example

# Check Gmail addresses
curl -X POST https://api.gmcheck.live/api/v1/check-emails \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"input": "[email protected]\[email protected]"}'

# Get job stats
curl -X GET https://api.gmcheck.live/api/v1/jobs/job-123-1234567890/stats \
  -H "X-API-Key: your-api-key-here"

Python Example

import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://api.gmcheck.live/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Check emails
response = requests.post(
    f"{BASE_URL}/check-emails",
    headers=headers,
    json={"input": "[email protected]\[email protected]"}
)
job_data = response.json()
job_id = job_data["data"]["jobId"]

# Get job stats
stats_response = requests.get(
    f"{BASE_URL}/jobs/{job_id}/stats",
    headers=headers
)
stats = stats_response.json()
print(stats)

JavaScript Example

const API_KEY = "your-api-key-here";
const BASE_URL = "https://api.gmcheck.live/api/v1";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
};

// Check Gmail addresses
const checkEmails = async () => {
  const response = await fetch(`${BASE_URL}/check-emails`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify({
      input: "[email protected]\[email protected]"
    })
  });
  
  const data = await response.json();
  const jobId = data.data.jobId;
  
  // Poll for job completion
  const pollJob = async () => {
    const statsResponse = await fetch(`${BASE_URL}/jobs/${jobId}/stats`, {
      headers: headers
    });
    const stats = await statsResponse.json();
    
    if (stats.data.status === "completed") {
      // Get full results
      const detailResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, {
        headers: headers
      });
      const detail = await detailResponse.json();
      console.log(detail.data.result);
    } else {
      // Poll again after delay
      setTimeout(pollJob, 2000);
    }
  };
  
  pollJob();
};

Email Status Values

LIVE: Email is valid and active
VERIFY: Email requires verification
DISABLE: Email is disabled
NOT_EXIST: Email does not exist
UNKNOWN: Unknown status
PENDING: Email is still being processed

Job Status Values

pending: Job is queued and waiting to be processed
processing: Job is currently being processed
completed: Job has completed successfully
stopped: Job was stopped by user
failed: Job failed to complete

Security Best Practices

Never share your API key: Treat your API key like a password
Use environment variables: Store API keys in environment variables, not in code
Rotate regularly: Regenerate your API key periodically
Revoke if compromised: If you suspect your API key is compromised, revoke it immediately
Use HTTPS only: Always use HTTPS when making API requests
Monitor usage: Regularly check your usage statistics to detect unauthorized access

Error Responses

Invalid API Key:

{
  "success": false,
  "code": "INVALID_API_KEY",
  "message": "Invalid API key. Please check your API key and try again."
}

Premium Required:

{
  "success": false,
  "code": "PREMIUM_REQUIRED",
  "message": "API key feature is only available for premium users."
}

Monthly Limit Exceeded:

{
  "success": false,
  "code": "MONTHLY_LIMIT_EXCEEDED",
  "message": "Monthly limit exceeded. You have checked 100000 / 100000 emails this month."
}

Support

For issues or questions regarding API keys, please contact support through the contact page or Telegram.