API Documentation

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate your API key in your account settings.

Endpoints

Validate Single Email

POST /api/v1/verify

Request

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

Response

{
  "email": "[email protected]",
  "valid": true,
  "checks": {
    "format": true,
    "mx": true,
    "smtp": true
  },
  "score": 1.0
}

Email Filters

POST /api/v1/filters

Request

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

Available filter types: "email", "domain", "ip_address" (Premium only)

Response

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

GET /api/v1/filters

Request

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

Query Parameters

filter_type: Filter by type (email, domain, ip_address)
query: Search by value or reason
page: Page number for pagination

Response

{
  "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
  }
}

DELETE /api/v1/filters/:id

Request

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

Response

{
  "status": "success",
  "message": "Filter was successfully removed"
}

Get Account Usage

GET /api/v1/usage

Request

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

Response

{
  "plan": "premium",
  "period": {
    "start": "2024-03-01T00:00:00Z",
    "end": "2024-03-31T23:59:59Z"
  },
  "credits": {
    "used": 1500,
    "limit": 10000,
    "remaining": 8500
  },
  "rate_limit": {
    "limit": 300,
    "remaining": 295,
    "reset_at": "2024-03-20T12:30:00Z"
  }
}

Rate Limits

Rate limits are based on your subscription plan:

Starter: 60 requests every 5 minutes
Premium: 300 requests every 5 minutes
Enterprise: Custom limits available

Error Handling

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
429	Too Many Requests - Rate limit exceeded

Code Samples

cURL

Verify Email

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

Get Usage

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"

Ruby

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 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
usage = client.get_usage

# 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)

Python

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 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
usage = client.get_usage()

# 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)

PHP

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);

Node.js

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);