# Email Source: https://www.hyperagent.com/docs/concepts/agents/invocations/email > For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL. Give an agent its own email address: control who may send, turn messages into threaded work, and let the agent reply or deliver updates. You want to forward an invoice, support ticket, or lead to an agent and have it pick up the work on its own, the way you would hand it to a colleague. An **email address** gives the agent that doorway: mail sent to the address starts a run, the message becomes the briefing, and the agent can reply from the same address when you allow it. Mail to the agent's address becomes a run, framed by a prompt template you write. You decide who may send, whether files come through, and whether the agent writes back. ## How email works [#how-email-works] Each email address belongs to one agent. Messages sent there can start runs without someone opening Hyperagent first. Incoming mail must pass sender authentication. Your allow list then decides which authenticated senders may invoke the agent. A prompt template turns the sender, subject, body, date, and attachments into the instructions the agent receives in its thread. With replies on, one email conversation maps to one Hyperagent thread. You can also let the agent start an email to you. ## Create and configure an email address [#create-and-configure-an-email-address] On the agent's **Invocations** tab, open the **Email** card and select **Create Email Address**. The form controls the address, the briefing each message creates, who may send, and whether the agent can answer. ### Name the address [#name-the-address] Choose the readable start of the address. Hyperagent adds a random suffix and your deployment's email domain. ### Frame the work [#frame-the-work] Write the prompt template that introduces each message to the agent. If replies are off, you can also tell the agent how to name each new thread. ### Set access and file handling [#set-access-and-file-handling] Add exact senders or domains, then decide whether attachments should enter the thread with the message. ### Choose the conversation behavior [#choose-the-conversation-behavior] Decide whether the agent may reply and whether it may start a new email conversation with you. ## Email configuration options [#email-configuration-options] ## Control who can trigger the agent [#control-who-can-trigger-the-agent] Every inbound message clears two gates: the receiving mail service must authenticate it, and the sender must satisfy the address's **Allowed Senders** rules. ### Allowed senders [#allowed-senders] Leave the list empty to accept any authenticated sender. This works for public intake, but it lets more people invoke the agent. A line such as `alice@example.com` matches that address and no one else. A line beginning with `@`, such as `@company.com`, admits every sender at that domain by matching the end of the address. Enter one rule per line. There is no wildcard or separate subdomain syntax, and Hyperagent stores patterns in lowercase so matching is case-insensitive. Once the list contains a rule, unmatched senders are rejected silently. An empty list creates an open inbox for any authenticated sender. Use exact addresses or domains when the agent can write to connected systems or take other consequential actions. Virus, spam, authentication, replay, size, rate-limit, paused-address, and allow-list failures are silent. A bounce would confirm that the address is live or reveal its sender rules. When a run row already exists, the failure reason appears there for you instead. ### What an accepted sender can do [#what-an-accepted-sender-can-do] Email-invoked runs use the agent's normal tools and integration access; they aren't forced into the read-only behavior a standard schedule starts with. The allow list is therefore both an entry gate and a trust boundary. An open inbox authorizes accepted mail for ordinary work. When a sender matches a populated allow list, Hyperagent treats that sender as explicitly trusted, which also lets the email-invoked run delegate work to subagents on their behalf. ## Choose how email conversations work [#choose-how-email-conversations-work] ### Reply behavior and threading [#reply-behavior-and-threading] Every inbound message opens its own thread, named from the **Thread naming hint**. The agent does the work without answering by email. Messages in one email conversation continue in one Hyperagent thread, and the agent can reply from its own address. With replies on, Hyperagent follows the standard `In-Reply-To` and `References` headers to find the thread a message belongs to. The agent's replies come from `{slug}-{suffix}@your-domain`, using the agent's name as the display name. The agent can't change the From address, and the subject remains `Re:` plus the original without accumulating prefixes. ### Let the agent email you first [#let-the-agent-email-you-first] **Start Email Conversations** is off by default and becomes available when **Reply to Email** is on. Enabling it gives the agent the **Send Email** tool so it can start an email to you, its run owner. It can't use this setting to email arbitrary addresses. Your reply returns to the originating thread through an agent-initiated exception, even if your address isn't on the allow list. Scheduled and Live Mode email delivery use this outbound path. ## Operate and monitor an address [#operate-and-monitor-an-address] Each address is managed independently, including its state, test runs, settings, and history. ### Pause, resume, or archive [#pause-resume-or-archive] An address can be **active**, **paused**, or **archived**. Pausing stops inbound mail from starting runs without deleting the address or its history; resuming turns it back on. You can pause, resume, edit, test, or delete one address without affecting another address on the same agent. ### Test the configuration [#test-the-configuration] **Send Test Email** opens a dialog where you enter a From address, subject, and body. The To address is fixed to the email invocation you're testing. A test skips SES delivery and the replay guard so you can exercise the prompt template and reply behavior end to end. If the agent replies, Hyperagent redirects that reply to your own email instead of the simulated sender. ### Review Recent Emails [#review-recent-emails] The **Recent Emails** section on the address detail page logs what has arrived. Each row shows a status badge, sender address, when the run started, its duration, and a link to the thread. Before anything arrives, it reads `No emails received yet`. A failed run shows its error beneath the row. ### Ownership on team agents [#ownership-on-team-agents] Multiple workspace members can see and edit an agent's email addresses, but each address has one runtime owner: the member whose context and usage the runs execute under. If the runtime owner leaves the workspace, the address pauses instead of running without an owner. Any remaining member can resume it, which makes that member the new runtime owner. ## Deliver scheduled and Live Mode updates [#deliver-scheduled-and-live-mode-updates] A [scheduled](https://www.hyperagent.com/docs/concepts/agents/invocations/schedules) run or [Live Mode](https://www.hyperagent.com/docs/concepts/agents/invocations/live-mode) watch needs an active email address on the same agent before it can deliver updates by email. The address gives the run a valid From address, and **Start Email Conversations** provides the outbound path to the run owner. Set up an email invocation for this agent to start receiving alerts. The warning's **Set up** button opens the **Create Email Address** dialog. Once an active address exists, email becomes a valid delivery channel and the warning clears. ## Troubleshooting and FAQs [#troubleshooting-and-faqs] Most often the sender isn't on a populated allow list, so the message was rejected silently. Other silent drops include a virus or spam verdict, a message over the 30 MB size limit, hitting the per-sender rate limit, a paused address, or failed authentication, such as a spoofed From address or mail forwarded through an untrusted ARC sealer. If a run row exists in Recent Emails, its error says which check failed. Yes. Turn on **Start Email Conversations**, which requires **Reply to Email**. The agent can then email you, its run owner—not arbitrary addresses—and your reply returns to the same thread. Scheduled and Live Mode email delivery use this behavior too. No. With **Reply to Email** off, each message opens its own thread and the agent works without answering by email. Both replying and starting an email require the reply switch to be on. Yes, within reason. The random suffix makes the complete address impractical to guess, and every message must pass authentication before anything runs. The real exposure is capability: an open inbox lets anyone who clears authentication invoke the agent, so scope **Allowed Senders** before publishing an address for an agent that can write to your systems. No. Every rejection is silent: no bounce, delivery notice, or other response goes back to the sender. Answering spoofers or unlisted senders would confirm the address is live and reveal its access rules, so failures are recorded only on your side when a run row exists. Yes. An agent can have as many addresses as you need. Each has its own template, senders, and switches, and each can be paused, tested, or deleted independently. Two addresses on the same agent can't share a slug.