Filters Overview

Filters let you create blocklists to automatically reject certain email addresses before they’re validated. This saves credits and keeps unwanted addresses out of your clean lists.

What are Filters?

Filters are rules that automatically mark matching emails as “bad” during validation. When an email matches one of your filters, it’s immediately rejected without consuming validation credits.

Filter types

Why Use Filters?

Save credits

If you know certain addresses are bad, filter them out instead of paying to validate them again.

Block known bad actors

Create a blocklist of addresses that have caused problems:

• Complainers and spam reporters
• Competitors harvesting your lists
• Known fraudulent addresses

Enforce business rules

Block addresses that don’t fit your needs:

• Competitor domains
• Free email providers (if you only want business emails)
• Known problematic domains

Automate list hygiene

Once set up, filters work automatically on every validation—bulk uploads and API requests alike.

How Filters Work

When you validate an email (via bulk upload or API):

1. TrueMail checks the email against your filters
2. If there’s a match, the email is marked as “bad” immediately
3. The response includes blocked_by_filter as the reason
4. No validation credits are used

Match priority

Filters are checked in this order:

1. Email filters - Exact email match
2. Domain filters - Domain part of the email
3. IP filters - Source IP of the request (API only)

The first match wins, and the email is rejected.

Managing Filters

From the dashboard

1. Go to Settings → Filters
2. Click Add Filter
3. Choose the filter type
4. Enter the value to block
5. (Optional) Add a reason for your reference
6. Click Save

Via API

You can also manage filters programmatically. See Filters API.

# Add a domain filter
curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filter": {
      "filter_type": "domain",
      "value": "spam-domain.com",
      "reason": "Known spam source"
    }
  }'

Validation Results with Filters

When an email is blocked by a filter, you’ll see it in the results:

Bulk validation

In your email list results, filtered addresses show:

• Status: Bad
• Reason: Blocked by filter

API response

{
  "email": "[email protected]",
  "status": "bad",
  "reason": "blocked_by_filter",
  "credits_used": 0
}

Notice credits_used: 0—filtered emails don’t cost credits.

Filter Best Practices

1. Start with domains

If you get multiple bad emails from the same domain, block the whole domain rather than individual addresses.

2. Add context with reasons

Always include a reason when creating filters. When you review your blocklist months later, you’ll know why each entry is there.

Domain: competitor.com
Reason: Competitor scraping our signup forms - added 2024-01-15

3. Review periodically

Blocklists can get stale. Review your filters occasionally and remove ones that are no longer relevant.

4. Import existing blocklists

If you already have a blocklist from your email platform or CRM, import it to TrueMail via the Filters API.

5. Sync across systems

Use webhooks or scheduled jobs to keep your TrueMail filters in sync with blocklists in other systems.

Filter Limits

There are no hard limits on the number of filters you can create. However, for best performance:

• Keep your filter list reasonable (under 10,000 entries)
• Use domain filters instead of many individual email filters
• Remove filters that are no longer needed

Common Use Cases

Block free email providers

If you only want business emails:

Domains to filter:
- gmail.com
- yahoo.com
- hotmail.com
- outlook.com

Block competitors

Keep competitor addresses out of your lists:

Domain: bigcompetitor.com
Reason: Competitor - remove from all campaigns

Block spam trap domains

Known spam trap operators:

Domain: spamtrap-domain.com
Reason: Known spam trap domain

Block after complaints

When someone marks you as spam:

Email: [email protected]
Reason: Spam complaint on 2024-01-15

Next Steps

• Email Filters - Block specific addresses
• Domain Filters - Block entire domains
• IP Filters - Block by IP (Premium)
• Filters API - Manage filters programmatically