Agentmail Hermes skill

AgentMail — Agent-Owned Email via Python SDK

Overview

AgentMail gives AI agents their own email inbox at @agentmail.to. This skill uses the official agentmail-python SDK (not MCP) for direct, scriptable email operations: create inboxes, send/reply/forward messages, manage threads, handle attachments, and configure custom domains.

Key distinction: This is for the agent's own identity. The agent sends email as itself (e.g. [email protected]), not as the user. For the user's personal email, use himalaya or Gmail.

Quick Install

pip install agentmail python-dotenv

Environment Setup

Set the API key (get one free at https://console.agentmail.to):

export AGENTMAIL_API_KEY="am_your_key_here"

Or in .env:

AGENTMAIL_API_KEY=am_your_key_here

Core Commands

Initialize Client

import os
from agentmail import AgentMail

client = AgentMail(api_key=os.environ["AGENTMAIL_API_KEY"])

Create Inbox

inbox = client.inboxes.create(username="my-agent")
# Returns: inbox.inbox_id, inbox.email_address (e.g. "[email protected]")

Send Email

client.inboxes.messages.send(
    inbox.inbox_id,
    to="[email protected]",
    subject="Hello from my agent",
    text="Plain text body",
    html="<p>HTML body</p>",  # optional
)

List Messages

response = client.inboxes.messages.list(inbox.inbox_id, limit=10)
for msg in response.messages:
    print(f"{msg.subject} — {msg.extracted_text[:100]}")

Reply to Message

client.inboxes.messages.reply(
    inbox.inbox_id,
    message_id,
    text="My reply",
)

Forward Message

client.inboxes.messages.forward(
    inbox.inbox_id,
    message_id,
    to=["[email protected]"],
)

Send with Attachments

import base64

with open("report.pdf", "rb") as f:
    attachment = {
        "filename": "report.pdf",
        "content": base64.b64encode(f.read()).decode(),
    }

client.inboxes.messages.send(
    inbox.inbox_id,
    to="[email protected]",
    subject="Report attached",
    text="See attached.",
    attachments=[attachment],
)

List Inboxes

for inbox in client.inboxes.list().inboxes:
    print(f"{inbox.email_address} ({inbox.inbox_id})")

Manage Threads

# List threads
threads = client.inboxes.threads.list(inbox.inbox_id, limit=5)
for t in threads.threads:
    print(f"{t.subject} — {len(t.messages)} messages")

# Get full thread
thread = client.inboxes.threads.get(inbox.inbox_id, thread_id)
for msg in thread.messages:
    print(f"  {msg.from_}: {msg.extracted_text[:80]}")

When to Use

• Agent needs to send outbound email (notifications, reports, outreach)
• Agent needs to receive and process incoming email
• Agent needs its own identity for service sign-ups
• Agent-to-agent or agent-to-human communication
• Automated follow-ups and email workflows

When NOT to Use

• Reading the user's personal email → use himalaya or google-workspace
• Sending email on behalf of the user (not the agent) → use himalaya
• Transactional email at scale → use SendGrid/Postmark

Pitfalls

1. Rate limits. AgentMail returns 429 with Retry-After header. Use exponential backoff or check error.body for details.

2. extracted_text vs text. When reading messages, prefer msg.extracted_text — it strips quoted history. msg.text includes the full quoted thread.

3. Idempotent inbox creation. Pass client_id to inboxes.create() to safely retry without duplicates:

   inbox = client.inboxes.create(username="agent", client_id="my-agent-v1")
   

4. API key rotation. Calling agent.sign_up() again with the same email rotates the API key. Store it securely after first use.

5. Free tier limits. 3 inboxes, 3,000 emails/month. Custom domains require paid plans.

6. Attachment encoding. Attachments must be base64-encoded content, not file paths. Use base64.b64encode(open(f,'rb').read()).decode().

7. OTP expiry. Agent verification OTP expires after 24 hours, max 10 attempts. Request a new one if needed.

8. Thread update limits. Threads with 100+ messages reject update requests with 422.

Verification Checklist

• pip install agentmail python-dotenv succeeds
• AGENTMAIL_API_KEY is set and valid
• client.inboxes.list() returns without error
• Can create an inbox and get an email address
• Can send a test email and verify delivery
• Can list received messages

References

• references/api-reference.md — Full SDK endpoint reference. Load when you need the exact parameters for any AgentMail API call.
• references/workflows.md — Common workflow patterns (sign-up verification, email parsing, cron-based inbox monitoring). Load when implementing complex email automation.
• references/troubleshooting.md — Error codes, debugging, and FAQ. Load when hitting unexpected errors.