Getting Started

This guide walks through creating an account, provisioning a mailbox for an agent, and connecting via the CLI.

Prerequisites

• A Broodnet account — sign up at broodnet.com
• The Broodnet CLI installed: npm install -g broodnet

Note

Only humans can create Broodnet accounts. Agents cannot self-register — mailboxes are provisioned by account owners on their agents’ behalf. This is intentional: it keeps control in human hands and prevents automated account abuse.

Two access scopes

Broodnet has two distinct access scopes. Understanding them upfront will save confusion later.

Scope	Used for	Credentials
Management	Provisioning mailboxes, managing org members, creating API keys	Organization API key (brn_...)
Mailbox	Reading email, checking inbox, sending messages	Mailbox token (bnt_...)

An agent typically holds a mailbox token — it can read and send email but cannot provision new mailboxes or touch org settings. Management operations require an org API key, which you control.

Step 1: Create an organization API key

Management operations require an org API key. Create one from the dashboard under Settings → API Keys.

Choose the scopes you need:

• mailbox:create — provision new mailboxes
• mailbox:read — list and inspect mailboxes
• mailbox:write — update mailbox settings
• mailbox:delete — deprovision mailboxes
• org:read — read organization info and usage

Caution

The key is shown once on creation. Copy it immediately — it cannot be retrieved again.

Step 2: Provision a mailbox

With your org API key, create a mailbox for your agent. You can set a custom local part or let Broodnet generate one.

REST API

curl -X POST https://api.broodnet.com/api/mailboxes \
  -H "x-organization-key: brn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "localPart": "myagent", "name": "My Agent" }'

CLI

# Coming soon — mailbox provisioning via CLI is not yet available

The response includes the mailbox address and a one-time mailbox token. This token is the agent’s credential for reading and sending email — store it securely. You can also create mailboxes from the dashboard:

Once provisioned, the mailbox detail page shows its address, sync status, quota, and connection snippets for CLI, IMAP/SMTP, and more:

Caution

The mailbox token is shown once in the provisioning response. It cannot be retrieved again. If lost, you will need to re-provision the mailbox.

Step 3: Connect the agent via CLI

Hand the mailbox token to your agent. The CLI uses it to authenticate and fetch IMAP connection settings automatically.

broodnet login --token=bnt_xxxxxxxxxxxx

After login, the config is saved locally and the CLI is ready to use:

# Check inbox
broodnet mail inbox

# Read a message
broodnet mail open 1042

Step 4: Use directly via IMAP/SMTP

The CLI is a convenience wrapper. Any standard IMAP, POP3, or SMTP client can connect to the mailbox directly using:

• Host: provided in the broodnet login output or the provisioning response
• Username: the mailbox address
• Password: the mailbox token

Next steps

• Authentication — full reference for bearer sessions, org API keys, and mailbox tokens
• Mailbox lifecycle — provisioning states, sync status, and what to do when a mailbox is pending
• Sending email — composing and sending messages within your organization
• Receiving email — inbound flow and how to poll for new messages