Receiving Email

Agent mailboxes accept inbound email from any sender on the internet. Messages are delivered to the mailbox and can be retrieved via the CLI, any IMAP client, or the REST API (coming soon).

How inbound mail works

When someone sends an email to a Broodnet mailbox address:

1. The message arrives at the Broodnet mail server via standard SMTP
2. The server routes it to the correct mailbox based on the address
3. The message is stored and becomes available for retrieval
4. An audit event is recorded (sender address, subject, timestamp)

No configuration is needed — inbound delivery works from the moment a mailbox reaches synced status. Any email address on the internet can send to a Broodnet mailbox.

Reading messages with the CLI

Check your inbox

broodnet mail inbox

This shows a summary table of recent messages with UID, flags, sender, subject, and date.

Inbox options

Option	Default	Description
--limit	20	Messages per page
--offset	0	Pagination offset
--sort	newest	Sort order: newest or oldest
--unread	—	Show only unread messages
--read	—	Show only read messages
--important	—	Show only flagged messages
--answered	—	Show only replied-to messages
--json	—	Output as JSON

Open a message

broodnet mail open <uid>

Opens a message by its UID (shown in the inbox listing). Displays the full message — headers, subject, and body. Opening a message marks it as read.

Option	Description
--raw	Print the raw RFC 822 source instead of formatted output
--json	Output structured JSON (headers, body, flags, attachments)

Wait for a new message

broodnet mail watch

A convenience command designed for OTP and verification code workflows. It checks the inbox for a message that arrived within the last 60 seconds. If none is found, it polls every 3 seconds for up to 60 seconds, then opens the first new message that arrives.

Note

watch is ideal for automated flows where an agent triggers an action that sends a verification email and needs to read the code immediately.

Using IMAP directly

Any standard IMAP client can connect to a Broodnet mailbox. Use the connection details from the CLI or the connect endpoint:

• Host: your Broodnet IMAP server
• Port: 993 (IMAPS / TLS)
• Username: the mailbox email address
• Password: the mailbox token

This means tools like mutt, neomutt, or any email client can read a Broodnet mailbox. See the CLI alternatives guide for setup examples.

Message flags

Messages support standard IMAP flags:

Flag	Meaning	CLI display
Seen	Message has been read	○ (unread) / ● (read)
Answered	Message has been replied to	↩
Flagged	Message marked as important	★
Forwarded	Message has been forwarded	⤴

Mailbox status

Check storage usage and message counts:

broodnet mail status

Shows the mailbox address, quota usage, total message count, and whether IMAP/SMTP access is active. Use --sync to refresh the data from the mail server.

Webhooks (planned)

Push-based notification for new messages via webhooks is on the roadmap but not yet available. Currently, the recommended approach is polling via the CLI watch command or IMAP IDLE for real-time notification.