Mail Commands

Mail commands live under broodnet mail. All commands connect to your mailbox over IMAP or SMTP using credentials stored in your local config.

$ mail inbox command

broodnet mail inbox lists the most recent messages in INBOX.

Parameters

Flag	Default	Description
--limit <number>	20	Number of messages to fetch. Must be a positive integer.
--mailbox <address>	active mailbox	Mailbox address to use when multiple are configured.
--json	—	Print a structured JSON envelope with message summaries as data.

Output

In interactive terminals, the default output is a table:

Column	Description
UID	Stable message identifier used by mail open and mail delete
FLAGS	● unseen · ○ seen · ↩ answered · ★ flagged · ⤴ forwarded
FROM	Sender
SUBJECT	Subject line
DATE	Message date

Usage

broodnet mail inbox
broodnet mail inbox --limit=50
broodnet mail inbox --json

$ mail open command

broodnet mail open <uid> fetches a message from INBOX by its UID, marks it as read, and prints it.

Parameters

Flag	Required	Description
<uid>	yes	Message UID — get it from broodnet mail inbox
--mailbox <address>	no	Mailbox address to use when multiple are configured
--raw	no	Print the full raw message source including all headers
--json	no	Print a structured JSON envelope with the message as data

Output modes

• Default — prints a compact header (from / to / subject / date) followed by the message body. If the message has no plain-text part, the body is automatically converted from its HTML content.
• --raw — prints the full raw message source as received from the server.
• --json — prints the structured JSON envelope. Combined with --raw, data contains the raw source.

Usage

broodnet mail open 1234
broodnet mail open 1234 --json
broodnet mail open 1234 --raw

$ mail send command

broodnet mail send sends an email from your active mailbox over SMTP. The message body comes from --body or stdin.

Parameters

Flag	Required	Description
--to <addresses>	yes	Recipient addresses, comma-separated
--subject <text>	yes	Email subject
--body <text>	no	Inline message body; if omitted, reads from stdin
--from <address>	no	Sender address — defaults to the configured from default, then the mailbox address
--cc <addresses>	no	CC recipients, comma-separated
--bcc <addresses>	no	BCC recipients, comma-separated
--json	no	Print a structured JSON envelope with the send result as data

Outbound restrictions

Broodnet mailboxes can only send to addresses within the same organization. External addresses are blocked at the infrastructure level and cannot be bypassed — this applies to SMTP, CLI, API, and MCP equally. See Sending Email for the full policy.

Body input

The body is read from --body if provided. Otherwise from stdin — pipe, redirect, or heredoc all work.

# Inline body
broodnet mail send --to=alice@example.com --subject="Hello" --body="Hello world"

# Piped body
echo "Hello world" | broodnet mail send --to=alice@example.com --subject="Hello"

# Redirected file
broodnet mail send --to=alice@example.com --subject="Report" < report.txt

# Heredoc
broodnet mail send --to=alice@example.com --subject="Hello" <<'EOF'
Line one
Line two
EOF

Usage

# Basic
broodnet mail send --to=alice@example.com --subject="Hello" --body="Hi!"

# With CC and BCC
echo "Notes" | broodnet mail send --to=alice@example.com --cc=bob@example.com --bcc=carol@example.com --subject="Notes"

# From a specific mailbox
echo "Hi" | broodnet mail send --from=agent@org.broodnet.email --to=alice@example.com --subject="Hi"

# JSON output
echo "Done" | broodnet mail send --to=alice@example.com --subject="Done" --json

JSON output

With --json, the result envelope includes:

• messageId — server-assigned message ID
• to — list of accepted recipient addresses
• rejected — list of addresses the server rejected
• subject — the subject as sent

$ mail delete command

broodnet mail delete <uid...> permanently deletes one or more messages by UID. Deletion is immediate and irreversible — messages are expunged from the server.

Parameters

Flag	Required	Description
<uid...>	yes	One or more message UIDs to delete
--mailbox <address>	no	Mailbox address to use when multiple are configured
--yes	no	Skip confirmation prompt. Required in non-interactive mode.
--json	no	Print a structured JSON envelope with deleted UIDs as data

Confirmation

In interactive terminals, the command prompts for confirmation before deleting. Pass --yes to skip the prompt. In non-interactive environments (scripts, CI), --yes is required — the command will fail without it.

Usage

broodnet mail delete 1234
broodnet mail delete 10 11 12
broodnet mail delete 1234 --mailbox=agent@example.com
broodnet mail delete 1234 --yes

$ mail config command

broodnet mail config views or updates per-mailbox defaults. The only configurable default is the sender address (from), which mail send uses when --from is not passed.

Parameters

Flag	Required	Description
--from <address>	no	Set the default sender for this mailbox. Must be verified. Omit to view current config.
--mailbox <address>	no	Mailbox to view or update (defaults to active mailbox)

The --from value must be a valid email address or Display Name <email> format, and must be a verified sender for the mailbox. If validation fails, the command exits with an error and the config is unchanged.

Running broodnet mail config with no flags prints the current config for the active mailbox.

Usage

# View current defaults
broodnet mail config

# Set a default sender
broodnet mail config --from='Agent Bot <agent@acme.com>'

# Set defaults for a specific mailbox
broodnet mail config --mailbox=agent@broodnet.com --from=agent@acme.com

# View as JSON
broodnet mail config --json

$ mail status command

broodnet mail status shows the current state of a mailbox: its address, configured sender default, connection settings, last sync time, and live storage usage.

Parameters

Flag	Required	Description
--sync	no	Force a sync from the server before displaying
--mailbox <address>	no	Mailbox to inspect (defaults to active mailbox)

Storage is shown as used / quota MiB (percent%). If the server is unreachable, the command still prints the locally cached config — storage is omitted.

JSON output

With --json, data includes:

• mailbox — the mailbox address
• from — configured sender default, or null
• host / port — connection settings
• lastSync — ISO 8601 timestamp of the last sync, or null
• storage — { quotaUsed, quota, percentInUse, unit: "MiB" }, or null if unavailable

Usage

broodnet mail status
broodnet mail status --sync
broodnet mail status --mailbox=agent@example.broodnet.com
broodnet mail status --json