Usage Endpoint

Check your current credit balance, plan details, and rate limits. Useful for monitoring usage or displaying account status in your application.

Endpoint

GET https://api.truemail.app/v1/usage

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request

No parameters required. Just make a GET request with authentication.

Example request

curl -X GET https://api.truemail.app/v1/usage \
  -H "Authorization: Bearer tm_live_abc123..."

Response

Success (200 OK)

{
  "plan": "premium",
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-02-01T00:00:00Z"
  },
  "credits": {
    "total": 45230,
    "locked": 1500
  },
  "rate_limit": {
    "limit": 300
  },
  "validation_types": {
    "mx": {
      "credits": 1,
      "available": true
    },
    "smtp": {
      "credits": 10,
      "available": true
    }
  }
}

Response fields

Understanding credits

• total: Credits available for immediate use
• locked: Credits temporarily held for bulk validations in progress

Your actual available balance is total (locked credits are already deducted from the balance shown).

Validation types availability

For non-Premium users, the SMTP validation shows an upgrade message:

{
  "validation_types": {
    "mx": {
      "credits": 1,
      "available": true
    },
    "smtp": {
      "credits": 10,
      "available": false,
      "upgrade_required": "Premium subscription required"
    }
  }
}

Error Responses

Invalid API key (401)

{
  "error": "Invalid API key"
}

IP not allowed (403)

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

Code Examples

JavaScript - Dashboard widget

async function getUsage() {
  const response = await fetch('https://api.truemail.app/v1/usage', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch usage');
  }

  return response.json();
}

// Display in your UI
async function updateDashboard() {
  const usage = await getUsage();
  
  document.querySelector('#credits').textContent = 
    usage.credits.total.toLocaleString();
  document.querySelector('#plan').textContent = 
    usage.plan.charAt(0).toUpperCase() + usage.plan.slice(1);
}

Python - Pre-validation check

import requests

def check_credits_before_validation(emails_count, validation_type='mx'):
    """Check if we have enough credits before starting validation."""
    
    response = requests.get(
        'https://api.truemail.app/v1/usage',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    )
    
    usage = response.json()
    
    credits_per_email = usage['validation_types'][validation_type]['credits']
    required_credits = emails_count * credits_per_email
    available_credits = usage['credits']['total']
    
    if required_credits > available_credits:
        shortfall = required_credits - available_credits
        raise Exception(
            f"Insufficient credits. Need {required_credits}, "
            f"have {available_credits}. Short by {shortfall}."
        )
    
    return True

# Usage
try:
    check_credits_before_validation(5000, 'mx')
    print("Ready to validate!")
except Exception as e:
    print(f"Cannot proceed: {e}")

Ruby - Usage monitoring

class TruemailUsageMonitor
  def initialize(api_key, threshold: 1000)
    @api_key = api_key
    @threshold = threshold
  end
  
  def check
    response = HTTP.auth("Bearer #{@api_key}")
                   .get('https://api.truemail.app/v1/usage')
    
    usage = JSON.parse(response.body)
    credits = usage['credits']['total']
    
    if credits < @threshold
      notify_low_credits(credits)
    end
    
    usage
  end
  
  private
  
  def notify_low_credits(credits)
    # Send alert email, Slack message, etc.
    puts "Warning: Only #{credits} credits remaining!"
  end
end

# Run as a scheduled job
monitor = TruemailUsageMonitor.new(ENV['TRUEMAIL_API_KEY'])
monitor.check

PHP - Credit check helper

class TruemailUsage {
    private $apiKey;
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function getUsage() {
        $ch = curl_init('https://api.truemail.app/v1/usage');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function hasEnoughCredits($count, $type = 'mx') {
        $usage = $this->getUsage();
        $creditsPerEmail = $usage['validation_types'][$type]['credits'];
        $required = $count * $creditsPerEmail;
        
        return $usage['credits']['total'] >= $required;
    }
}

// Usage
$truemail = new TruemailUsage('YOUR_API_KEY');

if ($truemail->hasEnoughCredits(1000, 'smtp')) {
    // Proceed with validation
} else {
    echo "Please purchase more credits";
}

Use Cases

Pre-flight checks

Before starting a bulk validation job via API, check that you have enough credits:

emails_to_validate = 10000
credits_needed = emails_to_validate * 1  # MX validation

usage = get_usage()
if usage['credits']['total'] >= credits_needed:
    start_validation(emails)
else:
    notify_admin("Insufficient credits for scheduled validation")

Low credit alerts

Set up monitoring to alert when credits drop below a threshold:

const LOW_CREDIT_THRESHOLD = 5000;

async function checkAndAlert() {
  const usage = await getUsage();
  
  if (usage.credits.total < LOW_CREDIT_THRESHOLD) {
    await sendSlackAlert(
      `⚠️ TrueMail credits low: ${usage.credits.total} remaining`
    );
  }
}

// Run daily
setInterval(checkAndAlert, 24 * 60 * 60 * 1000);

Usage dashboards

Display real-time credit usage in your admin panel:

Related

• API Overview - Authentication and basics
• Understanding Credits - How credits work
• Credit Packs - Purchase more credits