API Reference

Complete API documentation for developers integrating GoEmailVerify into their applications.

Base URL

Production

https://goemailverify.com

Development

https://goemailverify.com

Authentication

All API requests require authentication using Bearer token in the Authorization header.

Method 1: API Key (Recommended for Integrations)

Use your API key for server-side integrations:

curl -X POST https://goemailverify.com/api/validate-emails \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["test@example.com"]}'

Method 2: JWT Token (Web Applications)

Use JWT tokens obtained from the login endpoint:

curl -X POST https://goemailverify.com/api/validate-emails \
  -H "Authorization: Bearer eyJhbGciOiJIUzM4NCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"emails": ["test@example.com"]}'
Security: Never expose API keys in client-side code or commit them to version control. Use environment variables or secure vaults.

Email Validation Endpoints

POST /api/validate-emails

Validate email addresses in real-time with comprehensive checks. Accepts single or multiple emails.

Request

{
  "emails": ["test@example.com"]
}

Response (200 OK)

{
  "email": "test@example.com",
  "valid": true,
  "status": "DELIVERABLE",
  "qualityScore": 95,
  "riskLevel": "LOW",
  "validationDetails": {
    "syntax": true,
    "domain": "example.com",
    "mxRecords": true,
    "smtpVerified": true,
    "disposable": false,
    "roleBased": false,
    "catchAll": false,
    "domainAge": 7850,
    "domainTrustScore": 95,
    "emailAgeCategory": "LEGACY",
    "nameIsHumanLike": true,
    "nameConfidence": 0.92
  },
  "suggestions": [],
  "processingTimeMs": 127
}

Error Response (400 Bad Request)

{
  "error": "Invalid email format",
  "message": "Email must contain @ symbol"
}

Code Examples

curl -X POST https://goemailverify.com/api/validate-emails \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["test@example.com"]}'
import requests

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://goemailverify.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/api/validate-emails",
    headers=headers,
    json={"emails": ["test@example.com"]}
)

result = response.json()
print(f"Status: {result[0]['status']}")
print(f"Score: {result[0]['qualityScore']}")
const fetch = require('node-fetch');

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://goemailverify.com';

async function validateEmail(email) {
    const response = await fetch(`${BASE_URL}/api/validate-emails`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ emails: [email] })
    });

    const result = await response.json();
    console.log(`Status: ${result[0].status}`);
    console.log(`Score: ${result[0].qualityScore}`);
}

validateEmail('test@example.com');
import java.net.http.*;
import java.net.URI;

public class EmailValidator {
    private static final String API_KEY = "sk_live_your_api_key_here";
    private static final String BASE_URL = "https://goemailverify.com";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        String requestBody = "{\"emails\":[\"test@example.com\"]}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/validate-emails"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Response: " + response.body());
    }
}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const (
    API_KEY  = "sk_live_your_api_key_here"
    BASE_URL = "https://goemailverify.com"
)

type ValidateRequest struct {
    Emails []string `json:"emails"`
}

func main() {
    reqBody := ValidateRequest{
        Emails: []string{"test@example.com"},
    }

    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", BASE_URL+"/api/validate-emails", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

POST /api/validate-emails/bulk

Validate multiple emails in bulk asynchronously. Returns immediately with job ID for large batches.

Request

{
  "emails": [
    "john@example.com",
    "jane@company.com",
    "invalid@fakedomain.com"
  ]
}

Response (200 OK)

[
  {
    "email": "john@example.com",
    "valid": true,
    "status": "DELIVERABLE",
    "qualityScore": 92,
    "riskLevel": "LOW",
    "processingTimeMs": 98
  },
  {
    "email": "jane@company.com",
    "valid": true,
    "status": "DELIVERABLE",
    "qualityScore": 88,
    "riskLevel": "LOW",
    "processingTimeMs": 112
  },
  {
    "email": "invalid@fakedomain.com",
    "valid": false,
    "status": "UNDELIVERABLE",
    "qualityScore": 10,
    "riskLevel": "VERY_HIGH",
    "validationDetails": {
      "error": "No MX records found"
    },
    "processingTimeMs": 45
  }
]

Code Examples

curl -X POST https://goemailverify.com/api/validate-emails/bulk \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "john@example.com",
      "jane@company.com"
    ]
  }'
