> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Email addresses

> Give your agent its own inbound email address — emails arrive as conversations.

Every address you create is a dedicated mailbox on the `mail.agentheya.com` domain. When an email arrives at that address, Agentheya starts a new conversation and the agent processes the email as the first message.

You can have multiple inbound addresses per agent — for example, a `support@` address and a `billing@` address with different context instructions for each.

## Creating an address

1. Open your agent and go to **Email Addresses** in the sidebar.
2. Click **Add Email Address**.
3. Give the address a name (shown only to you), then enter the local part (the text before `@`) — for example, `support` gives you `support@mail.agentheya.com`.
4. Click **Save** — the address starts receiving mail after the save. The card shows a hint reminding you the address is *reserved locally* until you save.

The full address is shown in the card after saving. Click the copy icon next to it to copy it to your clipboard.

## Per-address settings

Each address card has an **ON / OFF** toggle (auto-saves) and the following fields:

| Setting                | What it does                                                                                                                                                                                                                                             |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sender Allowlist**   | When enabled, only accept emails from listed addresses or domains. One pattern per line. Use `user@example.com` for a single sender, `@example.com` for an exact domain, or `*@trusted.org` for a wildcard. Leave the section off to accept from anyone. |
| **Require DMARC Pass** | Only shown when the allowlist is on. When enabled, emails that fail DMARC authentication are rejected even if the sender matches the allowlist.                                                                                                          |
| **Context**            | Extra instructions the agent reads when processing emails arriving at this address — e.g. "These are support emails. The sender is a paying customer." Use this to give the agent different behaviour per address.                                       |
| **Auto-reply**         | When on, the agent actually sends a reply once an email clears every check above. When off, the email is stored in the [Inbox](/sidebar-menu/inbox) for you to handle rather than getting an automatic reply.                                            |
| **Notes**              | Private operator notes, never seen by the LLM.                                                                                                                                                                                                           |

You can re-order addresses by dragging the cards. Order persists on save.

## Content filters

Each address card has a collapsible **Content Filters** section for rejecting inbound email by its contents. Filters run *after* the authentication pipeline (DMARC, Sender Allowlist) and *before* the agent — or the classifier — ever sees the message.

| Filter                       | What it does                                                                                                                                    |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sender domain blocklist**  | One address or domain pattern per line. `@evil.com` blocks the whole domain. Complements the Sender Allowlist (the allowlist is checked first). |
| **Subject — block keywords** | Reject if the subject contains any of these (case-insensitive substring, one per line).                                                         |
| **Subject — allow keywords** | When set, *only* accept emails whose subject contains at least one of these.                                                                    |
| **Body — block keywords**    | Reject if the body contains any of these.                                                                                                       |
| **Body — allow keywords**    | When set, *only* accept emails whose body contains at least one of these.                                                                       |
| **Max message size (MB)**    | Reject if the combined text + HTML body exceeds this. `0` means no limit.                                                                       |
| **Attachment policy**        | **Any**, **Forbid** (reject anything with an attachment), or **Require** (reject anything without one).                                         |

Content filters are saved with **Save Changes**, not auto-saved.

## Spend budget

*(Owner-only.)* Each address has an optional **Spend budget** — a **Spend cap (credits)** and a **Budget period** (**Daily**, **Weekly**, or **Monthly**). Once the address's AI spend reaches the cap, auto-replies pause until the period resets (UTC). Leave the cap at `0` for no limit. Use it to keep a single address from draining credits if it gets hit hard.

## Connect your own mailbox (Gmail / Outlook)

By default the agent sends from the platform address shown on each card. To have it send **as your real Gmail or Microsoft 365 identity** — and to let it search, read, draft, label, and organise your actual inbox — connect a mailbox under **Sending identity** at the top of the page.

