IP Filters

IP filters block validation requests that originate from specific IP addresses. This is useful for stopping abuse, blocking bot traffic, or preventing unauthorized access to your validation quota.

Premium Feature: IP filtering is available on Premium plans only.

How IP Filters Differ

Unlike email and domain filters that block specific addresses, IP filters block the source of the request:

IP filters are primarily useful for API requests, where you can identify the source IP.

When to Use IP Filters

Block abusive IPs

If someone is making unauthorized requests using a compromised or shared key:

Block: 192.168.1.100
Reason: Unauthorized API usage detected

Stop bot traffic

Block known bot or scraper IPs:

Block: 203.0.113.50
Reason: Bot traffic - automated signups

Restrict access by location

If you only want requests from certain regions, block unwanted IP ranges.

Complement API key restrictions

Use IP filters as an additional layer on top of API key IP restrictions.

Adding an IP Filter

From the dashboard

1. Go to Settings → Filters
2. Click Add Filter
3. Select IP Address as the filter type
4. Enter the IP address to block
5. (Optional) Add a reason
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": "ip_address",
      "value": "192.168.1.100",
      "reason": "Blocked due to suspicious activity"
    }
  }'

IP Filter Rules

Format requirements

• Must be a valid IPv4 address
• Standard dotted decimal notation
• CIDR notation is not currently supported

Valid examples

192.168.1.100
10.0.0.1
203.0.113.42

Invalid examples

192.168.1.0/24       # CIDR not supported
192.168.1            # Incomplete address
256.1.1.1            # Invalid octets
2001:db8::1          # IPv6 not supported

How IP Filters Work

When an API request arrives:

1. TrueMail identifies the source IP
2. Checks if it matches any IP filter
3. If matched, the request is rejected with a 403 error
4. No validation is performed

API response when blocked

{
  "error": "IP address not allowed"
}

Note: The response is the same whether blocked by an IP filter or API key IP restriction, for security reasons.

Viewing IP Filters

From the dashboard

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

Via API

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

Response:

{
  "filters": [
    {
      "id": 789,
      "filter_type": "ip_address",
      "value": "192.168.1.100",
      "reason": "Suspicious activity",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Removing IP Filters

From the dashboard

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

Via API

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

IP Filters vs API Key Restrictions

Both features deal with IP addresses, but they work differently:

When to use each

Use IP Filters when:

• Blocking known bad actors
• Stopping abuse regardless of which key is used
• Creating a global blocklist

Use API Key IP Restrictions when:

• Securing a specific key to known servers
• Different keys need different IP access
• Implementing least-privilege access

Using both together

For maximum security, combine both:

1. API Key restrictions: Only allow your server IPs
2. IP Filters: Block any IPs you’ve identified as problematic

Common Use Cases

Block after detecting abuse

When you see unusual activity in your logs:

def handle_abuse_detection(ip_address):
    # Add to IP blocklist
    add_ip_filter(ip_address, f"Abuse detected {datetime.now()}")
    
    # Also revoke any compromised API keys
    revoke_compromised_keys()
    
    # Alert your team
    send_alert(f"Blocked IP: {ip_address}")

Integrate with security tools

Connect your WAF or security monitoring to automatically block IPs:

// Webhook from security tool
app.post('/webhooks/security-alert', async (req, res) => {
  const { ip, reason } = req.body;
  
  await truemail.addFilter({
    filter_type: 'ip_address',
    value: ip,
    reason: `Security alert: ${reason}`
  });
  
  res.sendStatus(200);
});

Block regions (manual)

If you want to restrict access by region, look up IP ranges for that region and add them:

# Block a specific datacenter range known for abuse
curl -X POST https://api.truemail.app/v1/filters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filter": {
      "filter_type": "ip_address",
      "value": "198.51.100.1",
      "reason": "Datacenter IP - likely bot traffic"
    }
  }'

Premium Requirement

IP filtering requires a Premium subscription. If you try to create an IP filter on a Starter plan:

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

Upgrade to Premium →

Best Practices

1. Monitor before blocking

Before adding IP filters, review your API usage logs to confirm suspicious activity.

2. Document your reasons

Always add context:

IP: 192.168.1.100
Reason: "Abuse detected 2024-01-15 - 10,000 requests in 5 minutes"

3. Review periodically

IPs can be reassigned. An IP you blocked might now belong to a legitimate user.

4. Use with other security measures

IP filters are one layer. Also use:

• API key restrictions
• Rate limiting (built-in)
• Monitoring and alerting

5. Don’t over-block

Be careful not to block legitimate traffic. When in doubt, monitor first.

Related

• IP Restrictions - Secure API keys with IP allowlists
• Filters Overview - How all filters work
• API Overview - Rate limits and security