import requests

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://goemailverify.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

emails = [
    "john@example.com",
    "jane@company.com"
]

response = requests.post(
    f"{BASE_URL}/api/validate-emails/bulk",
    headers=headers,
    json={"emails": emails}
)

results = response.json()
for result in results:
    print(f"{result['email']}: {result['status']}")
const fetch = require('node-fetch');

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://goemailverify.com';

const emails = [
    'john@example.com',
    'jane@company.com'
];

async function validateBulk(emails) {
    const response = await fetch(`${BASE_URL}/api/validate-emails/bulk`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ emails })
    });

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

validateBulk(emails);
import java.net.http.*;
import java.net.URI;

public class BatchValidator {
    private static final String API_KEY = "sk_live_your_api_key_here";
    private static final String BASE_URL = "https://goemailverify.com";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String requestBody = """
            {
              "emails": [
                "john@example.com",
                "jane@company.com"
              ]
            }
        """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/validate-emails/bulk"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Response: " + response.body());
    }
}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const (
    API_KEY  = "sk_live_your_api_key_here"
    BASE_URL = "https://goemailverify.com"
)

type BulkRequest struct {
    Emails []string `json:"emails"`
}

func main() {
    reqBody := BulkRequest{
        Emails: []string{
            "john@example.com",
            "jane@company.com",
        },
    }

    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", BASE_URL+"/api/validate-emails/bulk", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Bulk Processing Endpoints

POST /api/validate-emails/upload

Upload a CSV file for bulk validation. CSV must contain an 'email' column.

Request (multipart/form-data)

file: emails.csv (binary)

Response (201 Created)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "totalEmails": 10000,
  "inputFilename": "emails.csv",
  "createdAt": "2025-10-20T10:30:00",
  "message": "Job created successfully"
}

Error Response (400 Bad Request)

{
  "error": "Invalid CSV format",
  "message": "CSV must contain 'email' column"
}

Code Examples

curl -X POST https://goemailverify.com/api/validate-emails/upload \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F "file=@emails.csv"
import requests

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://goemailverify.com"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

with open('emails.csv', 'rb') as f:
    files = {'file': f}
    response = requests.post(
        f"{BASE_URL}/api/validate-emails/upload",
        headers=headers,
        files=files
    )

job = response.json()
print(f"Job ID: {job['jobId']}")
print(f"Total Emails: {job['totalEmails']}")
const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://goemailverify.com';

async function uploadCSV(filePath) {
    const form = new FormData();
    form.append('file', fs.createReadStream(filePath));

    const response = await fetch(`${BASE_URL}/api/validate-emails/upload`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            ...form.getHeaders()
        },
        body: form
    });

    const job = await response.json();
    console.log(`Job ID: ${job.jobId}`);
    console.log(`Total Emails: ${job.totalEmails}`);
}

uploadCSV('emails.csv');
import java.net.http.*;
import java.net.URI;
import java.nio.file.*;

public class BulkUploader {
    private static final String API_KEY = "sk_live_your_api_key_here";
    private static final String BASE_URL = "https://goemailverify.com";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        Path filePath = Paths.get("emails.csv");

        String boundary = "----Boundary" + System.currentTimeMillis();
        byte[] fileBytes = Files.readAllBytes(filePath);

        String multipartBody = "--" + boundary + "\r\n" +
            "Content-Disposition: form-data; name=\"file\"; filename=\"emails.csv\"\r\n" +
            "Content-Type: text/csv\r\n\r\n" +
            new String(fileBytes) + "\r\n" +
            "--" + boundary + "--\r\n";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/validate-emails/upload"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .POST(HttpRequest.BodyPublishers.ofString(multipartBody))
            .build();

        HttpResponse response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        System.out.println("Response: " + response.body());
    }
}
package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const (
    API_KEY  = "sk_live_your_api_key_here"
    BASE_URL = "https://goemailverify.com"
)

func main() {
    file, _ := os.Open("emails.csv")
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("file", "emails.csv")
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", BASE_URL+"/api/validate-emails/upload", body)
    req.Header.Set("Authorization", "Bearer "+API_KEY)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    fmt.Println("Status:", resp.Status)
}

