Agent Email Patterns

This is architectural guidance for agents that need to send and receive email, not SDK documentation. You get seven opinionated patterns: one inbox per agent (never share), two-way conversation loops using extracted_text to strip quoted replies, human-in-the-loop drafts for high-stakes messages, WebSockets over polling, multi-agent topologies with clear role separation, OTP extraction for verification flows, and labels for workflow state. The security section is brief but covers the critical stuff like prompt injection via inbound email and allow lists for production inboxes. Useful if you're building support bots, notification agents, or anything that needs structured email communication instead of just fire-and-forget sending.

skills.sh installs: 903
GitHub stars: 26
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add agentmail-to/agentmail-skills --skill agent-email-patterns --agent claude-code

Installs into .claude/skills of the current project.

Files

Agent Email Patterns

Opinionated patterns for building AI agents that communicate over email. This skill covers architecture and security decisions, not SDK specifics. For AgentMail SDK usage, use the agentmail skill.

Why agents need their own inboxes

Giving an agent OAuth access to a human's Gmail account is the most common approach and the most dangerous:

Over-permissioned: typical OAuth scopes (e.g. gmail.modify) grant read/send/delete over the entire mailbox history, far beyond what any single task needs
Prompt injection risk: the agent inherits the full inbox history as reachable context, so any crafted email already sitting in the mailbox is a live attack surface
Revocation granularity: OAuth tokens are hard to revoke or scope per-agent -- pulling access from one workflow often means pulling it from all of them
Rate limits: consumer mailbox sending limits aren't designed for automated/programmatic workflows
Audit trail: agent actions are mixed with human actions in the same mailbox, making debugging and compliance review hard

The safer default: one dedicated, API-native inbox per agent (see Pattern 1).