API Documentation

curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "value": "[email protected]",
      "filter_type": "email",
      "reason": "Known spam sender"
    }
  }'

{
  "id": 123,
  "value": "[email protected]",
  "filter_type": "email",
  "reason": "Known spam sender",
  "created_at": "2024-03-20T12:00:00Z"
}

curl -X GET "https://api.truemail.app/v1/filters?filter_type=email&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "filters": [
    {
      "id": 123,
      "value": "[email protected]",
      "filter_type": "email",
      "reason": "Known spam sender",
      "created_at": "2024-03-20T12:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Verify Email (MX)

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

Verify Email (SMTP - Premium)

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

Get Usage & Available Methods

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

Create Filter

curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "value": "[email protected]",
      "filter_type": "email",
      "reason": "Known spam sender"
    }
  }'

List Filters

curl -X GET "https://api.truemail.app/v1/filters?filter_type=email&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete Filter

curl -X DELETE https://api.truemail.app/v1/filters/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'json'

class TruemailClient
  BASE_URL = 'https://api.truemail.app/v1'

  def initialize(api_key)
    @api_key = api_key
  end

  def verify_email(email)
    uri = URI("#{BASE_URL}/verify")
    request = Net::HTTP::Post.new(uri)
    request.body = { email: email }.to_json
    perform_request(request)
  end

  def get_usage
    uri = URI("#{BASE_URL}/usage")
    request = Net::HTTP::Get.new(uri)
    perform_request(request)
  end

  def get_available_validation_types
    usage = get_usage
    usage['validation_types']
  end

  def verify_email_with_best_method(email)
    types = get_available_validation_types

    # Use SMTP if available, otherwise fall back to MX
    validation_type = types['smtp']['available'] ? 'smtp' : 'mx'

    uri = URI("#{BASE_URL}/verify")
    request = Net::HTTP::Post.new(uri)
    request.body = { email: email, validation_type: validation_type }.to_json
    perform_request(request)
  end

  def create_filter(value:, filter_type:, reason:)
    uri = URI("#{BASE_URL}/filters")
    request = Net::HTTP::Post.new(uri)
    request.body = {
      filter: {
        value: value,
        filter_type: filter_type,
        reason: reason
      }
    }.to_json
    perform_request(request)
  end

  def list_filters(filter_type: nil, page: 1)
    uri = URI("#{BASE_URL}/filters")
    uri.query = URI.encode_www_form(filter_type: filter_type, page: page)
    request = Net::HTTP::Get.new(uri)
    perform_request(request)
  end

  def delete_filter(id)
    uri = URI("#{BASE_URL}/filters/#{id}")
    request = Net::HTTP::Delete.new(uri)
    perform_request(request)
  end

  private

  def perform_request(request)
    request['Authorization'] = "Bearer #{@api_key}"
    request['Content-Type'] = 'application/json'

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

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

# Usage
client = TruemailClient.new('YOUR_API_KEY')

# Verify email
result = client.verify_email('[email protected]')

# Get usage and available types
usage = client.get_usage
puts "Available validation types:"
usage['validation_types'].each do |type, details|
  puts "#{type.upcase}: #{details['credits']} credits (Available: #{details['available']})"
end

# Get just the validation types
types = client.get_available_validation_types

# Verify email with best available method
result = client.verify_email_with_best_method('[email protected]')

# Create a filter
result = client.create_filter(
  value: '[email protected]',
  filter_type: 'email',
  reason: 'Known spam sender'
)

# List filters
filters = client.list_filters(filter_type: 'email', page: 1)

# Delete a filter
result = client.delete_filter(123)

import requests

class TruemailClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.truemail.app/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def verify_email(self, email):
        response = requests.post(
            f'{self.base_url}/verify',
            headers=self.headers,
            json={'email': email}
        )
        return response.json()

    def get_usage(self):
        response = requests.get(
            f'{self.base_url}/usage',
            headers=self.headers
        )
        return response.json()

    def get_available_validation_types(self):
        usage = self.get_usage()
        return usage['validation_types']

    def verify_email_with_best_method(self, email):
        types = self.get_available_validation_types()

        # Use SMTP if available, otherwise fall back to MX
        validation_type = 'smtp' if types['smtp']['available'] else 'mx'

        response = requests.post(
            f'{self.base_url}/verify',
            headers=self.headers,
            json={'email': email, 'validation_type': validation_type}
        )
        return response.json()

    def create_filter(self, value, filter_type, reason):
        response = requests.post(
            f'{self.base_url}/filters',
            headers=self.headers,
            json={
                'filter': {
                    'value': value,
                    'filter_type': filter_type,
                    'reason': reason
                }
            }
        )
        return response.json()

    def list_filters(self, filter_type=None, page=1):
        params = {'page': page}
        if filter_type:
            params['filter_type'] = filter_type

        response = requests.get(
            f'{self.base_url}/filters',
            headers=self.headers,
            params=params
        )
        return response.json()

    def delete_filter(self, filter_id):
        response = requests.delete(
            f'{self.base_url}/filters/{filter_id}',
            headers=self.headers
        )
        return response.json()

