← Back to guides
Use Case6 min read

Build an AI agent that processes inbound emails

Give your agent its own email address, receive messages from anyone, and respond automatically. This guide walks through the full workflow.

Overview

Every AgentInbox agent gets a unique email address like agent-b4a0@agent-mail.agentinbox.sh. Anyone can send emails to this address — humans, services, notification systems, other agents. Your agent can read incoming messages and reply automatically, all through MCP tools.

What you can build

  • A support agent that triages and responds to customer emails
  • A notification processor that reads alerts and takes action
  • A personal assistant that handles scheduling requests via email
  • An agent that monitors a shared inbox and routes messages

Get your agent's email address

Use the get_inbox_address tool to retrieve your agent's assigned email address. This is determined automatically from your authentication credentials.

Request

// Call get_inbox_address with no parameters
{}

Response

{
  "email": "agent-b4a0@agent-mail.agentinbox.sh",
  "displayName": "agent-b4a0",
  "plan": "free",
  "domain": "agent-mail.agentinbox.sh"
}

The email field is the address people will use to send messages to your agent.

Share your address

Once you have your agent's email address, share it wherever you want to receive messages:

  • Give it to people directly — they can email your agent like any normal address
  • Use it as a contact email on forms or landing pages
  • Subscribe it to notification services, CI/CD alerts, or monitoring tools
  • Set it as a forwarding address from an existing mailbox

Any email sent to your agent's address will be stored and available for retrieval through the get_emails tool.

Check for new emails

Use get_emails with direction: "inbound" to fetch only incoming messages. This filters out any emails your agent has sent.

Request

{
  "limit": 5,
  "direction": "inbound"
}

Response

{
  "emails": [
    {
      "id": "aaa-111-...",
      "from": "alice@example.com",
      "to": "agent-b4a0@agent-mail.agentinbox.sh",
      "subject": "What's the status of project X?",
      "body": "Hi, can you give me an update...",
      "messageId": "abc123@mail.example.com",
      "threadId": "thr-999-...",
      "direction": "inbound",
      "status": "received",
      "created_at": "2026-03-08T10:30:00Z"
    }
  ],
  "total": 1
}

Each email includes a messageId you can use for threading, and a threadId to fetch all messages in the same conversation.

Process and reply

Once your agent reads an incoming email, it can decide how to respond. Use send_email with the inReplyTo parameter to reply in the same thread. This ensures the reply shows up as part of the original conversation in the sender's email client.

Request

{
  "to": "alice@example.com",
  "subject": "Re: What's the status of project X?",
  "body": "Hi Alice, here's the latest on project X:\n\n- Design phase: complete\n- Development: 80% done\n- Launch target: March 15\n\nLet me know if you need more details.",
  "inReplyTo": "abc123@mail.example.com"
}

Response

{
  "emailId": "bbb-222-...",
  "messageId": "bbb-222-...@agent-mail.agentinbox.sh",
  "threadId": "thr-999-...",
  "status": "sent",
  "from": "agent-b4a0@agent-mail.agentinbox.sh",
  "to": "alice@example.com",
  "subject": "Re: What's the status of project X?"
}

The inReplyTo value should be the messageId from the email you're replying to. The server automatically sets the correct threading headers.

Example workflow

Here's a complete flow showing an agent handling an inbound email from start to finish.

Step 1 — Someone emails your agent

Alice sends an email to agent-b4a0@agent-mail.agentinbox.sh asking: "What's the status of project X?"

Step 2 — Agent checks inbox

The agent calls get_emails with direction: "inbound" and sees Alice's message. It reads the subject and body to understand the request.

// Agent calls get_emails
{ "limit": 10, "direction": "inbound" }

// Finds Alice's email with:
//   messageId: "abc123@mail.example.com"
//   subject: "What's the status of project X?"
//   body: "Hi, can you give me an update..."

Step 3 — Agent gathers information

The agent uses its other tools or knowledge to gather the relevant information. This could involve querying a database, checking a project management tool, or using any other MCP tools available to it.

Step 4 — Agent replies with threading

The agent sends a reply using send_email with inReplyTo set to Alice's original messageId. The reply appears in the same thread in Alice's inbox.

// Agent calls send_email
{
  "to": "alice@example.com",
  "subject": "Re: What's the status of project X?",
  "body": "Hi Alice, here's the latest:\n\n- Design: complete\n- Dev: 80% done\n- Launch: March 15",
  "inReplyTo": "abc123@mail.example.com"
}

Tips

Poll periodically for new emails

AgentInbox doesn't push notifications to your agent. Design your workflow to call get_emails at regular intervals to check for new inbound messages. You can track which emails you've already processed by their id or created_at timestamp.

Use threading for conversations

Always pass inReplyTo when replying to keep the conversation grouped. You can also use threadId in get_emails to fetch the full history of a conversation before responding.

Filter by direction

Use direction: "inbound" to see only received emails, or direction: "outbound" to review what your agent has sent. Omit the parameter to see everything.

← Back to guidesDocumentation →