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
- Create an account and an inbox at agentmail.to. The inbox id is its address, such as
research@agentmail.to. - Create an API key and export it:
Constructor
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.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.The backend’s API key. Defaults to
AGENTMAIL_API_KEY, or to RESEND_API_KEY on Resend.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.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 thatmessages() 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
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 nothread_id) sends a new message with subject. Later posts reply to the channel’s previous post, so the thread stays in order.
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.
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
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.