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 [e-mail].
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 [e-mail] 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 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.
• 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 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.
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 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 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 for authentication and the full tool catalogue.