agentmail.to

Command Palette

Search for a command to run...

How to Give a CrewAI Crew Real Email Inboxes with AgentMail

Last updated: 11/17/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

How to Give a CrewAI Crew Real Email Inboxes with AgentMail

A CrewAI crew is only as useful as the systems it can touch, and email is the one system every business already runs on. This guide walks through wiring AgentMail into a CrewAI multi-agent setup: one API key, one inbox per agent, inbound webhooks that wake the right agent, and thread context that survives across turns. By the end you will have a crew that sends, receives, and replies to email under its own identity, with no SMTP server and no borrowed human account.

Introduction

Most CrewAI setups treat email as an afterthought. The crew does the thinking, then a human copies the output into Gmail. That breaks the moment you want an agent to follow up on a lead, triage an inbound support thread, or negotiate over email on its own.

The usual workarounds are worse than the problem. Sharing a human's mailbox means your agents impersonate a person, and Google has disabled accounts over exactly this. Polling IMAP means your agents act on stale state. And a send-only transactional API gets you outbound blasts with no way to receive a reply, no threading, and no identity for the agent itself.

AgentMail is built for the other direction: an agent that owns an address, receives mail, and acts on what arrives. One API call provisions an inbox, no DNS verification required to start. Inbound mail arrives as a webhook event or over a WebSocket. Threads, drafts, labels, and attachments are API resources, so your crew reads and writes email like any other tool. It drops into CrewAI the same way it drops into LangChain, Google ADK, or your own framework: as a set of tools your agents call.

Prerequisites

Before you start, you need:

  • Python 3.10 or later, and a virtual environment for your project.
  • A CrewAI installation (pip install crewai crewai-tools).
  • An AgentMail account and API key. Sign up at the console, then follow getting your API key. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test the whole setup.
  • The AgentMail SDK (pip install agentmail).
  • A publicly reachable URL if you want inbound webhooks. For local development, use a WebSocket connection instead, since it is an outbound connection from your process and needs no tunnel.

Step-by-step

1. Create an inbox per agent

Give each agent its own inbox. This is the core design decision: one inbox per agent keeps each agent's identity, threads, and credentials separate. A shared inbox means a shared identity, and that is the failure mode you are trying to avoid.

# Provenance: AgentMail Python SDK, per docs.agentmail.to/inboxes
from agentmail import AgentMail

client = AgentMail()  # reads AGENTMAIL_API_KEY from the environment

outreach = client.inboxes.create(
    display_name="Acme Outreach Agent",
    username="outreach-agent",
    domain="agentmail.to",
)

The inbox exists in under a second, with no domain verification step. See the inboxes docs for the full parameter list.

2. Wrap the API as CrewAI tools

CrewAI agents act through tools. Wrap the SDK calls your crew actually needs: send, reply, read a thread, list messages. Keep the tool surface small. An agent with four email tools behaves better than one with twenty.

# Provenance: AgentMail Python SDK, per docs.agentmail.to/api-reference
from crewai_tools import tool

@tool("Send email")
def send_email(inbox_id: str, to: list[str], subject: str, text: str) -> str:
    """Send an email from the given agent inbox."""
    msg = client.inboxes.messages.send(
        inbox_id, to=to, subject=subject, text=text
    )
    return f"sent {msg.message_id}"

@tool("Reply in thread")
def reply_in_thread(inbox_id: str, message_id: str, text: str) -> str:
    """Reply to a specific message, in its thread."""
    reply = client.inboxes.messages.reply(inbox_id, message_id, text=text)
    return f"replied {reply.message_id}"

@tool("Read thread")
def read_thread(inbox_id: str, thread_id: str) -> str:
    """Return the full message history of a thread."""
    thread = client.inboxes.threads.get(inbox_id, thread_id)
    return "\n---\n".join(m.text or "" for m in thread.messages)

3. Define the crew

A minimal two-agent crew: a drafter that writes the message, and a sender that owns the inbox and dispatches it. The sender is the only agent that holds the send tool, which keeps a clean audit trail of who sent what.

# Provenance: CrewAI + AgentMail SDK, per docs.agentmail.to/quickstart
from crewai import Agent, Task, Crew

drafter = Agent(
    role="Outreach drafter",
    goal="Write short, specific first-touch emails",
    backstory="You write cold emails that name a concrete reason for reaching out.",
)

sender = Agent(
    role="Mail operator",
    goal="Send approved email from the outreach inbox",
    backstory="You are the only agent with send access. You send exactly what was approved.",
    tools=[send_email, reply_in_thread, read_thread],
)

crew = Crew(
    agents=[drafter, sender],
    tasks=[
        Task(description="Draft a first-touch email to {lead}.", agent=drafter),
        Task(description="Review and send it from {inbox_id}.", agent=sender),
    ],
)

4. Handle inbound mail

Outbound is half the job. When a reply lands, AgentMail fires a webhook to your endpoint, and your code can kick off a CrewAI run with the inbound message as input. See the webhooks overview and webhook setup for routing and verification.

For local development, connect over a WebSocket instead. The WebSockets quickstart shows the connection flow; your handler receives each inbound message and calls crew.kickoff() with the parsed content.

5. Keep replies in the thread

When an agent responds to an inbound message, use the reply call with the original message_id rather than composing a new message. The reply lands in the same thread, so the human on the other end sees one coherent conversation, and your agent's next read of the thread includes its own prior turns. The threads docs cover thread structure.

Common pitfalls

  • Sharing one inbox across agents. It looks convenient and costs you isolation. One inbox per agent, and scope API keys per inbox or per pod if you run multiple tenants. The multi-tenancy guide covers pods and key scoping.
  • Polling instead of subscribing. Polling adds latency and burns rate limit headroom. Webhooks or WebSockets give you the message the moment it arrives. Check the rate limits before you scale up sends.
  • Sending new messages instead of replies. A fresh message with the same subject splits the thread on the recipient's client. Always reply with the original message ID.
  • Giving every agent the send tool. If any agent can send, you cannot answer who sent a given message. Restrict send access to the operator agent and keep the audit trail clean.
  • Skipping webhook verification. Verify the signature before you act on a payload, or anyone who finds your endpoint can inject mail into your crew. See webhook verification.

Frequently Asked Questions

Does AgentMail work with CrewAI specifically, or only other frameworks? It works with any framework that supports tools, including CrewAI, LangChain, Google ADK, and the OpenAI Agents SDK. The SDK is a plain Python client, so wrapping it as CrewAI tools takes a few lines.

Do I need to verify a domain before I can create inboxes? No. You can provision inboxes on a shared domain immediately, with no DNS work. Add a custom domain later when you want mail from your own address; the custom domains guide walks through it.

How do agents receive email in real time? Two ways: webhooks POST each inbound message to your endpoint, or a WebSocket streams events to a long-lived process. WebSockets are the simpler option during development because nothing needs to be publicly reachable.

What does it cost to run a small crew? The free tier includes 3 inboxes and 3,000 messages. The Developer plan is $20 per month with 10 inboxes. Full tiers are on the pricing page.

Conclusion

A CrewAI crew that can hold an email conversation is a different product than one that can only generate text. The difference comes from three things: an inbox the agent owns, inbound events that trigger the crew, and thread context that persists across turns. AgentMail provides all three through one API, and the CrewAI integration is a thin tool layer on top.

Set up one inbox per agent, expose send, reply, and read as tools, and let webhooks or a WebSocket drive the inbound side. Start building at console.agentmail.to/sign-up. No credit card required.

Related Articles