Receive emails
List, fetch, and label incoming mail with the Mailgent SDK
Anything sent to your project's <prefix>@mailgent.dev address lands in your Mailgent inbox, parsed and ready to read. This page walks the Buyer side: list unread mail, read what came in, and label it processed so your agent doesn't pick it up twice.
Before you start
- A project at console.mailgent.dev with Mail turned on.
- Your inbox address (e.g.,
agent-x8k2m@mailgent.dev). Send a test message to it from any email client before running the snippets — otherwise your inbox is empty.
npm install @mailgent/sdk # Node, Bun, Deno
pip install mailgent-sdk # PythonProcess the inbox
The full read flow in one example: list unread messages, hand the body to your agent logic, then mark the message processed so it falls out of the next unread query. unread is the default label on every received message until you remove it. Labels are free-form — unread, read, sent, and received are managed by Mailgent; anything else you add is yours (e.g., triaged, escalated, customer-support).
import { Mailgent } from "@mailgent/sdk";
const mailgent = new Mailgent({ apiKey: process.env.MAILGENT_API_KEY! });
const { messages, count } = await mailgent.mail.listMessages({
limit: 20,
labels: "unread",
});
for (const m of messages) {
// m.from and m.to are string[]. m.text is the full body;
// m.extractedText is the new content with quoted history + signatures stripped —
// that's the field to feed an LLM.
console.log(m.messageId, m.from, m.subject);
console.log(m.extractedText);
// Once handled, swap the labels.
await mailgent.mail.updateLabels(m.messageId, {
addLabels: ["read"],
removeLabels: ["unread"],
});
}import os
from mailgent import Mailgent
mailgent = Mailgent(api_key=os.environ["MAILGENT_API_KEY"])
result = mailgent.mail.list_messages(limit=20, labels="unread")
for m in result["messages"]:
# m.from_addrs and m.to are list[str]. m.text is the full body;
# m.extracted_text is the new content (quoted history + signatures stripped).
print(m.message_id, m.from_addrs, m.subject)
print(m.extracted_text)
mailgent.mail.update_labels(
m.message_id,
add_labels=["read"],
remove_labels=["unread"],
)Messages come newest-first. To paginate, pass pageToken (page_token in Python) from the previous response back in on the next call.
If you only have a messageId (typically from a webhook or stored reference), call mailgent.mail.getMessage(messageId) / get_message(message_id) to fetch a single parsed message instead.