Email Filters

Email filters let you block specific email addresses. When you know certain addresses are problematic, add them to your blocklist to automatically reject them during validation.

When to Use Email Filters

Block individual email addresses when:

• Someone has complained or unsubscribed permanently
• You’ve identified a fraudulent or fake address
• A specific person should never receive your emails
• An address has caused deliverability issues

Tip: If you’re blocking many addresses from the same domain, use a domain filter instead—it’s more efficient.

Adding an Email Filter

From the dashboard

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

Via API

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

Email Filter Rules

Format requirements

• Must be a valid email format
• Automatically converted to lowercase
• Spaces are trimmed

Valid examples

[email protected]
[email protected]
[email protected]

Invalid examples

not-an-email          # Missing @ and domain
@nodomain.com         # Missing local part
user@                 # Missing domain

Duplicate handling

You can’t add the same email twice. If you try, you’ll see:

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

How Email Filters Work

When validating an email:

1. TrueMail checks if the exact address matches any email filter
2. If matched, the email is immediately marked as “bad”
3. The reason shows blocked_by_filter
4. No credits are charged

Example

You’ve added [email protected] to your email filters.

When someone tries to validate that address:

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

Viewing Email Filters

From the dashboard

1. Go to Settings → Filters
2. Use the filter dropdown to show only Email filters
3. Search by email address or reason

Via API

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

Response:

{
  "filters": [
    {
      "id": 123,
      "filter_type": "email",
      "value": "[email protected]",
      "reason": "Spam complaint",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Removing Email Filters

If you need to unblock an address:

From the dashboard

1. Go to Settings → Filters
2. Find the email filter
3. Click the Delete button
4. Confirm the action

Via API

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

Common Use Cases

Suppression list integration

Sync your email platform’s suppression list with TrueMail:

# Example: Import suppression list
suppressed_emails = get_suppression_list_from_esp()

for email in suppressed_emails:
    add_email_filter(email, reason="Suppressed in ESP")

Handling complaints

When someone reports your email as spam:

// Webhook handler for spam complaints
app.post('/webhooks/spam-complaint', async (req, res) => {
  const { email } = req.body;
  
  await truemail.addFilter({
    filter_type: 'email',
    value: email,
    reason: `Spam complaint on ${new Date().toISOString()}`
  });
  
  res.sendStatus(200);
});

Permanent unsubscribes

For users who want complete removal:

def handle_permanent_unsubscribe(email)
  # Remove from your lists
  Subscriber.where(email: email).destroy_all
  
  # Add to TrueMail blocklist
  TruemailClient.add_filter(
    filter_type: 'email',
    value: email,
    reason: 'Permanent unsubscribe request'
  )
end

Best Practices

1. Document your reasons

Always add a reason when creating filters:

Good:  "Spam complaint 2024-01-15 - Campaign #123"
Bad:   "" (empty)

2. Consider domain filters first

If you’re blocking multiple addresses from the same domain, a domain filter is more efficient:

Instead of:
- [email protected]
- [email protected]
- [email protected]

Use:
- spam-domain.com (domain filter)

3. Keep your list current

Review email filters periodically. Some might be outdated or no longer relevant.

4. Sync with other systems

If you have blocklists in multiple places (CRM, email platform, etc.), keep them in sync to maintain consistency.

Related

• Domain Filters - Block entire domains
• Filters Overview - How filters work
• Filters API - Manage filters via API