Skip to content
InboxEagle Documentation
Start free trial

AWS SES integration

InboxEagle’s Bot Finder feature relies on Amazon SES event data to detect bot opens and clicks. The AWS SES integration sets up the infrastructure — an SNS topic, SQS queue, and IAM role — in your AWS account using a CloudFormation stack, then gives InboxEagle read access to your event stream so the bot detection pipeline can process events.

Prerequisites

Section titled “Prerequisites”

Before starting the SES integration:

  • AWS account with access to SES, IAM, SNS, SQS, and CloudFormation
  • Amazon SES configured and out of the sandbox (production access granted) for at least one sending domain or email identity
  • InboxEagle account with an active subscription (Bot Finder requires Basic or above)
  • ExternalId from your InboxEagle settings — a unique identifier (8–64 characters) used for secure cross-account role assumption

Architecture overview

Section titled “Architecture overview”

The integration uses a cross-account IAM role pattern. Here is what the CloudFormation stack creates:

Your AWS account
  ├─ SNS Topic          ← SES sends open/click/bounce/complaint events here
  ├─ SQS Queue          ← SNS fans out to this queue (buffered for InboxEagle to poll)
  ├─ SQS Dead Letter Queue (DLQ) ← Captures failed events after 5 retries
  ├─ IAM Role           ← InboxEagle assumes this role to read from SQS and SES
  └─ SES Configuration Set ← Apply to your sending identity to route events

InboxEagle’s backend (account ID: 051826705850) assumes the IAM role in your account using the ExternalId as a security guard — preventing confused-deputy attacks.

Step-by-step setup

Section titled “Step-by-step setup”

  1. Deploy the CloudFormation stack

    In the InboxEagle app, go to Integrations → AWS SES and click Launch CloudFormation. This opens the InboxEagle Bot Finder stack template in the AWS Console.

    In the stack wizard:

    • Stack name — Leave as InboxEagle-BotFinder or change to your preference
    • Parameters → ExternalId — Paste the ExternalId from your InboxEagle settings
    • Capabilities — Check the box to acknowledge IAM resource creation

    Click Create stack and wait for status CREATE_COMPLETE (typically 1–2 minutes).

  2. Copy the IAM Role ARN

    In the AWS CloudFormation console, open your newly created stack and click the Outputs tab. Copy the value of InboxEagleRoleArn:

    arn:aws:iam::123456789012:role/inboxeagle-role-abc123-us-east-1

    The role ARN encodes your AWS account ID, your ExternalId (abc123), and your AWS region (us-east-1). InboxEagle extracts these automatically when you paste the ARN.

  3. Validate the ARN in InboxEagle

    Back in the InboxEagle app, paste the role ARN into the IAM Role ARN field and click Validate ARN. InboxEagle will:

    • Assume the role using STS (AssumeRole with your ExternalId)
    • Discover SQS queues, SNS topics, and SES configuration sets in your account
    • Confirm read permissions are working

    If validation fails, see troubleshooting below.

  4. Select your SES Configuration Set

    After ARN validation, InboxEagle lists the SES configuration sets discovered in your account. Select the configuration set that is attached to your sending identity — usually ie-config-<ExternalId> created by the stack.

    Click Save to complete the configuration.

  5. Apply the configuration set to your sending identity

    The stack creates a configuration set pre-wired for open, click, delivery, bounce, and complaint event types. Apply it to the SES identity you send from:

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

    Replace YOUR_EXTERNAL_ID with the value from your InboxEagle settings.

CloudFormation stack outputs

Section titled “CloudFormation stack outputs”
Output keyExample valuePurpose
InboxEagleRoleArnarn:aws:iam::123456789012:role/inboxeagle-role-abc123-us-east-1Paste into InboxEagle app (Step 3)
SESConfigurationSetNameie-config-abc123Apply to your SES sending identity (Step 5)
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-abc123Only needed for SNS delivery method
DLQArnarn:aws:sqs:us-east-1:123456789012/ie-dlq-abc123Monitor for failed events

Event delivery methods

Section titled “Event delivery methods”

After the initial SES setup, you can configure how Bot Finder delivers analyzed events back to you:

MethodDescriptionBest for
SQS (default)InboxEagle polls your SQS queueMost setups; no extra config needed
SNSInboxEagle publishes analyzed results to an SNS topic you ownFan-out to multiple consumers
S3Analyzed events are uploaded as CSV to an S3 bucketBatch analysis and data warehousing
WebhookInboxEagle POSTs analyzed events to your HTTPS endpointReal-time integration with your systems

To change the delivery method, go to Integrations → AWS SES → Settings in the InboxEagle app.

IAM permissions created by the stack

Section titled “IAM permissions created by the stack”

The CloudFormation stack creates an IAM role with these permissions (least-privilege):

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes"],
      "Resource": "<SQS Queue ARN>"
    },
    {
      "Effect": "Allow",
      "Action": ["ses:ListConfigurationSets", "ses:GetConfigurationSet"],
      "Resource": "*"
    }
  ]
}

InboxEagle can only read from your SQS queue and list SES configuration sets. It cannot send email, access your contacts, or write to any AWS resources in your account.

Troubleshooting ARN validation

Section titled “Troubleshooting ARN validation”

“Invalid ARN format” — The ARN must follow the pattern arn:aws:iam::<account-id>:role/<role-name>. Check for extra spaces or line breaks when copying from the AWS console.

“Unable to assume role” — The ExternalId in the role’s trust policy does not match the ExternalId in your InboxEagle settings. Re-deploy the stack with the correct ExternalId, or contact support.

“No SQS queues found” — The stack may not have been created in the same region as your SES configuration. Confirm the stack region matches your SES region, then re-validate.

“No SES configuration sets found” — The IAM role does not have ses:ListConfigurationSets permission. Check that the stack created the role successfully (CloudFormation → Events tab for errors).

For additional help, see Bot Finder troubleshooting.

Disconnecting AWS SES

Section titled “Disconnecting AWS SES”

To disconnect the integration:

  1. Go to Integrations → AWS SES → Settings in the InboxEagle app
  2. Click Disconnect
  3. Optionally, delete the CloudFormation stack in your AWS console to remove all created resources

After disconnecting, InboxEagle will stop polling your SQS queue. Events that were already processed remain in your Bot Finder history.

Next steps

Section titled “Next steps”
Set up AWS SES integration →