GET /api/jobs/{jobId}/status

Get the status and progress of a validation job.

Response - Pending (200 OK)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "totalEmails": 10000,
  "processedEmails": 0,
  "validEmails": 0,
  "invalidEmails": 0,
  "inputFilename": "emails.csv",
  "createdAt": "2025-10-20T10:30:00"
}

Response - In Progress (200 OK)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROGRESS",
  "totalEmails": 10000,
  "processedEmails": 6500,
  "validEmails": 5523,
  "invalidEmails": 977,
  "progressPercentage": 65.0,
  "inputFilename": "emails.csv",
  "createdAt": "2025-10-20T10:30:00",
  "startedAt": "2025-10-20T10:30:15",
  "estimatedCompletionTime": "2025-10-20T10:35:00"
}

Response - Completed (200 OK)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "totalEmails": 10000,
  "processedEmails": 10000,
  "validEmails": 8523,
  "invalidEmails": 1477,
  "progressPercentage": 100.0,
  "inputFilename": "emails.csv",
  "outputFilename": "results_550e8400.csv",
  "createdAt": "2025-10-20T10:30:00",
  "startedAt": "2025-10-20T10:30:15",
  "completedAt": "2025-10-20T10:35:42",
  "processingTimeSec": 327
}

Code Examples

# Check job status
curl -X GET https://goemailverify.com/api/jobs/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer sk_live_your_api_key_here"
import requests
import time

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://goemailverify.com"
JOB_ID = "550e8400-e29b-41d4-a716-446655440000"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Poll job status until complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/jobs/{JOB_ID}/status",
        headers=headers
    )

    job = response.json()
    status = job['status']

    print(f"Status: {status}")

    if status == 'COMPLETED':
        print(f"Valid: {job['validEmails']}")
        print(f"Invalid: {job['invalidEmails']}")
        break
    elif status == 'FAILED':
        print("Job failed!")
        break
    elif status == 'IN_PROGRESS':
        progress = job.get('progressPercentage', 0)
        print(f"Progress: {progress}%")

    time.sleep(5)  # Wait 5 seconds before checking again
const fetch = require('node-fetch');

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://goemailverify.com';
const JOB_ID = '550e8400-e29b-41d4-a716-446655440000';

