Skip to content
InboxEagle Documentation
Start free trial

Bot Finder setup

Bot Finder (powered by BotDetect) filters bot opens and clicks from your Amazon SES engagement data so your deliverability and engagement decisions are based on real subscriber behavior. It captures SES events (opens, clicks, bounces, complaints), runs a multi-layer bot-detection analysis (Lens pipeline), and delivers cleaned signals for InboxEagle.

What Bot Finder does

Section titled “What Bot Finder does”
  • Captures SES events — Opens, clicks, bounces, and complaints from Amazon SES.
  • Routes via SNS and SQS — Events are sent to a topic and queue in your AWS account (created by the CloudFormation stack).
  • Runs bot detection — A backend pipeline (Lens) classifies each event as bot, suspicious, or human using timing, IP, user agent, and other signals (e.g. privacy proxies, security scanners).
  • Delivers clean signal — Results are delivered via webhook, SNS, or S3 so InboxEagle (or your own systems) can use engagement data without bot inflation.

Why use it

Section titled “Why use it”

Without Bot Finder, open and click counts can be inflated by:

  • Privacy proxies — Apple Mail Privacy Protection, Gmail Image Proxy, Yahoo Mail proxy, Outlook prefetch (they load images automatically).
  • Security scanners — Corporate gateways (e.g. Proofpoint, Mimecast, Microsoft Defender) that scan links.
  • Other bots — Known bot user agents, cloud IPs, honeypot clicks, etc.

Bot Finder identifies these so you can exclude them from engagement metrics and base deliverability and content decisions on real subscribers.

Prerequisites

Section titled “Prerequisites”

Setup flow (in the app)

Section titled “Setup flow (in the app)”

In the InboxEagle app, open Bot Finder from the sidebar (or go to the Bot Finder integration page). The onboarding wizard has four steps.

  1. Intro — launch CloudFormation

    Read what Bot Finder does and the prerequisites, then click Launch CloudFormation to open the InboxEagle Bot Finder CloudFormation template in the AWS Console (stack name e.g. InboxEagle-Bot Finder).

    • Confirm the template URL points to the InboxEagle Bot Finder template.
    • In Parameters, enter the ExternalId provided by InboxEagle.
    • In Capabilities, acknowledge that the template will create IAM resources.
    • Create the stack and wait for CREATE_COMPLETE.

    Click Continue in the app to go to Step 2.

  2. Enter IAM Role ARN

    After the stack is created, open the Outputs tab of your stack in the AWS CloudFormation console.

    • Copy the InboxEagleRoleArn (e.g. arn:aws:iam::123456789012:role/inboxeagle-role-abc123-us-east-1).
    • Paste the ARN into the IAM Role ARN field in the app.
    • Click Validate ARN.

    If validation succeeds, you proceed to Step 3.

  3. Select SES Configuration Set

    The app lists the SES Configuration Sets available in your account (discovered via the role you validated).

    • Choose the configuration set applied to your sending identity so events flow to Bot Finder. Typically this is the set created by the stack (e.g. ie-config-<ExternalId>).
    • Click Save Configuration. The app stores your role ARN and selected configuration set.

  4. Complete Done

    You see Bot Finder Connected! The bot detection pipeline is now active for your account.

    Click View Dashboard to open the Bot Finder dashboard and monitor status, metrics, and reports.

CloudFormation stack outputs

Section titled “CloudFormation stack outputs”

After deploying the stack, note these values from the Outputs tab:

OutputExampleYou need it for
InboxEagleRoleArnarn:aws:iam::123456789012:role/inboxeagle-role-abc123-us-east-1Paste in the app at Step 2 (Enter IAM Role ARN)
SESConfigurationSetNameie-config-abc123Apply to your SES identity (below); also select this in the app at Step 3
SQSQueueUrlhttps://sqs.us-east-1.amazonaws.com/123456789012/ie-sqs-abc123Verify events are flowing (optional)
SNSWriteTopicArnarn:aws:sns:us-east-1:123456789012:ie-sns-write-abc123SNS delivery method only (if configured)

InboxEagle derives externalId and awsRegion from the role ARN pattern inboxeagle-role-{externalId}-{region}, so you only need to share the full ARN in the app.

Apply the configuration set to your sending identity

Section titled “Apply the configuration set to your sending identity”

The stack creates a configuration set (e.g. ie-config-{ExternalId}) pre-wired for open, click, delivery, bounce, and complaint events. Apply it to the SES identity you send from so events flow to Bot Finder.

Option A — Per identity (recommended):

Terminal window
aws sesv2 put-email-identity-configuration-set-attributes \
  --email-identity your-domain.com \
  --configuration-set-name ie-config-YOUR_EXTERNAL_ID

Option B — Account-level default:

Terminal window
aws sesv2 put-account-sending-attributes \
  --default-configuration-set ie-config-YOUR_EXTERNAL_ID

After this, SES will send events to the SNS topic created by the stack; the Resource Sync worker (runs every 5 minutes) will discover your SQS queue and configuration set, and ingestion will begin.

Section titled “Optional: Honeypot links for high-confidence bot detection”

Bot Finder’s passive detection rules run automatically. For highest-confidence bot detection, you can add a honeypot link to your email templates.

  • A honeypot link is a hidden <a> tag that is invisible to humans but often clicked by bots that scan all links.
  • Add an invisible link whose URL includes the query parameter ?_ie=hp (or &_ie=hp if appending to an existing query string). The link must point to a real, trackable URL so SES records the click.
  • Example (hidden with CSS): <a href="https://your-domain.com/track?_ie=hp" style="display:none;">.</a> Or use zero-size font or off-screen positioning so only bots interact with it.
  • Any click on such a link receives a high bot score (e.g. 90). Do not use _ie=hp on visible, intentional links.

Next steps

Section titled “Next steps”