TrueEmailer API Documentation

v2.0
Get API Key

TrueEmailer API v2

Welcome to the TrueEmailer API documentation. Our REST API allows you to verify email addresses programmatically with high accuracy and speed. Whether you need to verify a single email or process thousands in bulk, our API has you covered.

Quick Start

  1. Get your API key from app.trueemailer.com/api-integration
  2. Include it in the Authorization header of your requests
  3. Start verifying emails using our endpoints

Base URL

https://app.trueemailer.com/api/v2

Features

  • Single Email Verification: Verify one email at a time with instant results
  • Bulk Verification: Process up to 100 emails per request with job tracking
  • Result Caching: Previously verified emails return cached results without deducting credits
  • MX Record Validation: Deep email validation including MX record checks

Authentication

All API requests require authentication using an API key. You can obtain your API key from the TrueEmailer dashboard at app.trueemailer.com/api-integration.

Include your API key in the Authorization header of every request:

bash
curl -X POST "https://app.trueemailer.com/api/v2/verify" \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Security Note

Keep your API key secure and never expose it in client-side code. Always make API calls from your server.

Single Email Verification

Verify a single email address and get instant results. If the email has been verified before, cached results are returned without deducting credits.

POST/api/v2/verify

Request Body

FieldTypeRequiredDescription
emailstringYesThe email address to verify

Examples

cURL

bash
curl -X POST "https://app.trueemailer.com/api/v2/verify" \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

JavaScript

javascript
const response = await fetch('https://app.trueemailer.com/api/v2/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com'
  })
});

const result = await response.json();
console.log(result);

Python

python
import requests

url = "https://app.trueemailer.com/api/v2/verify"
headers = {
    "Authorization": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "email": "user@example.com"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

PHP

php
<?php
$url = "https://app.trueemailer.com/api/v2/verify";
$headers = [
    "Authorization: your_api_key_here",
    "Content-Type: application/json"
];
$data = json_encode([
    "email" => "user@example.com"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Response

New Verification (200 OK)

json
{
  "status": "valid",
  "mx_record": "mx.example.com",
  "credits_remaining": 9999,
  "daily_remaining": 1999,
  "message": "New verification completed - 1 credit deducted"
}

Cached Result (200 OK)

json
{
  "status": "valid",
  "mx_record": "mx.example.com",
  "credits_remaining": 10000,
  "daily_remaining": 2000,
  "message": "Result retrieved from verification history - no credits deducted"
}

Response Fields

FieldTypeDescription
statusstringEmail validation status (valid, invalid, unknown)
mx_recordstringMX record of the email domain
credits_remainingnumber|stringRemaining credits ("unlimited" for scale-up plan)
daily_remainingnumberRemaining daily verifications
messagestringInformation about credit deduction

Bulk Email Verification

Verify multiple email addresses in a single request. The verification process runs asynchronously, and you can check the status using the job ID returned in the response.

Bulk Verification Limits

  • • Maximum 100 emails per request
  • • Jobs are processed asynchronously
  • • Use the bulk status endpoint to check progress
POST/api/v2/bulk/verify

Request Body

FieldTypeRequiredDescription
emailsarrayYesArray of email addresses to verify (max 100)

Examples

cURL

bash
curl -X POST "https://app.trueemailer.com/api/v2/bulk/verify" \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user1@example.com",
      "user2@example.com",
      "user3@example.com"
    ]
  }'

JavaScript

javascript
const response = await fetch('https://app.trueemailer.com/api/v2/bulk/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: [
      'user1@example.com',
      'user2@example.com',
      'user3@example.com'
    ]
  })
});

const result = await response.json();
console.log('Job ID:', result.job_id);

Response

Success (202 Accepted)

json
{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "total_emails": 3,
  "status": "pending",
  "message": "Bulk verification job created with 3 emails",
  "credits_remaining": 9997,
  "daily_remaining": 1997
}

Response Fields

FieldTypeDescription
successbooleanWhether the job was created successfully
job_idstringUnique identifier for the bulk job
total_emailsnumberTotal number of emails in the job
statusstringJob status (pending, processing, completed)
credits_remainingnumber|stringRemaining credits after job completion
daily_remainingnumberRemaining daily verifications after job completion

Bulk Verification Status

Check the status and results of a bulk verification job using the job ID returned from the bulk verification endpoint. This endpoint provides real-time progress updates and final results.

