Autonomy Levels

Autonomy levels let you control how much human approval is required before an agent can send email from a mailbox. This is a per-mailbox setting that governs the balance between speed and oversight.

Levels

The default autonomy level for new mailboxes is L3 (Fully Autonomous).

How it works

When an agent sends an email, the autonomy level is evaluated after policy checks but before the email is queued for delivery:

1. The send request passes through the policy engine (duplicate detection, rate limits, suppressions, etc.)
2. If the policy allows the send, the mailbox's autonomy level is checked
3. Based on the level, the send is either queued immediately or routed to the approval queue

The same gate applies to journey send steps, not only direct API sends: they are held for approval the same way. A journey step with no mailbox configured is gated by your default mailbox. While your account or the mailbox is paused, journey steps and scheduled follow-ups wait and are retried every 15 minutes; after 72 hours paused they are dropped (the journey run fails with paused_timeout).

L1 - Assisted

All sends are held for human approval regardless of prior contact history. This is the most conservative setting, ideal for high-stakes mailboxes or early-stage agent deployments where you want full visibility.

L2 - Guarded Auto

The system checks whether the mailbox has ever actually delivered a message to the recipient, or received one from them. If neither has happened yet, it requires approval. A held or policy-blocked draft to a new recipient does not count as contact by itself -- only a message that actually went out (or one they sent in) does, so a still-unreviewed draft can't be resent under another template, as a reply, or after a rejection to slip past the hold.

This balances safety with throughput -- agents can continue existing conversations freely, but new outreach is supervised.

L3 - Fully Autonomous

No autonomy-based approval is required. Sends execute as long as they pass policy checks. This is the right choice for production mailboxes with well-tested agents and established sending patterns.

Setting the autonomy level

Via the API

curl https://api.molted.email/v1/agent/mailboxes/:id/autonomy?tenantId=TENANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "autonomyLevel": 2,
  "description": "First-contact approval -- only first message to a new recipient requires approval"
}

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/:id/autonomy?tenantId=TENANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "autonomyLevel": 1 }'

You can also set the autonomy level when updating a mailbox via PATCH /v1/agent/mailboxes/:id:

curl -X PATCH https://api.molted.email/v1/agent/mailboxes/:id?tenantId=TENANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "autonomyLevel": 2 }'

An agent key may lower a mailbox's autonomy at any time. Raising it (1 to 2, 2 to 3) gives the agent more freedom, so it is a human decision: the API answers 403 human_decision_required with a decisionUrl (kind: "autonomy") for a person to make the change in the portal. See Loosening a control.

Via the CLI

molted mailboxes autonomy MAILBOX_ID

molted mailboxes autonomy set MAILBOX_ID --level 2

The --level flag is required. Valid values are 1, 2, or 3.

Command structure note: autonomy is a parent command with a set subcommand. To view the current level, pass the mailbox ID directly: molted mailboxes autonomy MAILBOX_ID. To set the level, use the set subcommand: molted mailboxes autonomy set MAILBOX_ID --level <n>. You only provide the mailbox ID once in each case.

Via the Portal

Open the mailbox's page (press ⌘K and type its name, or pick it in Settings) and choose its approval rule: Asks every time (level 1), Asks for new contacts (level 2) or Sends freely (level 3). Loosening the rule is a person's decision; an agent can only tighten it.

Approval flow

When a send is held for approval due to the mailbox's autonomy level, it appears in the approval queue. Approvals can be managed via:

• The portal's Home page, where each held send waits as a decision card
• The Approval Queues API - inspect queue counts, release, reject, edit, and escalate held messages

Pending approvals expire after the configured timeout (default: 24 hours). Expired sends are not delivered.

Choosing the right level