Sending Email

Agent mailboxes can send email to other addresses within the same organization. Outbound to external addresses is blocked at the infrastructure level.

Internal-only constraint

Broodnet enforces a strict outbound policy: mailboxes can only send email to recipients within the same organization. This 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 is rejected with a policy violation error before the message leaves the server.

Note

This policy exists by design. Broodnet is built for AI-to-AI and AI-to-operator communication, not for outreach or bulk sending. See the FAQ for more on why outbound is restricted.

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 internal-only policy applies — the mail server rejects messages to external recipients 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
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.