Kumo Shaping

Kumo Shaping is PostMTA's epoch-based sending-rate control system. It replaces iptables-based throttling with a Kumo-native engine that models ISP delivery windows, reputation tiers, and warmup curves as first-class primitives. Every subuser operates inside a shaping epoch that governs how many messages per day may be injected into the transport layer.

Kumo-Native vs iptables

Legacy MTA shaping used iptables rules to meter connection counts and message injection rates at the kernel level. This approach is opaque, stateless, and ISP-agnostic. Kumo Shaping runs entirely in user space and exposes a programmable API.

Epoch Model

Each subuser occupies exactly one active epoch at any given time. The epoch encodes three signals:

• sent_today — cumulative messages injected so far in the current UTC calendar day.
• epoch_number — the current tier in the warmup ladder (1 = coldest, 10 = fully warmed).
• next_epoch_at — UTC timestamp when the next epoch promotion (or demotion) is scheduled.

Epoch State Fields

Apply Shaping Policy via API

Operators can apply a named shaping policy to a subuser. Valid policy names are conservative, moderate, and aggressive. Each policy encodes a different warmup ladder trajectory.

POST /v1/shaping/apply
Content-Type: application/json
Authorization: Bearer pmta_live_...

{
  "subuser_id": "sub_usr_01HX...",
  "policy": "aggressive",
  "override": false,
  "reason": "campaign_launch"
}

Response:

{
  "epoch_id": "ep_01HX9P7N3M4Q6R8T2V4W6Y8",
  "subuser_id": "sub_usr_01HX...",
  "policy": "aggressive",
  "sent_today": 0,
  "epoch_number": 1,
  "next_epoch_at": "2026-07-18T12:00:00Z",
  "rate_limit": 5000,
  "warmup_stage": "stage_1",
  "applied_by": "operator@example.com",
  "applied_at": "2026-07-18T00:00:00Z"
}

Warmup Ladder

New subusers or subusers with degraded reputation start at epoch 1. Each epoch has a defined daily send cap and a minimum dwell time before promotion is allowed. Promotion requires a positive reputation delta and no active suppression flags. Demotion occurs automatically if hard bounce rate exceeds 3% or complaint rate exceeds 0.1% over a rolling 7-day window.

Manual Epoch Override

Operators may manually promote or demote a subuser's epoch using the override endpoint. Overrides trigger a mandatory cooldown period of 30 minutes (promotions) or 120 minutes (demotions) before another override can be issued, preventing accidental rapid cycling.

POST /v1/shaping/override
Content-Type: application/json
Authorization: Bearer pmta_live_...

{
  "subuser_id": "sub_usr_01HX...",
  "target_epoch": 5,
  "reason": "emergency_auction_reminder",
  "duration_minutes": 60
}

Response:

{
  "override_id": "ovr_01HX...",
  "subuser_id": "sub_usr_01HX...",
  "previous_epoch": 3,
  "target_epoch": 5,
  "cooldown_until": "2026-07-18T04:30:00Z",
  "reason": "emergency_auction_reminder",
  "applied_at": "2026-07-18T03:30:00Z"
}

Suppression Pipeline Order

When a message is submitted to Kumo Shaping, it passes through a deterministic filter stack. The order matters:

1. Global blocklist — Hard blocks from internal blocklists, RFC 2606 reserves, and PMH-SEC-026 policy.
2. Subuser suppression list — Recipient addresses explicitly suppressed by the subuser.
3. Complaint cache — FBL-derived complaints with a 30-day TTL from last seen date.
4. Bounce cache — Known hard/soft bounces with TTLs of 7 days (hard) and 1 day (soft).
5. Epoch check — Is sent_today below current epoch cap? If yes, proceed; otherwise queue.
6. Reputation gate — Is reputation_score ≥ epoch_number × 0.1? If yes, proceed.
7. ISP-specific routing — Apply per-ISP delivery windows and concurrency limits.
8. Inject to transport — Message is handed off to the MTA transport layer.

Messages that fail the epoch check or reputation gate are held in the shaping queue and retried at the next epoch window boundary (top of each UTC hour) without 计 time penalty against the subuser.

Reputation-Shape Coupling

Kumo Shaping enforces a hard coupling between the reputation score and the maximum accessible epoch. This prevents high-volume subusers from continuing to send at full capacity when their reputation is degrading.

• Reputation score ≥ 0.95 — Full access to all epochs; unlimited sends at epoch 10.
• Reputation score 0.80 – 0.94 — Capped at epoch 8 even if epoch_number in DB is higher.
• Reputation score 0.60 – 0.79 — Capped at epoch 6; promotion ladder paused.
• Reputation score 0.30 – 0.59 — Capped at epoch 3; subuser flagged for review.
• Reputation score < 0.30 — Capped at epoch 1; all sends held pending operator review (PMH-SEC-031).

Checking Epoch Status via SQL

SELECT
  subuser_id,
  sent_today,
  epoch_number,
  next_epoch_at,
  warmup_stage,
  reputation_score
FROM shaping_epochs
WHERE subuser_id = 'sub_usr_01HX...'
  AND date(next_epoch_at) = CURRENT_DATE
ORDER BY epoch_number DESC
LIMIT 10;

ISP-Specific Delivery Windows

Kumo Shaping enforces per-ISP delivery windows that reflect each ISP's accepted sending patterns. These windows are hard limits enforced at the transport layer, not just shaping limits.

Queue Priority Tiers

Messages held by Kumo Shaping (waiting for epoch window or reputation gate) are ordered by queue priority. Priority is set at injection time and cannot be changed while in queue. Higher priority messages are processed first when the shaping gate opens.

Messages that exceed their maximum queue time are moved to the DLQ with reason max_queue_time_exceeded. Transactional and critical messages are never downqueued to a lower priority tier.

Monitoring Shaping State

Real-time Metrics API

GET /v1/shaping/metrics?subuser_id=sub_usr_01HX...
Authorization: Bearer pmta_live_...

{
  "subuser_id": "sub_usr_01HX...",
  "current_epoch": 5,
  "sent_today": 8432,
  "epoch_cap": 15000,
  "pct_used": 56.2,
  "reputation_score": 0.72,
  "epoch_promotion_due": "2026-07-19T00:00:00Z",
  "active_queue_messages": 312,
  "queue_breakdown": {
    "critical": 0,
    "transactional": 12,
    "standard": 245,
    "marketing": 55,
    "batch": 0
  },
  "suppression_snapshot": {
    "addresses_suppressed": 1842,
    "addresses_suppressed_today": 14
  }
}

Promotion and Demotion Alerts

Configure alerting on the following shaping events to monitor subuser health:

• Epoch demotion: Triggered when reputation threshold crossed. Alert threshold: immediate PagerDuty for demotions beyond epoch 3.
• Complaint rate warning: complaint_rate_pct > 0.08% in rolling 7-day window.
• Bounce rate warning: Hard bounce rate > 1.5% over 3-day rolling window.
• Queue depth warning: More than 1,000 messages queued for a single subuser for more than 2 hours.
• Epoch cap reached: sent_today reaches 95% of epoch_cap before 18:00 UTC.

Policy Reference