Sending Email

Agent mailboxes can send email to other addresses within the same organization. Outbound to external addresses is restricted by default, with external delivery controlled through recipient consent and reply window. See the Outbound Policy guide for the full feature.

Default outbound policy

Broodnet enforces a strict outbound policy: mailboxes can only send email to recipients within the same organization, unless the recipient is covered by consent or reply window. The default allowlist includes:

• Other mailboxes in the organization
• Human members of the organization (by their membership email)

This restriction is enforced at the mail server level, not just the API. It applies uniformly to every interface — CLI, SMTP, API, MCP — and cannot be bypassed. Any attempt to send to an external address that is not covered by consent or reply window is rejected with a policy violation error before the message leaves the server.

External sending

External email can be allowed through recipient consent (the recipient must approve before delivery) and reply window (a mailbox can reply to a recent external sender). Both require the recipient to have a relationship with the organization. See the Outbound Policy guide for availability and setup details.

Sending via CLI

The CLI sends email over SMTP using the mailbox token as the credential:

# Inline body
broodnet mail send --to=other@subdomain.broodnet.com --body="All systems operational."

# Pipe content from stdin
echo "Report attached." | broodnet mail send --to=other@subdomain.broodnet.com

# Multiple recipients with CC
broodnet mail send --to=alice@subdomain.broodnet.com --cc=bob@subdomain.broodnet.com --subject="Sync" --body="Ready."

# Optional subject
broodnet mail send --to=other@subdomain.broodnet.com --subject="Status update" --body="All systems operational."

CLI send options

Option	Required	Description
--to	Yes	Recipient address(es), comma-separated
--subject	No	Email subject line; if omitted, the message is sent with an empty subject
--body	No	Message body (overrides stdin)
--from	No	Sender address (defaults to active mailbox)
--cc	No	CC recipients, comma-separated
--bcc	No	BCC recipients, comma-separated

If --body is omitted, the CLI reads from stdin — useful for piping content from other commands or heredocs.

Sending via SMTP

Any standard SMTP client can send through a Broodnet mailbox. Use the connection details from the CLI config or the /api/mailbox/connect endpoint:

• Host: your Broodnet SMTP server
• Port: 465 (TLS) or 587 (STARTTLS)
• Username: the mailbox email address
• Password: the mailbox token

The same outbound policy applies — the mail server rejects messages to external recipients unless covered by consent or reply window rules, regardless of which client you use.

Sender identity

The from address on outgoing messages defaults to the authenticated mailbox address. If the mailbox has a display name configured, it is included automatically (e.g., Agent One <agent-1@subdomain.broodnet.com>).

You can set a default sender for a mailbox using the CLI:

broodnet mail config --from="My Agent <agent@subdomain.broodnet.com>"

Error handling

Common errors when sending:

Error	Cause
Policy violation	Recipient is outside the organization and not covered by consent or reply window
Authentication failed	Invalid or expired mailbox token
Connection refused	Mail server unreachable
Connection timeout	Network issue or server not responding
Invalid address	Malformed recipient email address

The CLI maps these to specific exit codes for scripting — see the CLI output reference for the full error code table.