Superkabe LogoSuperkabe

State Machine

Understand mailbox states, domain states, and valid transitions through the protection lifecycle

Mailbox States

Mailboxes transition through several states based on bounce thresholds and cooldown periods:

healthy

Default state. Mailbox is actively sending.

Bounce count: < 3 within 60 sends

Can send: Yes

Gate allows: Yes

warning

Early warning state. Issue detected.

Bounce count: ≥3 within 60 sends

Can send: Yes (monitored)

Gate allows: Yes

warming

New mailbox being warmed up.

Bounce count: N/A

Can send: Limited volume

Gate allows: Gradual ramp

paused

Automatically paused due to bounce threshold.

Bounce count: ≥5 within 100 sends

Can send: No

Gate allows: No (blocked)

recovering

Cooldown period expired, gradual recovery.

Bounce count: Sliding window healing

Can send: Yes (gradual)

Gate allows: Yes (monitored)

active

Generic active state (legacy).

Can send: Yes

Gate allows: Yes

Mailbox State Transitions


    ┌─────────┐
    │ warming │
    └────┬────┘
         │
         ▼
    ┌─────────┐    3 bounces/60 sends    ┌─────────┐
    │ healthy ├────────────────────────►  │ warning │
    └────▲────┘                           └────┬────┘
         │                                     │
         │                                     │ 5 bounces/100 sends
         │                                     ▼
         │                                ┌────────┐
         │          cooldown expired      │ paused │
         │         ◄──────────────────────┤        │
         │                                └────────┘
         │                                     │
         │                                     │
    ┌────┴───────┐                            │
    │ recovering │◄───────────────────────────┘
    └────────────┘

Domain States

Domains aggregate mailbox health and have their own state machine:

healthy

Condition:

< 30% mailboxes unhealthy

warning

Condition:

≥30% mailboxes unhealthy

paused

Condition:

≥50% mailboxes unhealthy

Domain State Transitions


    ┌─────────┐    30% unhealthy    ┌─────────┐    50% unhealthy    ┌────────┐
    │ healthy ├────────────────────► │ warning ├────────────────────► │ paused │
    └────▲────┘                      └────▲────┘                      └────┬───┘
         │                                │                                │
         │ <15% unhealthy                 │ <15% unhealthy                 │
         └────────────────────────────────┴────────────────────────────────┘
                                     (gradual recovery)

Lead States

Leads also have states based on execution gate results:

held

Lead received from Clay, waiting for gate check.

active

Passed execution gate, sent to campaign.

paused

Blocked by gate due to HEALTH_ISSUE.

completed

Outreach finished, no longer monitored.

State Transition Events

All state transitions are logged in the state_transitions table:

Transition Record

{ "entity_type": "mailbox", "entity_id": "mb_123", "from_state": "healthy", "to_state": "paused", "reason": "Exceeded 5 bounces within 100 sends", "triggered_by": "bounce_threshold" }

🔍 Audit Trail

Every state change is logged with:

  • • Timestamp of transition
  • • Previous and new state
  • • Reason for transition
  • • Triggering event or threshold

This provides complete infrastructure forensics for debugging and compliance.