Everything you need to know to build email agents
Foundations, threading, webhooks, drafts with Ask, attachments, allow lists, and deployment on Neuro OS.
Discuss this post in AI
Send a pre-filled prompt to ChatGPT, Claude, Gemini, or Perplexity — get a summary, ask follow-ups, or compare ideas from this guide.
Building an email agent is less about a single clever prompt and more about a reliable loop: mail arrives, the role understands the thread, tools run in a sandbox, a human gates risky sends, and the system waits for the next event. This guide is the practical checklist Pattern Automation uses with Agent Inbox and Neuro OS.
Foundations
Start with a role that has a clear owner, a skill document, and an inbox. Provision the mailbox through Agent Inbox:
from agentinbox import AgentInbox
client = AgentInbox()
inbox = client.inboxes.create(username="claims", domain="agentinbox.space")
Put the address in role config next to connectors and model policy. Decide early whether the role may only draft, or may send after Ask. Default to Ask. Block credential export and unrestricted blast lists.
Threading
Rely on Message-ID, In-Reply-To, and References. Prefer the inbox API’s stored threads over hand-rolled subject parsing. Idempotent replies matter: if a webhook retries, do not send twice. Details: email threading.
Webhooks versus polling
Webhooks wake the agent when mail arrives. Polling is a fallback for constrained networks, not the primary design. Debounce bursts on busy threads. Record the event id you processed so retries are safe.
Drafts and Ask
The model should produce a draft—body, recipients, attachments—then present it for Ask. Humans approve, edit, or reject. The same gate applies to forwards that leave the agent boundary. Neuro OS makes Ask the default for writes and sends; do not disable it to “feel autonomous.”
Attachments
Extract text and structured fields from attachments inside the sandbox. Do not execute macros or remote content. Promote confirmed facts into project memory; leave raw MIME out of the prompt. See email as memory and rendering email safely.
Allow and block lists
Maintain allow lists for domains the role may contact, and block lists for sinks that should never receive automated mail. Separate internal systems (1C, Bitrix, amoCRM notification paths) from external customer domains. Complaints and bounces feed deliverability hygiene—deliverability 101.
HTML and Markdown
Use markdown for model I/O. Emit sanitized HTML only when a human client must render rich layout. Never treat inbound HTML as trusted code. Guidance: HTML vs Markdown.
Forwarding
Accept forwards from humans and systems as first-class intake. When Ask requires a person, forward the thread out with history. Operational pattern: you don’t need to receive email anymore.
Deploy on Neuro OS
Neuro OS keeps roles in git, runs them in sandboxes, brokers connectors server-side, and supports any approved model. Self-host when policy requires. Pair each production role with evaluations: wrong recipient, missing Ask, leaked context across tenants. Multi-tenant isolation notes: pods multi-tenant email.
Minimal vertical slice
- Create inbox and role
- Inbound webhook → classify → draft
- Ask → send
- Wait for reply → continue thread
- Escalate by forward when confidence or policy fails
That slice beats a demo that sends one email and never reads the answer. For architecture context, return to the definitive guide. For product intro, see Introducing Agent Inbox.
Email agents are ordinary Neuro OS roles with a mailbox and a strict send gate. Build the loop, not a one-shot script.
Agent Inbox gives each role a mailbox people can reply to, with forwarding into Neuro OS when a human must see the thread. Outbound mail defaults to Ask. Run the role on Neuro OS. To scope the first inbox, get started.