Verify Endpoint

Validate a single email address and get instant results. Perfect for signup forms, CRM integrations, or any real-time validation needs.

Endpoint

POST https://api.truemail.app/v1/verify

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request

Parameters

Example request

curl -X POST https://api.truemail.app/v1/verify \
  -H "Authorization: Bearer tm_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "validation_type": "mx"
  }'

Response

Success (200 OK)

{
  "email": "[email protected]",
  "status": "good",
  "validation_type": "mx",
  "credits_used": 1
}

Response fields

Status values

Failure reasons

When status is bad, the reason field explains why:

Validation Types

MX Validation (default)

• Cost: 1 credit
• Speed: ~100ms
• Checks: Email format, domain existence, MX records

{
  "email": "[email protected]",
  "validation_type": "mx"
}

SMTP Validation

• Cost: 10 credits
• Speed: ~1-3 seconds
• Checks: Everything in MX, plus mailbox existence
• Requires: Premium plan

{
  "email": "[email protected]",
  "validation_type": "smtp"
}

Error Responses

Missing email parameter (400)

{
  "error": "Email parameter is required"
}

Invalid validation type (422)

{
  "error": "Invalid validation_type. Must be 'mx' or 'smtp'",
  "valid_types": ["mx", "smtp"]
}

SMTP requires Premium (402)

{
  "error": "SMTP validation requires a Premium subscription",
  "current_plan": "starter"
}

Insufficient credits (402)

{
  "error": "Insufficient account credits"
}

Invalid API key (401)

{
  "error": "Invalid API key"
}

IP not allowed (403)

{
  "error": "IP address not allowed"
}

Rate limit exceeded (429)

{
  "error": "Rate limit exceeded"
}

Code Examples

JavaScript - Form validation

async function validateEmail(email) {
  const response = await fetch('https://api.truemail.app/v1/verify', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

// Usage in a form
document.querySelector('form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const email = document.querySelector('#email').value;
  
  try {
    const result = await validateEmail(email);
    if (result.status === 'good') {
      // Proceed with form submission
      e.target.submit();
    } else {
      alert('Please enter a valid email address');
    }
  } catch (error) {
    console.error('Validation error:', error);
  }
});

Python - Batch validation

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.truemail.app/v1/verify'

def validate_email(email, validation_type='mx'):
    response = requests.post(
        BASE_URL,
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={'email': email, 'validation_type': validation_type}
    )
    
    if response.status_code == 429:
        # Rate limited, wait and retry
        time.sleep(5)
        return validate_email(email, validation_type)
    
    return response.json()

# Validate a list of emails
emails = ['[email protected]', '[email protected]', '[email protected]']
results = []

for email in emails:
    result = validate_email(email)
    results.append(result)
    print(f"{email}: {result['status']}")

Ruby - Rails integration

class EmailValidationService
  API_URL = 'https://api.truemail.app/v1/verify'
  
  def initialize(api_key)
    @api_key = api_key
  end
  
  def validate(email, validation_type: 'mx')
    response = HTTP.auth("Bearer #{@api_key}")
                   .post(API_URL, json: { 
                     email: email, 
                     validation_type: validation_type 
                   })
    
    JSON.parse(response.body)
  end
end

# Usage
validator = EmailValidationService.new(ENV['TRUEMAIL_API_KEY'])
result = validator.validate('[email protected]')

if result['status'] == 'good'
  # Email is valid
end

PHP - WordPress plugin example

function truemail_validate_email($email) {
    $api_key = get_option('truemail_api_key');
    
    $response = wp_remote_post('https://api.truemail.app/v1/verify', [
        'headers' => [
            'Authorization' => 'Bearer ' . $api_key,
            'Content-Type' => 'application/json'
        ],
        'body' => json_encode(['email' => $email])
    ]);
    
    if (is_wp_error($response)) {
        return null;
    }
    
    return json_decode(wp_remote_retrieve_body($response), true);
}

// Hook into registration
add_filter('registration_errors', function($errors, $sanitized_user_login, $user_email) {
    $result = truemail_validate_email($user_email);
    
    if ($result && $result['status'] === 'bad') {
        $errors->add('invalid_email', 'Please enter a valid email address.');
    }
    
    return $errors;
}, 10, 3);

Best Practices

1. Use appropriate validation type

• MX validation for high-volume, speed-critical scenarios
• SMTP validation for important signups or campaigns

2. Handle errors gracefully

Always check for error responses and handle rate limits with retries.

3. Cache results

If validating the same email multiple times, cache the result to save credits.

4. Validate server-side

Never expose your API key in client-side code. Always validate from your backend.

5. Combine with filters

Use filters to block known bad addresses before they use credits.

Related

• API Overview - Authentication and basics
• Validation Types - MX vs SMTP explained
• Error Handling - Complete error reference