GET/api/v2/bulk/status/{job_id}

Path Parameters

ParameterTypeRequiredDescription
job_idstringYesThe job ID returned from bulk verification

Examples

cURL

bash
curl -X GET "https://app.trueemailer.com/api/v2/bulk/status/550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: your_api_key_here"

JavaScript

javascript
const jobId = '550e8400-e29b-41d4-a716-446655440001';
const response = await fetch(`https://app.trueemailer.com/api/v2/bulk/status/${jobId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'your_api_key_here'
  }
});

const result = await response.json();
console.log(`Job ${result.status}: ${result.progress_percentage}% complete`);

// Check if completed
if (result.status === 'completed') {
  result.results.forEach(email => {
    console.log(`${email.email}: ${email.status}`);
  });
}

Response

json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "completed",
  "total_emails": 3,
  "processed_emails": 3,
  "progress_percentage": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:31:30Z",
  "summary": {
    "valid": 2,
    "invalid": 1
  },
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "mx_record": "mx1.example.com",
      "error": null,
      "created_at": "2024-01-15T10:30:15Z"
    },
    {
      "email": "user2@example.com",
      "status": "valid",
      "mx_record": "mx2.example.com",
      "error": null,
      "created_at": "2024-01-15T10:30:30Z"
    },
    {
      "email": "invalid@invalid-domain.com",
      "status": "invalid",
      "mx_record": null,
      "error": "Domain does not exist",
      "created_at": "2024-01-15T10:30:45Z"
    }
  ]
}

Response Fields

FieldTypeDescription
job_idstringUnique job identifier
statusstringJob status: pending, processing, completed, failed
total_emailsnumberTotal emails in the job
processed_emailsnumberNumber of emails processed so far
progress_percentagenumberCompletion percentage (0-100)
summaryobjectCount of results by status
resultsarrayIndividual verification results

Job Status Values

  • • pending: Job is queued for processing
  • • processing: Job is currently being processed
  • • completed: All emails have been verified
  • • failed: Job encountered an error

Rate Limits & Plans

TrueEmailer enforces rate limits based on your subscription plan. All plans include both monthly credit limits and daily verification limits to ensure fair usage.

Trial Plan

  • 100 total credits
  • 100 verifications per day

Basic Plan

  • 10,000 total credits
  • 2,000 verifications per day

Advance Plan

  • 50,000 total credits
  • 5,000 verifications per day

Pro Plan

  • 100,000 total credits
  • 10,000 verifications per day

Scale-Up Plan

  • Unlimited credits - No monthly limit
  • 15,000 verifications per day

Rate Limit Headers

Each API response includes information about your remaining limits:

  • • credits_remaining - Your remaining monthly credits
  • • daily_remaining - Your remaining daily verifications

Error Codes

The TrueEmailer API uses conventional HTTP response codes to indicate the success or failure of an API request. Error responses include a JSON object with an error message and additional details.

HTTP Status Codes

CodeStatusDescription
200OKRequest successful
202AcceptedBulk job created successfully
400Bad RequestInvalid request format or parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient credits or trial expired
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableExternal service error

Common Error Examples

401 - Invalid API Key

json
{
  "error": "Invalid API key"
}

401 - Inactive API Key

json
{
  "error": "API key is inactive"
}

403 - Trial Expired

json
{
  "error": "Trial expired. Please subscribe to continue."
}

403 - No Credits Remaining

json
{
  "error": "No credits remaining. Please upgrade your plan."
}

429 - Daily Limit Reached

json
{
  "error": "Daily limit reached. Please try again tomorrow."
}

400 - Invalid Email Format

json
{
  "error": "Invalid email format"
}

400 - Too Many Emails (Bulk)

json
{
  "error": "Too many emails. Maximum 100 emails allowed per request. You provided 150 emails."
}

404 - Job Not Found

json
{
  "error": "Job not found or access denied"
}

503 - Service Unavailable

json
{
  "error": "External email verification service unavailable",
  "details": "Connection timeout",
  "status": 503
}

Error Handling Best Practices

  • Always check the HTTP status code before processing the response
  • Handle rate limit errors by implementing exponential backoff
  • Monitor your credit usage to avoid hitting limits unexpectedly
  • Implement proper error logging for debugging purposes