Receive emails
List, fetch, and label incoming mail with the Loomal SDK
Anything sent to your project's <prefix>@mailgent.dev address lands in your Loomal 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.loomal.ai 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 @loomal/sdk # Node, Bun, Deno
pip install loomal-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 Loomal; anything else you add is yours (e.g., triaged, escalated, customer-support).
import { Loomal } from "@loomal/sdk";
const loomal = new Loomal({ apiKey: process.env.LOOMAL_API_KEY! });
const { messages, count } = await loomal.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 loomal.mail.updateLabels(m.messageId, {
addLabels: ["read"],
removeLabels: ["unread"],
});
}import os
from loomal import Loomal
loomal = Loomal(api_key=os.environ["LOOMAL_API_KEY"])
result = loomal.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)
loomal.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 loomal.mail.getMessage(messageId) / get_message(message_id) to fetch a single parsed message instead.