How to Use the AgenticMail Plugin for Email‑Based Coordination

The AgenticMail plugin enables Claude assistants to read, compose, and send emails through SMTP/IMAP connections, allowing multiple AI agents to coordinate distributed workflows via a shared inbox.

The AgenticMail plugin extends Claude’s capabilities with full email integration, enabling sophisticated multi‑agent coordination through standard email protocols. Available through the anthropics/claude-plugins-community repository, this plugin exposes a clean OpenAPI interface for listing threads, reading messages, and sending replies. By leveraging the plugin architecture defined in .claude-plugin/marketplace.json, you can enable email‑based workflows that let distributed agents share status updates and delegate tasks asynchronously.

Installing and Enabling the AgenticMail Plugin

Plugin Discovery in the Marketplace

The Claude runtime discovers AgenticMail through the centralized marketplace registry. In the anthropics/claude-plugins-community repository, the file .claude-plugin/marketplace.json contains the canonical entry for the plugin at lines 756–765, specifying the source Git URL (https://github.com/agenticmail/agenticmail.git) and homepage metadata. Additionally, .github/owner-baseline.json at line 194 records the plugin name for compliance verification.

To enable the plugin in a Claude session using the Python SDK:

from claude import ClaudeClient

client = ClaudeClient(api_key="YOUR_CLAUDE_API_KEY")
client.enable_plugin("agenticmail")  # Loads OpenAPI spec from the repository

Configuring SMTP and IMAP Authentication

AgenticMail requires valid SMTP and IMAP credentials to interact with mail servers. These credentials are supplied via your Claude settings or a hidden .env file—the repository itself contains no hardcoded secrets. At runtime, the plugin reads these credentials from the secure environment context, ensuring passwords never appear in source code or logs.

Core Email Operations

The plugin exposes three primary operations through its OpenAPI specification, allowing Claude to invoke functions with typed JSON arguments.

Listing Active Threads with list_threads

The list_threads operation returns the IDs of recent email threads available for processing. This allows agents to poll for new coordination messages without retrieving full message bodies.

message = client.run_plugin(
    plugin="agenticmail",
    operation="list_threads",
    arguments={}
)
print("Open threads:", message["thread_ids"])

Reading Messages with read_message

Use the read_message operation to retrieve the full body of a specific email by providing its thread_id. This returns the complete message content including headers and text body.

thread_id = "abcd1234"
message = client.run_plugin(
    plugin="agenticmail",
    operation="read_message",
    arguments={"thread_id": thread_id}
)
print(message["body"])

Sending Replies with send_reply

The send_reply operation transmits new email messages, optionally including attachments or structured summaries. This enables agents to post status updates and delegate subsequent tasks.

client.run_plugin(
    plugin="agenticmail",
    operation="send_reply",
    arguments={
        "thread_id": thread_id,
        "subject": "Re: Project Update",
        "body": """\
Hi team,

Here's the current status:
- Data ingest: 95%
- Model training: pending

Next steps:
1. Start model training (Agent B)
2. Review metrics (Agent C)

Thanks,
Agent A
""",
        "attachments": []
    }
)

Implementing Multi‑Agent Coordination Workflows

Email‑based coordination relies on a shared "coordination inbox" where agents post updates and read statuses. Because the plugin operates within Claude’s security sandbox, all traffic is logged and auditable.

A typical three‑agent workflow proceeds as follows:

1. Agent A posts a status update describing completed work using send_reply
2. Agent B polls list_threads to discover new messages, calls read_message to parse the status, performs its assigned task, and uses send_reply to report completion
3. Agent C monitors the thread for specific completion keywords before proceeding with final validation

# Agent A posts initial status

agent_a.send_status_update()

# Agent B reads and responds

status = agent_b.read_current_status()
if status["model_training"] == "pending":
    agent_b.execute_training()
    agent_b.reply_with_progress_update()

# Agent C waits for completion notification

while not agent_c.check_thread_contains("training complete"):
    time.sleep(30)

Error Handling and Reliability

Each endpoint returns a standardized error object containing code and message fields. Claude automatically retries transient network failures, such as temporary IMAP connection drops, and surfaces concise explanations for permanent errors—for example, "mailbox not found" or authentication failures.

Summary

• The AgenticMail plugin is registered in .claude-plugin/marketplace.json (lines 756–765) and tracked in .github/owner-baseline.json (line 194) of the anthropics/claude-plugins-community repository
• Enable the plugin via client.enable_plugin("agenticmail") to load the OpenAPI specification from https://github.com/agenticmail/agenticmail.git
• Configure SMTP/IMAP credentials through Claude settings; the plugin reads these at runtime without exposing them in code
• Use list_threads to poll for new messages, read_message to retrieve content, and send_reply to send updates and coordinate tasks
• Multi‑agent coordination works through a shared inbox where agents asynchronously post and consume status updates
• Standardized error objects with code and message enable automatic retry logic for transient failures while surfacing permanent errors to users

Frequently Asked Questions

What authentication does AgenticMail require?

AgenticMail requires standard SMTP and IMAP credentials to send and receive emails. You provide these through Claude’s secure settings interface or environment variables; the plugin never stores credentials in the repository or exposes them in source code.

Can multiple Claude instances use the same inbox simultaneously?

Yes. Multiple agents can coordinate through a single shared inbox by using list_threads to discover new messages and send_reply to post updates. Each agent should implement polling logic to check for new threads periodically.

Where is the AgenticMail plugin defined in the repository?

The plugin entry is located in .claude-plugin/marketplace.json at lines 756–765, which specifies the source Git URL and metadata. The plugin name is also recorded in .github/owner-baseline.json at line 194 for baseline compliance tracking.

How does the plugin handle email sending failures?

The plugin returns structured error objects with code and message fields. Claude’s runtime automatically retries transient network errors, such as temporary connection timeouts, and surfaces permanent errors—like authentication failures—directly to the user with descriptive messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}