async function checkJobStatus(jobId) {
    while (true) {
        const response = await fetch(`${BASE_URL}/api/jobs/${jobId}/status`, {
            headers: {
                'Authorization': `Bearer ${API_KEY}`
            }
        });

        const job = await response.json();
        const status = job.status;

        console.log(`Status: ${status}`);

        if (status === 'COMPLETED') {
            console.log(`Valid: ${job.validEmails}`);
            console.log(`Invalid: ${job.invalidEmails}`);
            break;
        } else if (status === 'FAILED') {
            console.log('Job failed!');
            break;
        } else if (status === 'IN_PROGRESS') {
            const progress = job.progressPercentage || 0;
            console.log(`Progress: ${progress}%`);
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

checkJobStatus(JOB_ID);
import java.net.http.*;
import java.net.URI;
import com.google.gson.*;

public class JobStatusChecker {
    private static final String API_KEY = "sk_live_your_api_key_here";
    private static final String BASE_URL = "https://goemailverify.com";
    private static final String JOB_ID = "550e8400-e29b-41d4-a716-446655440000";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        Gson gson = new Gson();

        while (true) {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/api/jobs/" + JOB_ID + "/status"))
                .header("Authorization", "Bearer " + API_KEY)
                .GET()
                .build();

            HttpResponse response = client.send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );

            JsonObject job = gson.fromJson(response.body(), JsonObject.class);
            String status = job.get("status").getAsString();

            System.out.println("Status: " + status);

            if ("COMPLETED".equals(status)) {
                System.out.println("Valid: " + job.get("validEmails").getAsInt());
                System.out.println("Invalid: " + job.get("invalidEmails").getAsInt());
                break;
            } else if ("FAILED".equals(status)) {
                System.out.println("Job failed!");
                break;
            } else if ("IN_PROGRESS".equals(status)) {
                double progress = job.get("progressPercentage").getAsDouble();
                System.out.println("Progress: " + progress + "%");
            }

            Thread.sleep(5000);
        }
    }
}
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

const (
    API_KEY  = "sk_live_your_api_key_here"
    BASE_URL = "https://goemailverify.com"
    JOB_ID   = "550e8400-e29b-41d4-a716-446655440000"
)

type JobStatus struct {
    Status              string  `json:"status"`
    ValidEmails         int     `json:"validEmails"`
    InvalidEmails       int     `json:"invalidEmails"`
    ProgressPercentage  float64 `json:"progressPercentage"`
}

func main() {
    for {
        url := fmt.Sprintf("%s/api/jobs/%s/status", BASE_URL, JOB_ID)
        req, _ := http.NewRequest("GET", url, nil)
        req.Header.Set("Authorization", "Bearer "+API_KEY)

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        body, _ := ioutil.ReadAll(resp.Body)

        var job JobStatus
        json.Unmarshal(body, &job)

        fmt.Printf("Status: %s\n", job.Status)

        if job.Status == "COMPLETED" {
            fmt.Printf("Valid: %d\n", job.ValidEmails)
            fmt.Printf("Invalid: %d\n", job.InvalidEmails)
            break
        } else if job.Status == "FAILED" {
            fmt.Println("Job failed!")
            break
        } else if job.Status == "IN_PROGRESS" {
            fmt.Printf("Progress: %.1f%%\n", job.ProgressPercentage)
        }

        time.Sleep(5 * time.Second)
    }
}

GET /api/jobs/{jobId}/download

Download validation results as CSV once the job is completed.

Response (200 OK)

Content-Type: text/csv

CSV file with validation results including all input columns plus validation data.

CSV Output Format

email,valid,status,quality_score,risk_level,validation_message,suggestions,processing_time_ms
john@gmail.com,true,DELIVERABLE,95,LOW,All checks passed,,127
invalid@fake.com,false,UNDELIVERABLE,10,VERY_HIGH,No MX records found,,89
user@gmial.com,false,TYPO_DETECTED,45,MEDIUM,Possible typo,user@gmail.com,45

Code Examples

# First check if job is complete
STATUS=$(curl -s -X GET https://goemailverify.com/api/jobs/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer sk_live_your_api_key_here" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)

if [ "$STATUS" = "COMPLETED" ]; then
  # Download results
  curl -X GET https://goemailverify.com/api/jobs/550e8400-e29b-41d4-a716-446655440000/download \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -o results.csv
  echo "Results downloaded!"
else
  echo "Job not complete yet. Status: $STATUS"
fi
import requests
import time

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://goemailverify.com"
JOB_ID = "550e8400-e29b-41d4-a716-446655440000"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# First, check status until complete
while True:
    status_response = requests.get(
        f"{BASE_URL}/api/jobs/{JOB_ID}/status",
        headers=headers
    )

    job = status_response.json()
    status = job['status']

    if status == 'COMPLETED':
        print("Job completed! Downloading results...")
        break
    elif status == 'FAILED':
        print("Job failed!")
        exit(1)
    else:
        print(f"Status: {status}, waiting...")
        time.sleep(5)

# Download results
download_response = requests.get(
    f"{BASE_URL}/api/jobs/{JOB_ID}/download",
    headers=headers
)

with open('results.csv', 'wb') as f:
    f.write(download_response.content)

print("Results downloaded successfully!")
const fs = require('fs');
const fetch = require('node-fetch');

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://goemailverify.com';
const JOB_ID = '550e8400-e29b-41d4-a716-446655440000';

async function downloadWhenReady(jobId) {
    // First, check status until complete
    while (true) {
        const statusResponse = await fetch(`${BASE_URL}/api/jobs/${jobId}/status`, {
            headers: { 'Authorization': `Bearer ${API_KEY}` }
        });

        const job = await statusResponse.json();
        const status = job.status;

        if (status === 'COMPLETED') {
            console.log('Job completed! Downloading results...');
            break;
        } else if (status === 'FAILED') {
            console.log('Job failed!');
            return;
        } else {
            console.log(`Status: ${status}, waiting...`);
            await new Promise(resolve => setTimeout(resolve, 5000));
        }
    }

    // Download results
    const downloadResponse = await fetch(`${BASE_URL}/api/jobs/${jobId}/download`, {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    const buffer = await downloadResponse.buffer();
    fs.writeFileSync('results.csv', buffer);
    console.log('Results downloaded successfully!');
}

downloadWhenReady(JOB_ID);
import java.net.http.*;
import java.net.URI;
import java.nio.file.*;
import com.google.gson.*;

public class ResultsDownloader {
    private static final String API_KEY = "sk_live_your_api_key_here";
    private static final String BASE_URL = "https://goemailverify.com";
    private static final String JOB_ID = "550e8400-e29b-41d4-a716-446655440000";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        Gson gson = new Gson();

        // First, check status until complete
        while (true) {
            HttpRequest statusRequest = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/api/jobs/" + JOB_ID + "/status"))
                .header("Authorization", "Bearer " + API_KEY)
                .GET()
                .build();

            HttpResponse statusResponse = client.send(
                statusRequest,
                HttpResponse.BodyHandlers.ofString()
            );

            JsonObject job = gson.fromJson(statusResponse.body(), JsonObject.class);
            String status = job.get("status").getAsString();

            if ("COMPLETED".equals(status)) {
                System.out.println("Job completed! Downloading results...");
                break;
            } else if ("FAILED".equals(status)) {
                System.out.println("Job failed!");
                return;
            } else {
                System.out.println("Status: " + status + ", waiting...");
                Thread.sleep(5000);
            }
        }

        // Download results
        HttpRequest downloadRequest = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/jobs/" + JOB_ID + "/download"))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();

        HttpResponse downloadResponse = client.send(
            downloadRequest,
            HttpResponse.BodyHandlers.ofFile(Paths.get("results.csv"))
        );

        System.out.println("Results downloaded to: " + downloadResponse.body());
    }
}
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "io/ioutil"
    "net/http"
    "os"
    "time"
)

const (
    API_KEY  = "sk_live_your_api_key_here"
    BASE_URL = "https://goemailverify.com"
    JOB_ID   = "550e8400-e29b-41d4-a716-446655440000"
)

type JobStatus struct {
    Status string `json:"status"`
}

func main() {
    client := &http.Client{}

    // First, check status until complete
    for {
        statusURL := fmt.Sprintf("%s/api/jobs/%s/status", BASE_URL, JOB_ID)
        req, _ := http.NewRequest("GET", statusURL, nil)
        req.Header.Set("Authorization", "Bearer "+API_KEY)

        resp, _ := client.Do(req)
        body, _ := ioutil.ReadAll(resp.Body)
        resp.Body.Close()

        var job JobStatus
        json.Unmarshal(body, &job)

        if job.Status == "COMPLETED" {
            fmt.Println("Job completed! Downloading results...")
            break
        } else if job.Status == "FAILED" {
            fmt.Println("Job failed!")
            return
        } else {
            fmt.Printf("Status: %s, waiting...\n", job.Status)
            time.Sleep(5 * time.Second)
        }
    }

    // Download results
    downloadURL := fmt.Sprintf("%s/api/jobs/%s/download", BASE_URL, JOB_ID)
    req, _ := http.NewRequest("GET", downloadURL, nil)
    req.Header.Set("Authorization", "Bearer "+API_KEY)

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    out, _ := os.Create("results.csv")
    defer out.Close()

    io.Copy(out, resp.Body)
    fmt.Println("Results downloaded successfully!")
}

GET /api/jobs

List all jobs for the authenticated user with pagination and filtering.

Query Parameters

  • page (optional): Page number (default: 0)
  • size (optional): Page size (default: 20)
  • status (optional): Filter by status (PENDING, IN_PROGRESS, COMPLETED, FAILED)

Response (200 OK)

{
  "content": [
    {
      "jobId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "COMPLETED",
      "totalEmails": 10000,
      "validEmails": 8523,
      "invalidEmails": 1477,
      "createdAt": "2025-10-20T10:30:00",
      "completedAt": "2025-10-20T10:35:42"
    }
  ],
  "totalElements": 45,
  "totalPages": 3,
  "currentPage": 0,
  "pageSize": 20
}

DELETE /api/jobs/{jobId}

Delete a completed job and its results.

Response (200 OK)

{
  "message": "Job deleted successfully",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

API Key Management Endpoints

GET /api/apikeys

List all API keys for the authenticated user.

Response (200 OK)

[
  {
    "apiKeyId": 123,
    "keyPrefix": "sk_live_a1b2",
    "keyName": "Production App",
    "description": "Main application API key",
    "status": "ACTIVE",
    "createdAt": "2025-10-15T09:00:00",
    "lastUsedAt": "2025-10-20T10:30:00"
  }
]

Code Example

curl -X GET https://goemailverify.com/api/apikeys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/apikeys

Create a new API key. The full key is returned only once.

Request

{
  "keyName": "Production App",
  "description": "Main application API key",
  "scopes": ["EMAIL_VALIDATION", "BULK_UPLOAD"],
  "rateLimitPerMinute": 60,
  "expiresAt": "2026-10-20T00:00:00"
}

Response (201 Created)

{
  "apiKeyId": 123,
  "keyValue": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "keyPrefix": "sk_live_a1b2",
  "keyName": "Production App",
  "status": "ACTIVE",
  "message": "Save this key - it won't be shown again!"
}
Important: The full API key is only shown once during creation. Store it securely immediately.

Code Example

curl -X POST https://goemailverify.com/api/apikeys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "Production App",
    "description": "Main application API key"
  }'

DELETE /api/apikeys/{keyId}

Revoke an API key permanently.

Response (200 OK)

{
  "message": "API key revoked successfully",
  "apiKeyId": 123
}

Code Example

curl -X DELETE https://goemailverify.com/api/apikeys/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Codes

HTTP Status Codes

Code Description
200 Success
201 Created
400 Bad Request - Invalid parameters or request format
401 Unauthorized - Invalid or missing API key/token
403 Forbidden - Insufficient permissions for requested resource
404 Not Found - Requested resource does not exist
429 Rate Limit Exceeded - Too many requests
500 Internal Server Error - Contact support if persists

Validation Error Codes

Code Type Description
100 SYNTAX_ERROR Invalid email syntax - basic format validation failed
101 MISSING_AT_SYMBOL Email missing required @ symbol
200 INVALID_TLD Invalid top-level domain
300 PROVIDER_TYPO Possible typo in email provider (e.g., gmial.com instead of gmail.com)
400 BLOCKED_DOMAIN Domain is blocked or blacklisted
401 DISPOSABLE_EMAIL Disposable/temporary email address detected
500 NO_MX_RECORDS No MX records found for domain
501 SMTP_VERIFICATION_FAILED SMTP server rejected email address
600 HIGH_BOUNCE_RISK High bounce risk detected based on historical data
700 RATE_LIMIT_EXCEEDED API rate limit exceeded
800 NEW_DOMAIN_WARNING Domain recently registered (less than 90 days)
801 NEW_EMAIL_WARNING Email recently created based on pattern analysis
802 BOT_PATTERN_WARNING Bot or automated pattern detected in email username

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error message",
  "code": 400,
  "timestamp": "2025-10-20T10:30:00",
  "path": "/api/validate-emails"
}

Rate Limits

Default Limits by Plan

Plan Per Minute Per Day Per Month
Free 10 requests 1,000 requests 10,000 emails
Pro 100 requests 10,000 requests 300,000 emails
Premium 200 requests 20,000 requests 500,000 emails

Rate Limit Headers

All API responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1634567890

Rate Limit Exceeded Response

When rate limited (429 status):

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after 45 seconds.",
  "retryAfter": 45
}

Best Practices for Rate Limiting

Implement Exponential Backoff

import time

def with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = min(2 ** attempt, e.retry_after)
            time.sleep(wait_time)

Monitor Rate Limit Headers

response = requests.get(url, headers=headers)

remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
if remaining < 10:
    print("Warning: Approaching rate limit")
    time.sleep(5)  # Slow down requests

Use Batch Endpoints

For multiple emails, use the batch endpoint instead of individual requests:

  • Single endpoint: 100 emails = 100 requests
  • Batch endpoint: 100 emails = 1 request

Ready to Integrate?

Start building with our API today. Get 100 free credits to test integration.

Get API Access

No credit card required • Full API access