Filters Endpoints

Manage your blocklists programmatically. Create, list, and delete filters for emails, domains, and IP addresses via the API.

Overview

Filters let you automatically block certain addresses before they’re validated. Any email matching a filter is immediately marked as “bad” without using validation credits.

Filter types

Type Description Plan
email Block specific email addresses All plans
domain Block entire domains All plans
ip_address Block by sender IP Premium only

List Filters

Retrieve all your filters with optional filtering and pagination.

Endpoint

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

Query parameters

Parameter Type Description
filter_type string Filter by type: email, domain, or ip_address
query string Search in value or reason fields
page integer Page number (default: 1)

Example request

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

Response (200 OK)

{
  "filters": [
    {
      "id": 123,
      "filter_type": "domain",
      "value": "spam-domain.com",
      "reason": "Known spam source",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 124,
      "filter_type": "domain",
      "value": "fake-company.xyz",
      "reason": "Fraudulent signups",
      "created_at": "2024-01-14T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 47
  }
}

Create Filter

Add a new filter to your blocklist.

Endpoint

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

Request body

Field Type Required Description
filter_type string Yes email, domain, or ip_address
value string Yes The value to block
reason string No Why you’re blocking this (for your reference)

Example: Block an email

curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer tm_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filter_type": "email",
      "value": "[email protected]",
      "reason": "Submitted fake data multiple times"
    }
  }'

Example: Block a domain

curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer tm_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filter_type": "domain",
      "value": "competitor-spam.com",
      "reason": "Competitor email harvesting"
    }
  }'

Example: Block an IP (Premium)

curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer tm_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filter_type": "ip_address",
      "value": "192.168.1.100",
      "reason": "Bot traffic source"
    }
  }'

Response (201 Created)

{
  "filter": {
    "id": 125,
    "filter_type": "email",
    "value": "[email protected]",
    "reason": "Submitted fake data multiple times",
    "created_at": "2024-01-20T09:15:00Z"
  }
}

Delete Filter

Remove a filter from your blocklist.

Endpoint

DELETE https://api.truemail.app/v1/filters/:id

Example request

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

Response (200 OK)

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

Error Responses

Validation errors (422)

{
  "error": "invalid email format"
}

Common validation errors:

  • invalid email format - Email doesn’t match valid format
  • invalid domain format - Domain format is incorrect
  • invalid IP address format - IP address is malformed

Filter not found (404)

{
  "error": "Filter not found"
}

IP filters require Premium (403)

{
  "error": "IP address filtering requires a premium plan"
}

Duplicate filter (422)

{
  "error": "Value has already been taken"
}

Code Examples

JavaScript - Sync blocklist from CRM

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

  async addFilter(type, value, reason = '') {
    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        filter: { filter_type: type, value, reason }
      })
    });

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

    return response.json();
  }

  async listFilters(type = null) {
    const url = type 
      ? `${this.baseUrl}?filter_type=${type}` 
      : this.baseUrl;

    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });

    return response.json();
  }

  async removeFilter(id) {
    const response = await fetch(`${this.baseUrl}/${id}`, {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });

    return response.json();
  }
}

// Usage: Block domains from your spam reports
const filters = new FilterManager('YOUR_API_KEY');

const spamDomains = ['spam1.com', 'spam2.net', 'fake-company.xyz'];
for (const domain of spamDomains) {
  try {
    await filters.addFilter('domain', domain, 'From spam report');
    console.log(`Blocked: ${domain}`);
  } catch (e) {
    console.log(`Skipped ${domain}: ${e.message}`);
  }
}

Python - Import blocklist from file

import requests
import csv

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

def add_filter(filter_type, value, reason=''):
    response = requests.post(
        BASE_URL,
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'filter': {
                'filter_type': filter_type,
                'value': value,
                'reason': reason
            }
        }
    )
    return response.json()

def import_blocklist(filename):
    """Import filters from a CSV file with columns: type, value, reason"""
    with open(filename, 'r') as f:
        reader = csv.DictReader(f)
        for row in reader:
            try:
                result = add_filter(
                    row['type'], 
                    row['value'], 
                    row.get('reason', '')
                )
                print(f"Added: {row['value']}")
            except Exception as e:
                print(f"Failed: {row['value']} - {e}")

# Usage
import_blocklist('blocklist.csv')

Ruby - Webhook integration

# When a user marks email as spam, add to blocklist
class SpamReportHandler
  def initialize(api_key)
    @api_key = api_key
  end

  def handle_spam_report(email:, reason:)
    # Block the specific email
    add_filter('email', email, reason)
    
    # Optionally block the domain too
    domain = email.split('@').last
    add_filter('domain', domain, "Domain of reported spam: #{email}")
  end

  private

  def add_filter(type, value, reason)
    HTTP.auth("Bearer #{@api_key}")
        .post('https://api.truemail.app/v1/filters', json: {
          filter: {
            filter_type: type,
            value: value,
            reason: reason
          }
        })
  end
end

# In your webhook controller
handler = SpamReportHandler.new(ENV['TRUEMAIL_API_KEY'])
handler.handle_spam_report(
  email: params[:reported_email],
  reason: "User spam report"
)

PHP - Admin panel integration

class TruemailFilters {
    private $apiKey;
    private $baseUrl = 'https://api.truemail.app/v1/filters';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function getAll($type = null, $page = 1) {
        $url = $this->baseUrl . "?page={$page}";
        if ($type) {
            $url .= "&filter_type={$type}";
        }
        
        return $this->request('GET', $url);
    }
    
    public function add($type, $value, $reason = '') {
        return $this->request('POST', $this->baseUrl, [
            'filter' => [
                'filter_type' => $type,
                'value' => $value,
                'reason' => $reason
            ]
        ]);
    }
    
    public function delete($id) {
        return $this->request('DELETE', "{$this->baseUrl}/{$id}");
    }
    
    private function request($method, $url, $data = null) {
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ]);
        
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

// Usage in WordPress admin
$filters = new TruemailFilters(get_option('truemail_api_key'));

// Add domain from admin form
if ($_POST['action'] === 'block_domain') {
    $filters->add('domain', $_POST['domain'], $_POST['reason']);
}

Best Practices

1. Add context with reasons

Always include a reason when creating filters. It helps when reviewing your blocklist later.

2. Start with domains

Blocking a domain is more efficient than blocking individual emails. If you see multiple bad emails from one domain, block the whole domain.

3. Review periodically

Export and review your filters occasionally. Remove any that are no longer needed.

4. Sync with your systems

If you have a blocklist in your CRM or email platform, sync it to TrueMail to save credits.

We use cookies to process payments and improve your experience. By using TrueMail, you agree to our use of cookies in accordance with our Privacy Policy.