Mailbox Lifecycle

Every mailbox goes through a provisioning lifecycle — from the initial API request to a fully active mailbox that can send and receive email.

Creating a mailbox

When you create a mailbox (via the dashboard, API, or CLI), Broodnet:

1. Reserves the address in the database with a pending sync status
2. Generates a mailbox token — shown exactly once in the response
3. Provisions the mailbox on the mail server (creates the account, sets up authentication)
4. Updates the sync status to synced on success, or failed if something went wrong

The token returned at creation is the credential for all mailbox-scoped access — IMAP, SMTP, CLI, and API. Store it securely. It cannot be retrieved again, only rotated.

Sync status

Every mailbox has a syncStatus field that tracks whether it has been successfully provisioned on the mail server:

Status	Meaning
pending	Mailbox created in the database, mail server provisioning in progress
synced	Mail server provisioning complete — mailbox is fully operational
failed	Provisioning failed — check syncError for details

A mailbox in pending or failed state cannot send or receive email. The lastSyncedAt timestamp records when the mailbox was last successfully synced.

Note

Most mailboxes reach synced within a few seconds of creation. If a mailbox stays in pending or moves to failed, check the sync error message for the cause.

Suspension

A mailbox can be suspended by an organization owner or admin. Suspended mailboxes:

• Cannot send or receive email
• Remain visible in the dashboard and API
• Retain all stored messages
• Can be unsuspended to restore full functionality

Suspension is a soft state — no data is deleted.

Token rotation

Mailbox tokens can be rotated at any time via the dashboard or API. When you rotate a token:

1. A new token is generated and the mail server password is updated immediately
2. The old token stops working instantly — all active IMAP/SMTP sessions using it will disconnect
3. The new token is shown once in the response

Rotation is useful when a token may have been exposed or when you want to revoke an agent’s access without deleting the mailbox.

Deleting a mailbox

Deleting a mailbox is permanent and irreversible:

1. The mailbox is deprovisioned from the mail server — all stored email is deleted
2. The database record is removed
3. The email address becomes available for reuse

Caution

Deletion cannot be undone. All messages in the mailbox are permanently lost. If you only need to temporarily disable a mailbox, use suspension instead.

Agent ownership

Mailboxes can optionally be assigned to an agent. An unassigned mailbox can be claimed by an agent through the agent auth flow. Once assigned:

• The agent can access the mailbox through its granted capabilities
• The mailbox appears in agent-scoped queries
• Deleting the agent releases the mailbox (it becomes unassigned again, not deleted)

Lifecycle summary

Create mailbox
     ↓
syncStatus: pending
     ↓
Mail server provisioning
     ↓
  ┌──────────────┐
  │   Success    │──→ syncStatus: synced ──→ Mailbox active
  └──────────────┘
  ┌──────────────┐
  │   Failure    │──→ syncStatus: failed (check syncError)
  └──────────────┘

Active mailbox can be:
  → Suspended (reversible, no data loss)
  → Token rotated (immediate credential change)
  → Deleted (permanent, all data removed)