Entities (leads, mailboxes, domains, campaigns) each carry a state and transition through it via deterministic triggers. Mailbox states: healthy → warning → paused → quarantine → restricted_send → warm_recovery → healthy. Each transition has graduation criteria enforced by code, not timers.
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.
Frequently Asked Questions
Why separate quarantine, restricted_send, and warm_recovery?
+
Each phase has a different purpose: quarantine verifies DNS auth recovery, restricted_send proves the mailbox can produce clean sends at low volume, warm_recovery ramps back to full volume. Skipping any phase would risk reopening the original damage.
Who can force a state transition manually?
+
Admins can force graduations via the Mailboxes dashboard, but the action is logged and requires a reason. Transitions that bypass safety checks warn explicitly.