API Overview

The TrueMail API lets you integrate email validation directly into your applications. Validate emails in real-time during signups, clean lists programmatically, or build custom workflows.

Base URL

All API requests should be made to:

https://api.truemail.app/v1

Authentication

TrueMail uses API keys for authentication. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting your API key

1. Log in to your TrueMail dashboard
2. Go to Settings → API Keys
3. Click Create New Key
4. Give it a descriptive name
5. Copy and securely store the key

Important: API keys are shown only once when created. Store them securely—we can’t retrieve them for you.

See Managing API Keys for more details.

Rate Limits

To ensure fair usage, API requests are rate-limited based on your plan:

When you exceed the limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded"
}

Best practice: Implement exponential backoff when you hit rate limits. Wait a few seconds and retry.

Request Format

• All requests use JSON for request and response bodies
• Set Content-Type: application/json for POST requests
• All responses are JSON

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]"}'

Example response

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

Available Endpoints

HTTP Status Codes

TrueMail uses standard HTTP status codes:

Error Responses

When something goes wrong, you’ll receive a JSON error response:

{
  "error": "Description of what went wrong"
}

See Error Handling for detailed error codes and how to handle them.

SDKs and Libraries

While we don’t have official SDKs yet, the API is simple enough to use with any HTTP client:

cURL

curl -X POST https://api.truemail.app/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"email": "[email protected]"}'

JavaScript (fetch)

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: '[email protected]' })
});

const result = await response.json();

Python (requests)

import requests

response = requests.post(
    'https://api.truemail.app/v1/verify',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'email': '[email protected]'}
)

result = response.json()

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.truemail.app/v1/verify')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { email: '[email protected]' }.to_json

response = http.request(request)
result = JSON.parse(response.body)

PHP

$ch = curl_init('https://api.truemail.app/v1/verify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => '[email protected]'
]));

$response = curl_exec($ch);
$result = json_decode($response, true);

Next Steps

• Verify Endpoint - Validate emails
• Usage Endpoint - Check your credits
• Filters Endpoints - Manage blocklists via API
• Error Handling - Handle errors gracefully