Gmail RADAR — API Documentation

🚀 Quick Start

Register an account at Gmail RADAR
Login and go to your profile to create an API key
Send a POST request to /api/v1/check with your key

Your First Request

curl -X POST "https://your-server.com/api/v1/check" \
          -H "Content-Type: application/json" \
          -H "X-API-Key: gmr_your_api_key_here" \
          -d '{"emails": ["user@gmail.com", "test@gmail.com"]}'

import requests

          response = requests.post(
          "https://your-server.com/api/v1/check",
          headers={"X-API-Key": "gmr_your_api_key_here"},
          json={"emails": ["user@gmail.com", "test@gmail.com"]}
          )

          data = response.json()
          for result in data["results"]:
          print(f"{result['email']}: {result['status']}")
        

const res = await fetch("https://your-server.com/api/v1/check", {
          method: "POST",
          headers: {
          "Content-Type": "application/json",
          "X-API-Key": "gmr_your_api_key_here"
          },
          body: JSON.stringify({
          emails: ["user@gmail.com", "test@gmail.com"]
          })
          });

          const data = await res.json();
          data.results.forEach(r => console.log(`${r.email}: ${r.status}`));
        

🔐 Authentication

All API requests require an API key passed via the X-API-Key header:

X-API-Key: gmr_your_api_key_here

⚠️ Keep your API key secret. Do not share it publicly or commit it to version control. If compromised, revoke it and create a new one.

📡 Endpoints

POST /api/v1/check Check email statuses

Check the status of Gmail accounts. Returns results synchronously.

Request Body

{
            "emails": [
            "user1@gmail.com",
            "user2@gmail.com:password123",
            "user3@gmail.com"
            ]
            }
          

💡 You can include passwords with the email:password format. The password is preserved in the original_line field of the response.

Response (200)

{
            "success": true,
            "total": 3,
            "results": [
            { "email": "user1@gmail.com", "status": "good", "original_line":
            "user1@gmail.com" },
            { "email": "user2@gmail.com", "status": "disabled", "original_line": "user2@gmail.com:password123" },
            { "email": "user3@gmail.com", "status": "unknown", "original_line": "user3@gmail.com" }
            ],
            "counts": { "good": 1, "disabled": 1, "unknown": 1 }
            }
          

Limits

Maximum 50,000 emails per request
Requires API subscription
No daily limits — check unlimited emails per day

GET /api/v1/usage Get usage statistics

Returns current usage statistics for your API key.

Response (200)

{
            "key_name": "Production",
            "rate_limit": 10,
            "daily_limit": 1000,
            "today_used": 53,
            "remaining": 947,
            "total_used": 12450,
            "last_used_at": "2026-02-09T08:30:00.000Z"
            }
          

GET /api/v1/keys List your API keys (JWT auth)

Lists all API keys for your account. Requires JWT token in Authorization: Bearer TOKEN header.

🔑 This endpoint uses JWT authentication (from login), not API key auth.

POST /api/v1/keys Create new API key (JWT auth)

Request Body

{ "name": "My App" }

Response (200)

{
            "success": true,
            "api_key": "gmr_a1b2c3d4e5f6...",
            "message": "Save this key — it will only be shown once"
            }
          

⚠️ The API key is only shown once on creation. Store it securely.

DELETE /api/v1/keys/:id Revoke an API key (JWT auth)

Permanently deletes an API key. All requests using this key will fail immediately.

📊 Status Values

Status	Description
`good`	Account exists and is active
`disabled`	Account is disabled or suspended
`unknown`	Could not determine status (timeout, error, etc.)

⚠️ Error Codes

Code	Error	Description
400	Invalid input	Missing or malformed request body
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key has been disabled
429	Rate limited	Too many requests or daily limit exceeded
500	Server error	Internal error during email check

💳 Access Requirements

Requirement	Details
Subscription	API plan — free and pro plan users cannot use the API
Emails/request	50,000 max per single API call
Daily limit	Unlimited — no daily cap for paid users
Keys/account	1 API key per user account

💡 Purchase an API subscription to unlock API access. Other plan users will receive a 403 Subscription required error.