Bot Signatures

Overview

Bot signatures let you identify open and click-tracking events that weren't generated by a real recipient. Email security gateways, inbox-preview services, AI crawlers, and mailbox providers that proxy images (such as Apple Private Relay or Google Image Proxy) all fetch tracking pixels and follow links automatically. Without a way to tell them apart from real recipients, those requests show up as opens and clicks and inflate your engagement metrics.

When a tracking request matches a bot signature, unMTA labels the event with a bot field identifying the kind of automation that produced it — but still records it. See Event Labeling below for how this shows up on Open and Click webhook payloads.

Bot signatures come in two layers, merged at match time:

Custom rules are always additive. Disables remove matching entries from the built-in and default layers.

Match Types

Every signature — default or custom — has a type that determines how the request is matched:

A request is labeled if any signature matches. User-Agent matching runs first, then exact-IP lookups, then CIDR ranges — the first hit wins and its source becomes the event's bot label.

Default Signatures

unMTA ships a curated set of default signatures covering common sources of bot traffic. The list is updated over time as new bots, proxies, and scanners appear.

What's Covered

The dataset evolves over time as new bots appear. Categories currently covered include:

• Mailbox-provider image proxies — Apple Private Relay, Google Image Proxy, Yahoo Mail Proxy
• Link-preview services — Microsoft BingPreview, Teams URL Preview
• Email security gateways — Proofpoint, Mimecast, Barracuda, Symantec, FireEye, MessageLabs, and others
• AI and LLM crawlers — ChatGPT, Anthropic ClaudeBot, OpenAI GPTBot, Amazonbot
• Generic HTTP clients — curl, wget, python-requests, Go-http-client, HeadlessChrome, and similar automation tooling
• Apple Private Relay egress ranges — the CIDRs published by Apple
• Other provider egress ranges — added as vendors publish authoritative lists (e.g. Microsoft Defender/SafeLinks, additional security vendors)

Disabling a Default Per Cluster

Defaults apply to every cluster automatically. If one of them is filtering real engagement for your audience, you can disable it for a specific cluster without affecting any other cluster.

1. Navigate to the Bot Signatures page from the sidebar
2. Open the Defaults tab
3. Use the source filter or search box to find the signature
4. Toggle the switch at the end of the row to disable it

Disabling is per-cluster — the same default can be on for one cluster and off for another. You can re-enable it at any time by toggling the switch back on.

Custom Signatures

Custom signatures are yours to manage. Use them to:

• Flag events from an internal security scanner or link-checker you control
• Cover a bot that unMTA's defaults don't handle yet
• Tag a specific range of IPs that is consistently generating non-human opens

Adding a Custom Rule

1. Navigate to the Bot Signatures page
2. Click Add custom rule
3. Choose the match type (User Agent, IP Address, or IP CIDR)
4. Enter the pattern
5. Optionally, enter a label to help you remember what the rule is for
6. Click Save

Pattern Requirements

Deleting a Custom Rule

1. Open the Custom rules tab
2. Click the menu button on the rule and select Delete
3. Confirm

Deleting is immediate. The rule is removed from the cluster and MTAs stop matching on it once the next config sync completes (see below).

Prefetch Detection

In addition to signature matching, unMTA flags pixel or click requests that arrive implausibly soon after the message was sent.

If the delta is under 5 seconds and no user-agent or IP signature matched, the event is labeled bot: "prefetch". This catches link-scanners and preview fetchers that don't match any known signature — a real recipient opening an email within 5 seconds of delivery is almost always automation.

More specific signature hits always win over prefetch, so a fast Apple Mail Privacy Protection load still labels as apple.

Event Labeling

When a signature (or prefetch detection) matches, unMTA adds a nested bot object to the Open or Click webhook payload:

{
  "type": "Open",
  "id": "...",
  "recipient": "...",
  "bot": { "kind": "proxy", "source": "apple" }
}

Human traffic emits the event without the bot field, so treat the field's presence — not its truthiness — as the signal.

bot.kind — the field you bucket on

A stable, two-value enum that tells you whether the hit was a mailbox-provider proxy standing in for a real recipient, or automation with no human behind it:

This is the field to filter on. It's stable against future change — if Google were to launch a prefetcher tomorrow, the corresponding signature would ship with kind: "automation" and every dashboard that buckets on kind would be automatically correct without any rule rewrites.

bot.source — diagnostic detail

The fine-grained identifier for the specific provider or category that matched. Use it for slicing dashboards ("how much of our automation traffic is AI crawlers vs Proofpoint?"), not for bucketing human-vs-bot. Current source values include:

The source ↔ kind relationship is set per-signature, not fixed globally — a future microsoft signature could ship with either kind depending on what it matches.

API Reference

For programmatic management of bot signatures, see the Bot Signatures API documentation.