When connecting your AWS account to SendOps, most issues fall into a few well-known categories. This page walks through each one with the likely cause and how to fix it.

## AWS Status Badge

The **AWS Status Badge** in the sidebar header shows the current state of your AWS connection at a glance. Clicking it opens a popover with details such as region, account ID, and last validated time.

| Badge State | Meaning |
|---|---|
| **Not Connected** | No AWS account has been linked yet. Click to start onboarding. |
| **Connecting...** | The connection has been saved but not yet validated. |
| **Validating...** | A validation job is currently running (AWS connection or stack validation). |
| **Connection Error** | The most recent validation failed. Click to open onboarding and fix the issue. |
| **Update Available** | Your CloudFormation stack is running an older template version. Click to update. |
| **Sandbox** | Connected successfully, but your SES account is in sandbox mode. |
| **AWS Connected** | Connected and validated with production SES access. |

## IAM role errors

**Symptom:** The AWS connection step in onboarding fails with one of these messages:

- "Access denied — ensure the IAM role ARN is correct and the Sesmail account is included in the trust policy with the correct External ID"
- "IAM role not found — verify the role ARN and that it exists in your AWS account"
- "Role trust policy must include the external ID condition"

**Cause:** SendOps calls `sts:AssumeRole` to verify your IAM role during onboarding. The most common mistakes are:

- The **IAM Role ARN** you entered does not match an existing role in your AWS account.
- The **trust policy** on the role does not include the SendOps AWS Account ID in the `Principal` field.
- The **External ID** in the trust policy's `Condition` block does not match the value shown in your onboarding page.
- The trust policy is missing the `sts:ExternalId` condition entirely.

**Fix:**

If you used the **Launch Stack** button during onboarding, the CloudFormation template creates the `SendOpsRole` automatically with the correct trust policy. If the role already exists from a previous attempt, delete the old CloudFormation stack first and re-launch.

If you set up the role manually:

