Skip to main content

Overview

AgentMailChannel keeps a conversation as one email thread in an AgentMail inbox. Each post is an email from the inbox to the people in to: the first starts the thread and the rest reply in it. People on the thread can reply from their own mail client, and their replies join the conversation under their email address. It talks to the AgentMail REST API over HTTPS, so there is no SMTP or IMAP server to configure. With backend="resend", the same thread runs on Resend from your own verified domain instead (see Resend backend). To use a mailbox you already run, see SmtpChannel.

Import

Setup

  1. Create an account and an inbox at agentmail.to. The inbox id is its address, such as research@agentmail.to.
  2. Create an API key and export it:

Constructor

str
required
The inbox the agents send from, such as research@agentmail.to. On Resend, the address to send from, on a domain with sending and receiving verified.
str | List[str]
required
The address or addresses that get each post and can reply.
str
default:"Swarms conversation"
The subject of the first email.
str
default:"None"
An existing AgentMail thread to join instead of starting one. The first post then replies to the thread’s newest message. On Resend, the thread_id a channel saved earlier.
str
default:"None"
The backend’s API key. Defaults to AGENTMAIL_API_KEY, or to RESEND_API_KEY on Resend.
str
default:"None"
The API host. Defaults to https://api.agentmail.to (use https://api.agentmail.eu for the EU region), or https://api.resend.com on Resend.
float
default:"30.0"
Seconds to wait for each call.
str
default:"agentmail"
"agentmail" or "resend".
Raises: ValueError if backend is unknown, or if no API key is passed or set. The message names the variable to set.

Attributes

How messages are sent and read

AgentMail adds its own footer and the quoted thread to each email body. So that messages() can read a post back exactly, each post carries two headers: messages() reads every page of the thread and returns the messages oldest first: The two headers are trusted only on mail the inbox sent. A reply that sets X-Swarms-Agent itself is still attributed to its From address.

Resend backend

The key needs Full access: a “Sending access” key can send but gets 401 restricted_api_key when messages() reads received mail. inbox_id’s domain must be verified in Resend for sending, with receiving turned on (see the quickstart). Resend has no thread object, so the channel builds the thread itself:
  • Joining a thread with thread_id= from another process shows people’s replies and only the posts made through this instance.
  • Requests per read: one call per 100 received emails on the account, plus one call for each new email to inbox_id. Each email is fetched once per channel.
  • Replies are matched by References. Mail clients such as Gmail copy it into a reply. A client that leaves it out is not read.

Methods

post()

Send one email. The first post (with no thread_id) sends a new message with subject. Later posts reply to the channel’s previous post, so the thread stays in order.
Raises: httpx.HTTPStatusError on a non-2xx reply.

messages()

Read the whole thread, oldest first. Returns [] before the first post when no thread_id was given.
Raises: httpx.HTTPStatusError on a non-2xx reply.

clear()

Delete the thread from the inbox, so the next post starts a new one. Emails already delivered stay in the recipients’ mailboxes. On Resend, the thread is only forgotten locally: nothing is deleted.

close()

Close the connection pool. The thread stays in the inbox.

Usage Examples

A person approves before the swarm continues

Rejoin a thread later

More examples are in the AgentMailChannel quickstart.

Notes

  • Every read is an API call per page. An agent reads the channel on every run.
  • Treat replies as untrusted input. Anyone who can email the inbox and is on the thread can add to the conversation the agents read.

Source Code

View the source on GitHub.