* **Connect / Disconnect** Gmail or Outlook with one click (a standard OAuth sign-in). Tokens are stored encrypted and refreshed automatically.
* Once connected, the agent gains the `gmail_*` / `outlook_*` tools — search, read, send-as-you, draft, and label/organise. See [Tools](/sidebar-menu/tools).
* The connected account is **yours** (the owner's). Each **subscriber** can connect their *own* mailbox from their dashboard; the agent always acts on the mailbox of whoever it is talking to — never the owner's for a subscriber.

This is separate from the inbound addresses above: an inbound address receives mail *forwarded* to the platform, while a connected mailbox is your real Gmail/Outlook account that the agent reads and sends from directly. The card appears only when your deployment has the Gmail/Microsoft OAuth app configured.

## Bring your own mailbox (IMAP / SMTP)

This is a **Business plan** capability, separate from the OAuth Gmail / Outlook connection above. Use OAuth when you want the agent to act *inside* a Google or Microsoft account; use IMAP / SMTP for any other provider, or when you'd rather connect with an app password than an OAuth grant.

Instead of a platform address, you can connect a real mailbox that the agent polls over **IMAP** and replies from over **SMTP**. Adding one opens the **Add IMAP / SMTP mailbox** dialog:

* **Provider preset** — **Gmail**, **Outlook / Office 365**, or **Custom IMAP**. Picking Gmail or Outlook prefills the host and port; Custom leaves them blank.
* **IMAP** host, port, username, password, and folder (defaults to `INBOX`).
* **SMTP** host, port, and — optionally — a separate password, **From address**, and **From name**.
* **Poll interval** — how often, in seconds, the agent checks for new mail.
* **On new mail** — **React to all**, **Classify first**, or **Store only**.

Click **Verify & add**. The mailbox joins your address list only once its IMAP connection actually verifies — if the host or credentials are wrong, the dialog reports the failure and keeps your entry so you can fix it and retry.

Once added, a mailbox shows up as an entry in the address list (tagged **IMAP / SMTP**) with its own **On / OFF** toggle, a **Connect & test** / **Disconnect** control, and an **Auto-reply over SMTP** toggle that lets the agent send replies from that mailbox's own SMTP server.

For Gmail, turn on 2-Step Verification and create an **app password** — your normal password won't work over IMAP/SMTP. For Outlook / Office 365, your admin must have **IMAP** and **Authenticated SMTP** enabled for the mailbox.

## Processing pipeline (advanced)

Before the agent reacts to an inbound email it passes through up to three optional, owner-only stages:

1. **Event Pre-Processor (code).** Your own JavaScript or Python runs in a sandbox *before* anything else and returns a verdict — `pass_to_agent`, `drop` (the cheapest gate — skips the LLM entirely), `store`, or `run_tool` (send a reply, etc., with no LLM). See the full [Event pre-processor](/sidebar-menu/event-pre-processor) reference for the `event` fields, verdicts, the `run_tool` allow-list, and worked examples.
2. **Interpreters.** Named rules that recognise *what kind* of email arrived — an invoice, a support request, a bounce — and inject a short hint into the agent's context so it knows what it's handling before it reads the body. They don't accept or reject anything; they only add framing. Reach for them when one address receives several different kinds of email. See [Interpreters](/sidebar-menu/event-interpreters).
3. **Event Classifier (LLM).** Optional. When enabled, an LLM reads each email the pre-processor passed through and picks an action — **reply**, **escalate**, **store**, or **drop** — guided by your optional *What counts as relevant?* prompt. With the classifier **off**, the agent reacts to every email that reaches it.

Every email is stored regardless; the pipeline only controls Inbox visibility and whether the reply pipeline fires. All three stages are optional and independent.

### Example — the classifier

**Simple.** Leave the classifier off. Every email that reaches this address goes straight to the agent — a good fit for a single-purpose `support@` address.

**Complex.** Turn the classifier on and set *What counts as relevant?* to: *"Only reply to genuine support questions; mark sales and partnership pitches as escalate; drop newsletters."* The classifier reads each email and picks one of **reply**, **escalate**, **store**, or **drop**: a newsletter is dropped, a partnership pitch is escalated and stored for you to review in the Inbox, and a real support question gets an agent reply.

## Recent Inbound Emails

The bottom of the page shows a log of the most recently received emails for this agent — sender, subject, and timestamp. Use this to verify emails are arriving and being processed correctly. For the agent's outbound history, see the [Sent](/sidebar-menu/emails) page.

## Replying to emails

If you want the agent to reply to the original sender, enable the **Send email** tool and set it to reply-to mode. The `from` address in the agent's reply will be the inbound address that received the email.

To receive replies back into the conversation (creating a threaded exchange), set the inbound address as the reply-to on outgoing emails.

## Manage via the Management MCP

This area is managed through the [Management MCP](/manage-mcp) at `https://manage.agentheya.com/mcp`.

|          |                                                                |
| -------- | -------------------------------------------------------------- |
| Endpoint | `https://manage.agentheya.com/mcp`                             |
| Tools    | `list_email_triggers, add_email_trigger, remove_email_trigger` |

All tools take `owner_id` + `agent_id` as required arguments. See the [Management MCP guide](/manage-mcp) for authentication and the full tool catalogue.