1. Open your IAM role in the [AWS IAM Console](https://console.aws.amazon.com/iam/).
2. Click the **Trust relationships** tab and then **Edit trust policy**.
3. Verify the `Principal.AWS` value matches the SendOps Account ID shown on your onboarding page.
4. Verify the `sts:ExternalId` condition value matches the External ID shown on the same page. Copy and paste it directly to avoid typos.
5. Save and retry the connection in SendOps.


  Every SendOps organization gets a unique External ID, generated when onboarding is initialized. If you are setting up multiple organizations, each one has its own External ID and needs its own IAM role and trust policy. See [AWS Integration](/aws-setup/connecting-aws) for the full setup walkthrough.


## CloudFormation stack failed

**Symptom:** The CloudFormation stack created during onboarding shows a status of `CREATE_FAILED` or `ROLLBACK_COMPLETE` in the AWS Console.

**Cause:** Common reasons include:

- **Insufficient permissions** — the IAM user or role you used to launch the stack does not have permission to create the required resources (IAM roles, SES configuration sets, EventBridge rules, EventBridge connections, API destinations).
- **Resource name conflict** — a resource with the same name already exists in that region (e.g., an IAM role named `SendOpsRole`, a configuration set named `sendops-events`, or an EventBridge rule named `sendops-ses-events`).
- **Service limit reached** — you have hit an AWS account limit for EventBridge rules, API destinations, or SES configuration sets.

**Fix:**

1. Open the [CloudFormation Console](https://console.aws.amazon.com/cloudformation/) in the region where you launched the stack.
2. Click the failed stack and go to the **Events** tab.
3. Look for the first event with a `CREATE_FAILED` status — this is usually the root cause. The **Status reason** column explains the error.
4. Fix the underlying issue (grant permissions, delete the conflicting resource, or request a limit increase).
5. Delete the failed stack and re-launch it from the SendOps onboarding page.

The stack creates these resources: `SendOpsRole` (IAM role), `SendOpsConfigSet` (SES configuration set named `sendops-events`), `SendOpsEventDestination` (EventBridge event destination on the config set), `SendOpsConnection` (EventBridge connection with API key auth), `SendOpsApiDestination` (API destination at 300 invocations/sec), `SendOpsEventBridgeRole` (IAM role for EventBridge), and `SendOpsEventRule` (EventBridge rule named `sendops-ses-events`). See [AWS Integration](/aws-setup/connecting-aws) for a detailed breakdown.

## Stack validation errors

**Symptom:** You click **Run Validation** in the Connection Validation phase of onboarding, and one or more checks fail.

**Cause:** SendOps runs a background validation job that verifies your CloudFormation stack resources are correctly deployed. The job checks seven items:

1. **SES Configuration Set** — confirms the `sendops-events` configuration set exists in your selected region.
2. **EventBridge Rule** — confirms the `sendops-ses-events` rule exists and is enabled.
3. **Webhook Target** — confirms the EventBridge rule has a target pointing to the SendOps API destination (webhook endpoint).
4. **Channel Management** — probes that your IAM role has `ses:ListConfigurationSets` permission for creating and managing channels.
5. **Channel Settings** — probes that your IAM role has `ses:PutConfigurationSetDeliveryOptions` permission for syncing channel settings.
6. **Email Templates** — probes that your IAM role has `ses:ListEmailTemplates` permission for template management.
7. **Contact Lists** — probes that your IAM role has `ses:ListContactLists` permission for provisioning and managing contact lists.

The validation also reads your SES account status and reports whether sending is enabled, whether you are in sandbox mode, your sending limits, and how many verified identities exist.

**Fix:**

- If the configuration set or EventBridge rule is missing, the CloudFormation stack likely did not deploy successfully. Check the [CloudFormation Console](https://console.aws.amazon.com/cloudformation/) for stack status, delete any failed stacks, and re-launch from onboarding.
- If the webhook target is missing, the stack may have partially deployed. Delete and re-create the stack.
- If permission probes fail (Channel Management, Channel Settings, Email Templates, or Contact Lists), your CloudFormation stack may be running an older template version. The validation page will show a **stack update card** with a link to update your stack to the latest version. After updating, click **Re-validate**.
- If SES sending is disabled or your account is in sandbox mode, these are AWS-side settings. Visit the [AWS SES Console](https://console.aws.amazon.com/ses/) to request production access.


  Stack validation does not run automatically. You must click **Run Validation** (or **Re-validate** after making changes) to trigger the check. The validation job runs in the background and the page polls for results every 2 seconds.


## EventBridge not delivering events

**Symptom:** Your AWS account is connected and stack validation passes, but SendOps is not receiving email events (the Messages Dashboard stays empty).

**Cause:** SES events flow through EventBridge to SendOps via an API Destination (webhook). Check these in order:

1. **EventBridge rule is disabled** — open the [EventBridge Console](https://console.aws.amazon.com/events/) and verify the `sendops-ses-events` rule is in an **ENABLED** state.
2. **API destination target is missing** — click the rule and check that it has a target pointing to the `sendops-ingest` API destination. If the target is missing, the webhook endpoint is not connected.
3. **SES configuration set not assigned** — emails must be sent using a configuration set that has an EventBridge event destination for events to fire. The bootstrap configuration set created by the stack is `sendops-events`. Channels create their own configuration sets (named `sesmail-<slug>`) with EventBridge destinations auto-configured.
4. **Wrong region** — the EventBridge rule only captures events from the region it is deployed in. If you send email from a different region than where the stack is deployed, events will not be captured.

**Fix:**

- Re-enable the rule if it was disabled.
- If the API destination target is missing, delete and re-create the CloudFormation stack from onboarding.
- Verify your sending setup uses a configuration set with an EventBridge event destination. See [Understanding Channels](/channels/understanding-channels) for how channels map to configuration sets.
- Deploy the CloudFormation stack in every region from which you send email. See [Supported AWS Regions](/aws-setup/supported-regions).


  EventBridge only captures events generated after the rule is active. If the rule was disabled or misconfigured for a period, events from that window are lost and cannot be backfilled.


## Template version mismatch

**Symptom:** The AWS Status Badge shows **Update Available**, or the Connection Validation page displays a stack update card after re-validating.

**Cause:** SendOps periodically adds new features that require additional IAM permissions or resources in the CloudFormation stack. When the deployed stack version is older than the current template version, permission probes may fail and new features (such as channel management or template sync) will not work.

**Fix:**

1. Open the stack update link shown on the validation page or in the AWS Status Badge popover. This opens the CloudFormation Console with the latest template pre-filled.
2. Follow the CloudFormation update wizard to apply the changes.
3. Return to SendOps and click **Re-validate** to confirm the update was successful.

## Still stuck?

If none of the above resolves your issue:

- Check the [AWS SES Console](https://console.aws.amazon.com/ses/) directly to confirm your SES account is active and not under review or on probation.
- Review [IAM Permissions Explained](/aws-setup/iam-permissions) to verify your role has all required permissions.
- Contact [support@sendops.dev](mailto:support@sendops.dev) with your organization name and the error message you see in the dashboard.