SmtpChannel Quickstart

SmtpChannel turns a conversation into one email thread. Every post is emailed to you, and when you reply from your own mail client, your reply joins the conversation the agents read next. It uses a mailbox you already have, over SMTP and IMAP. Reference: SmtpChannel.

Setup

You need a mailbox the agents can send from and read, and its password. For Gmail, create an app password.

export SMTP_USERNAME="agents@yourco.com"
export SMTP_PASSWORD="your-app-password"

The examples below use Gmail’s servers. Change smtp_host and imap_host for another provider. Microsoft 365 and Outlook.com are not supported, because they no longer accept passwords over IMAP.

from swarms import SmtpChannel


def thread(subject: str) -> SmtpChannel:
    return SmtpChannel(
        from_address="agents@yourco.com",
        to="you@yourco.com",
        smtp_host="smtp.gmail.com",
        imap_host="imap.gmail.com",
        mailbox="[Gmail]/All Mail",
        subject=subject,
    )

Two agents email you

from swarms import Agent

channel = thread("EV battery market report")

researcher = Agent(
    agent_name="Researcher",
    system_prompt="You gather facts and figures. Answer in a short bullet list.",
    model_name="gpt-5.4",
    max_loops=1,
    channel=channel,
)
writer = Agent(
    agent_name="Writer",
    system_prompt="You turn the facts in the conversation into a short report.",
    model_name="gpt-5.4",
    max_loops=1,
    channel=channel,
)

task = "Report on the EV battery market."
researcher.run(task)
writer.run(task)

Your inbox gets one thread with three emails: the task, the Researcher’s facts and the Writer’s report. Each carries an X-Swarms-Agent header with the speaker’s name.

Reply to steer the next run

The agents read the thread before every run, so your reply becomes context.

import time

from swarms import Agent

channel = thread("Press release draft")

drafter = Agent(
    agent_name="Drafter",
    system_prompt="You write and revise press releases.",
    model_name="gpt-5.4",
    max_loops=1,
    channel=channel,
)
drafter.run("Draft a press release for our Q3 product launch.")

print("Reply to the email with your feedback ...")
while not any(m["agent_name"] == "you@yourco.com" for m in channel.messages()):
    time.sleep(30)

drafter.run("Revise the draft using the feedback in the thread.")

Your reply is read back under your address, with the quoted history below it removed. The revised draft arrives in the same thread.

A SequentialWorkflow report by email

from swarms import Agent, SequentialWorkflow

workflow = SequentialWorkflow(
    agents=[
        Agent(
            agent_name="Researcher",
            system_prompt="Gather the key facts as a short bullet list.",
            model_name="gpt-5.4",
            max_loops=1,
        ),
        Agent(
            agent_name="Analyst",
            system_prompt="Weigh the facts in the conversation and state the main risk.",
            model_name="gpt-5.4",
            max_loops=1,
        ),
        Agent(
            agent_name="Writer",
            system_prompt="Turn the conversation into a three-paragraph brief.",
            model_name="gpt-5.4",
            max_loops=1,
        ),
    ],
    max_loops=1,
    channel=thread("Weekly EV market brief"),
)
workflow.run("Report on the EV battery market this week.")

Each step is one email, so you can read the research and the analysis behind the final brief.

A PlannerWorkerSwarm that reports its progress

from swarms import Agent
from swarms.structs.planner_worker_swarm import PlannerWorkerSwarm

workers = [
    Agent(
        agent_name="Market-Worker",
        agent_description="Market sizing and competitors.",
        model_name="gpt-5.4",
        max_loops=1,
    ),
    Agent(
        agent_name="Pricing-Worker",
        agent_description="Pricing and packaging.",
        model_name="gpt-5.4",
        max_loops=1,
    ),
]

swarm = PlannerWorkerSwarm(
    agents=workers,
    planner_model_name="gpt-5.4",
    max_loops=1,
    channel=thread("Go-to-market plan"),
)
swarm.run("Draft a go-to-market plan for a B2B analytics product.")

The thread receives the task, the planner’s plan, each worker’s result and the cycle judge’s verdict.

Pick up the thread later

Save thread_id after the first post and pass it back to join the same thread from another process:

saved = channel.thread_id  # "<swarms-...@yourco.com>"

later = SmtpChannel(
    from_address="agents@yourco.com",
    to="you@yourco.com",
    smtp_host="smtp.gmail.com",
    imap_host="imap.gmail.com",
    mailbox="[Gmail]/All Mail",
    thread_id=saved,
)

Tips

Keep runs coarse. Every agent run logs into IMAP to read the thread.
Wait for delivery between processes. A second SmtpChannel sees a post only after the mailbox has received it.
Treat replies as untrusted input. Anyone who replies on the thread adds to what the agents read.

Next steps

AgentMailChannel, the same pattern through the AgentMail API
Channels with every structure

Index

Basic Examples

Model Providers

Single Agent

Tree of Thoughts

Multi-Agent Examples

Comms Channels

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

SmtpChannel Quickstart

Setup

Two agents email you

Reply to steer the next run

A SequentialWorkflow report by email

A PlannerWorkerSwarm that reports its progress

Pick up the thread later

Tips

Next steps

​Setup

​Two agents email you

​Reply to steer the next run

​A SequentialWorkflow report by email

​A PlannerWorkerSwarm that reports its progress

​Pick up the thread later

​Tips

​Next steps

Setup

Two agents email you

Reply to steer the next run

A SequentialWorkflow report by email

A PlannerWorkerSwarm that reports its progress

Pick up the thread later

Tips

Next steps