Skip to main content
The MailWorker lets your build an agent that communicates via email. It receives incoming messages, stores them in your room, generates replies using an LLM, and sends responses back out through SMTP — automatically turning your inbox into an intelligent, room-connected agent. MailWorker extends the Worker agent to process inbound email from a queue and send replies via SMTP. It automatically persists every message and attachment to room storage, builds conversation context from past emails, and can call tools or reason over messages like any other agent.
Prerequisite: To use MailWorkers you must either be an admin of the MeshAgent project you are using or have an admin create and allocate an email address for the agent to use. Only project admins can create and allocate email addresses.

​
When to Use It

Use MailWorker when you want an agent that:
  • Responds to incoming email automatically (e.g., helpdesk, order confirmations, triage bots)
  • Maintains threaded context so replies include past conversation history (based on the current email thread)
  • Runs LLMs or tools over incoming email messages before responding
  • Bridges email and your MeshAgent environment, connecting to other agents or toolkits in the same room
If you just need a background job, see Worker. If you want real-time conversations outside of email, see ChatBot or VoiceBot.

​
Constructor Parameter

MailWorker inherits all Worker parameters (like queue, llm_adapter, tool_adapter, toolkits, rules, and requires) and adds a few email-specific ones:
ParameterTypeDescription
queuestrName of the queue to listen to (default "email").
email_addressstrThe address used as the “From” field for outgoing replies.
domainstrDomain for message routing, defaults to MESHAGENT_MAIL_DOMAIN or "mail.meshagent.com".
smtpSmtpConfiguration | NoneSMTP settings (hostname, port, username, password). Defaults to environment variables if not provided.

​
Lifecycle Overview

MailWorker inherits its lifecycle from Worker:
  • await start(room): connects to the room and begins long-polling the email queue for new messages.
  • await stop(): gracefully stops the polling loop and disconnects.
Note: “Long-polling” means the worker efficiently waits on the queue until a new message arrives—no busy-looping or manual sleep required.

​
Processing Flow

MailWorker runs a continuous loop inherited from Worker that listens for incoming email messages on a queue and processes them end-to-end.
  1. Receive an email — The worker long-polls the email queue and receives base64-encoded .eml messages.
  2. Parse and persist — It decodes the message, extracts headers, body, and attachments, and saves them under .emails/... in room storage. A summary record is inserted into the emails table for lookup and threading.
  3. Rebuild thread context — The agent walks the In-Reply-To chain to include earlier messages in the LLM’s context.
  4. Generate a reply — The llm_adapter uses the chat context and toolkits to produce a text reply.
  5. Send via SMTP — A threaded reply (RE:, In-Reply-To, Message-ID) is composed and sent using your SMTP credentials. The reply is also stored alongside the original message.

​
Key Methods

MethodDescription
process_message(chat_context, room, message, toolkits)Core processing logic—decodes, saves, builds thread, calls the LLM, and sends the reply.
append_message_context(room, message, chat_context)Loads the full email thread into the chat context.
get_thread_toolkits(thread_context)Resolves local and required toolkits for the current email thread.
send_reply_message(room, message, reply)Composes and sends the actual reply message via SMTP.

​
Example

First create and allocate an available email address, then define a MailWorker that uses it. 
import os
import asyncio
import aiohttp
import logging
from meshagent.otel import otel_config
from meshagent.api import Meshagent
from meshagent.api.services import ServiceHost
from meshagent.openai import OpenAIResponsesAdapter
from meshagent.agents.mail import MailWorker

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="mailbot")
log = logging.getLogger("mailbot")

queue = os.environ["EMAIL_QUEUE"]
email_address = os.environ["EMAIL_ADDRESS"]
project_id = os.environ["MESHAGENT_PROJECT_ID"]

service = ServiceHost()  # MeshAgent assigns a free port if you omit one


async def ensure_mailbox(*, room_name: str) -> None:
    meshagent = Meshagent(base_url=os.getenv("MESHAGENT_BASE_URL"))
    try:
        await meshagent.create_mailbox(
            project_id=project_id,
            address=email_address,
            room=room_name,
            queue=queue,
        )
        log.info("Created mailbox %s for room %s", email_address, room_name)
    except aiohttp.ClientResponseError as exc:
        if exc.status == 409:
            raise RuntimeError(
                f"Mailbox '{email_address}' already exists. Choose a different EMAIL_ADDRESS and try again."
            ) from exc
        raise
    finally:
        await meshagent.close()


@service.path(path="/mail", identity="mailbot")
class ExampleMailbot(MailWorker):
    def __init__(self):
        super().__init__(
            name="mailbot",
            title="mailbot",
            description="An agent that responds via email",
            llm_adapter=OpenAIResponsesAdapter(),
            rules=["You are a helpful assistant that responds to users via email."],
            queue=queue,
            email_address=email_address,
        )
        self._mailbox_ready = False

    async def start(self, *, room):
        if not self._mailbox_ready:
            await ensure_mailbox(room_name=room.room_name)
            self._mailbox_ready = True
        await super().start(room=room)


asyncio.run(service.run())
Set env vars, pick a queue, and choose a unique email address. If you’re self-hosting, you can override the default mail domain. You’ll also need to export the MeshAgent Project ID you can run meshagent project list from the CLI to get the IDs associated with the MeshAgent projects you have access to. 
export EMAIL_QUEUE="test_email"
export EMAIL_ADDRESS="myemail@mail.meshagent.com" # come up with a unique email
export MESHAGENT_PROJECT_ID="<your-project-id>"
# If self-hosting, you can also set:
# export MESHAGENT_MAIL_DOMAIN="mail.meshagent.com" # this would be your custom domain instead of the default mail.meshagent.com
Next, run the service: 
meshagent service run "main.py" --room=maildemo
At this point, the MailWorker is connected to the maildemo room and listening on the queue you configured. As mail arrives (forwarded into the queue), the worker will parse, store, generate a reply, and send it via SMTP.
Note: Once you stop the room, the mail agent will not automatically restart unless you save the agent configuration and deploy the agent as a project wide service or run it via a room container. To persist your mail agent and reuse it you will need to save the configuration for your agent and create a project wide service that manages saved agent configurations via room containers. This project wide service will be responsible for starting/stopping agent configuration in a specific room. You can learn more about this in the services & containers documentation.

​
Next Steps

Explore and understand other agents in MeshAgent:
  • Worker: Understand how queue based agents work
  • TaskRunner: Learn how to run agents in the background or wrap existing agents from other frameworks
  • ChatBot: Create a conversational text/chat based agent
  • VoiceBot: Create a conversational speech/voice based agent
Learn how to deploy and run agents across rooms in a project or in specific rooms: