# Email Notifications

Deliver Capsule policy-violation notifications as email, so your team sees AI agent and shadow-AI signals in the inbox they already watch.

## Overview

When a policy you've linked is violated, Capsule sends an email to an address of your choice. The email summarizes the violation - severity, policy, affected entity, and time - with a **View in Capsule** link back into the portal.

The address can be a personal inbox or a distribution / security-group address. Capsule sends one message to the address you configure; it doesn't distinguish between the two, so fanning a group address out to its members is your mail platform's job.

You can add more than one email channel and link each to different policies, so (for example) high-severity violations go to your on-call distribution list while everything else goes to a shared triage inbox.

```
Capsule policy violation
  → Capsule sends an email via Capsule's email provider
  → email arrives at the address you configured
```

## Sender identity

Capsule notification emails come from:

```
Capsule Security <sender@mail.capsulesecurity.io>
```

To keep delivery reliable, **allow-list this sender** (add it to your safe-senders list, or ask your mail administrator to allow-list it at the gateway). Allow-listing the `mail.capsulesecurity.io` sending domain covers it. Security-alert email that lands in spam is email your team won't act on.

## Prerequisites

Before you begin, ensure you have:

- An **email address** where you want Capsule notifications to arrive (a personal inbox, or a distribution / security-group address)
- A **Capsule Security** account with admin access


## 1. Configure the channel in Capsule

1. Log in to the **Capsule Security** portal.
2. Go to **Settings → Notifications**.
3. Click **Add channel** and choose **Email**.
4. Enter a **display name** (how this channel appears in Capsule) and the **email address** to notify.
5. Click **Save & Test**.


### What the test actually proves

**Save & Test** sends a real test email to the address you entered. The test email is clearly labeled as a test - its subject is `[Capsule] Test notification` and its body confirms the channel is configured correctly.

> A passing test means Capsule's email provider **accepted** the message for delivery - not that it reached the inbox. After the test succeeds, confirm the email actually arrived. If nothing shows up within a minute, check the **spam / junk** folder, then double-check the **spelling of the address**, then confirm the sender is **allow-listed** (see [Sender identity](#sender-identity)).


## 2. What the emails contain

A notification email includes:

- **Severity** - Critical, High, Medium, or Low, shown prominently as a colored banner
- **Policy** - the policy that was violated
- **Entity** - the affected agent or entity
- **Category** - the kind of signal that triggered the notification
- **Time** - when the violation occurred (in UTC)
- A **View in Capsule** button that deep-links to the violation in the portal


A test email is clearly marked as a test and omits the severity banner and the View in Capsule button, so it's never mistaken for a real alert.

### Footer: Manage in Capsule, not unsubscribe

Notification emails carry a **Manage in Capsule** link to **Settings → Notifications** - there is deliberately **no unsubscribe link**. These are team destinations, often shared inboxes, so turning a channel off is an admin action in Capsule, not a one-click link that any single recipient could use to silence the whole team's security alerts.

## 3. Link the channel to policies

An email channel only receives notifications for the policies you link to it. On the **policy edit** screen, add the email channel to the policy's notification channels - the same way you link any other notification destination. Link as many policies as you want; a channel with no linked policies stays idle.

## Rate limits

To protect deliverability, Capsule caps how many emails it sends - **per destination each hour** and **per tenant each month**. When a cap is reached, further emails to that destination (or across the tenant) are **suppressed** until the window resets, at which point sending resumes automatically. Suppressed sends are recorded in Capsule's delivery log, so nothing is lost silently.

The defaults are **20 emails per hour per destination** and **1,000 emails per month per tenant**. These are defaults, not fixed limits - they're configurable for your deployment.

## Troubleshooting

**Test passes, but no email arrives.** A passing test means Capsule's email provider accepted the message, not that it was delivered. Check the recipient's **spam / junk** folder, confirm there's **no typo** in the address, and make sure `sender@mail.capsulesecurity.io` is **allow-listed** so your mail gateway doesn't quarantine it (see [Sender identity](#sender-identity)).

**The channel row shows an Error state.** Capsule flips a channel to **Error** when delivery to that address is failing - typically because the mailbox has been removed or the receiving server is rejecting the mail. **Edit** the channel and fix the address (or point it at a working mailbox). A successful delivery clears the error and returns the channel to Active.

**Emails stopped, and the delivery log shows "Sending paused" / suppressed sends.** This is rate limiting - a per-destination hourly or per-tenant monthly cap was reached (see [Rate limits](#rate-limits)). No action is needed; sending resumes automatically when the window resets.

## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, the affected channel's display name, and any error shown on the channel row