# Usage
client = TruemailClient('YOUR_API_KEY')

# Verify email
result = client.verify_email('[email protected]')

# Get usage and available types
usage = client.get_usage()
print("Available validation types:")
for type_key, details in usage['validation_types'].items():
    print(f"{type_key.upper()}: {details['credits']} credits (Available: {details['available']})")

# Get just the validation types
types = client.get_available_validation_types()

# Verify email with best available method
result = client.verify_email_with_best_method('[email protected]')

# Create a filter
result = client.create_filter(
    value='[email protected]',
    filter_type='email',
    reason='Known spam sender'
)

# List filters
filters = client.list_filters(filter_type='email', page=1)

# Delete a filter
result = client.delete_filter(123)

class TruemailClient {
    private $apiKey;
    private $baseUrl = 'https://api.truemail.app/v1';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function verifyEmail($email) {
        return $this->request('POST', '/verify', [
            'email' => $email
        ]);
    }

    public function getUsage() {
        return $this->request('GET', '/usage');
    }

    public function createFilter($value, $filterType, $reason) {
        return $this->request('POST', '/filters', [
            'filter' => [
                'value' => $value,
                'filter_type' => $filterType,
                'reason' => $reason
            ]
        ]);
    }

    public function listFilters($filterType = null, $page = 1) {
        $query = http_build_query([
            'filter_type' => $filterType,
            'page' => $page
        ]);
        return $this->request('GET', "/filters?{$query}");
    }

    public function deleteFilter($id) {
        return $this->request('DELETE', "/filters/{$id}");
    }

    private function request($method, $path, $data = null) {
        $curl = curl_init();

        $url = $this->baseUrl . $path;
        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ];

        curl_setopt_array($curl, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => $headers
        ]);

        if ($data) {
            curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($curl);
        $error = curl_error($curl);
        curl_close($curl);

        if ($error) {
            throw new Exception('cURL Error: ' . $error);
        }

        return json_decode($response, true);
    }
}

// Usage
$client = new TruemailClient('YOUR_API_KEY');

// Verify email
$result = $client->verifyEmail('[email protected]');

// Get usage
$usage = $client->getUsage();

// Create a filter
$result = $client->createFilter(
    '[email protected]',
    'email',
    'Known spam sender'
);

// List filters
$filters = $client->listFilters('email', 1);

// Delete a filter
$result = $client->deleteFilter(123);

class TruemailClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.truemail.app/v1';
  }

  async verifyEmail(email) {
    return this.request('POST', '/verify', { email });
  }

  async getUsage() {
    return this.request('GET', '/usage');
  }

  async createFilter(value, filterType, reason) {
    return this.request('POST', '/filters', {
      filter: {
        value,
        filter_type: filterType,
        reason
      }
    });
  }

  async listFilters(filterType = null, page = 1) {
    const params = new URLSearchParams({ page: page });
    if (filterType) params.append('filter_type', filterType);

    return this.request('GET', `/filters?${params}`);
  }

  async deleteFilter(id) {
    return this.request('DELETE', `/filters/${id}`);
  }

  async request(method, path, body = null) {
    const options = {
      method,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    };

    if (body) {
      options.body = JSON.stringify(body);
    }

    const response = await fetch(`${this.baseUrl}${path}`, options);
    return response.json();
  }
}

// Usage
const client = new TruemailClient('YOUR_API_KEY');

// Verify email
const result = await client.verifyEmail('[email protected]');

// Get usage
const usage = await client.getUsage();

// Create a filter
const result = await client.createFilter(
  '[email protected]',
  'email',
  'Known spam sender'
);

// List filters
const filters = await client.listFilters('email', 1);

// Delete a filter
const result = await client.deleteFilter(123);