Shaping & Warmup Policy
PostMTA uses a Kumo-native shaping system driven by epoch bumps and warmup ladders. Shaping controls the rate at which a workspace can inject messages into the delivery network. Warmup is the process of gradually increasing an IP or domain's sending quota to build reputation with recipient mail servers.
Epoch System Overview
An epoch is a named, tiered sending bucket that defines a maximum delivery rate. Each epoch has:
- A daily volume ceiling (e.g., 500 emails/day)
- A burst allowance (up to 4x the daily ceiling over a rolling 1-hour window)
- A priority level for queue scheduling
Workspaces start at epoch 0 (minimal sending) and are bumped to higher epochs as their sending history and reputation grow. Epoch bumps can be manual (operator-initiated) or automatic (triggered by sustained good behaviour).
Epoch Reference
| Epoch | Name | Daily Ceiling | Burst Allowance | Priority | Typical Stage |
|---|---|---|---|---|---|
epoch_0 | Cold Start | 100 | 50/hr max burst | lowest | New domain, new IP |
epoch_1 | Warmup | 500 | 200/hr max burst | low | Days 8-14 |
epoch_2 | Ramp | 5,000 | 1,000/hr max burst | normal | Days 15-21 |
epoch_3 | Production | 20,000+ | 4x daily / 1hr rolling | high | Day 22+ |
epoch_custom | Custom | Configured | Configured | configured | Enterprise tiers |
Warmup Ladder
The warmup ladder defines the rate at which a new sending identity (IP address or sending domain) increases its daily sending quota over a 30-day ramp. This gradual increase gives recipient mail servers time to learn to accept mail from the new source.
Warmup Schedule
| Phase | Days | Daily Volume | Target Recipients/Day | Notes |
|---|---|---|---|---|
| Phase 1 | Days 1-7 | 100/day | 100 | Seed with major providers (Gmail, Microsoft) first to build seed reputation |
| Phase 2 | Days 8-14 | 500/day | 500 | Expand to secondary providers and ISP addresses |
| Phase 3 | Days 15-21 | 5,000/day | 5,000 | Broad sending. Monitor bounce rates carefully. |
| Phase 4 | Days 22-30 | 20,000+/day | 20,000+ | Full production volume. Epoch bump to production recommended. |
Apply Shaping Policy
To manually set the epoch or warmup schedule for a workspace, sending domain, or IP pool, POST to the policy apply endpoint:
curl -X POST https://api.postmta.com/v1/panel/policy/apply \
-H "Authorization: Bearer pmta_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"target_type": "workspace",
"target_id": "ws_01HXABC123DEF456",
"policy": {
"epoch": "epoch_2",
"warmup_ladder": "default_30day",
"burst_enabled": true,
"max_burst_multiplier": 4
},
"apply_at": "2026-07-18T12:00:00Z",
"reason": "Customer upgraded to Growth plan"
}'Response:
{
"policy_job_id": "pj_01HXPOLICY001",
"target_type": "workspace",
"target_id": "ws_01HXABC123DEF456",
"previous_epoch": "epoch_1",
"new_epoch": "epoch_2",
"scheduled_at": "2026-07-18T12:00:00Z",
"status": "scheduled"
}Policy Jobs
Policy changes are executed as asynchronous jobs. You can query the status of a policy job:
curl https://api.postmta.com/v1/panel/policy/jobs/pj_01HXPOLICY001 \
-H "Authorization: Bearer pmta_live_xxxxxxxxxxxxxxxx"Job Types
| Job Type | Description | Typical Duration |
|---|---|---|
epoch_bump | Move a workspace, domain, or IP from one epoch to another. Re-calculates shaping limits and updates queue schedulers. | 30-60 seconds |
warmup_apply | Assign or update the warmup ladder for an IP or sending domain. Triggers the daily volume schedule. | 60-120 seconds |
shape_reset | Emergency reset of shaping to epoch_0. Used when a sending domain or IP is suddenly blocklisted or reputation-collapses. | Immediate |
Suppression Enforcement at INJECT Time
When a message is injected into the delivery pipeline, PostMTA checks the recipient against the workspace suppression list in real time. Suppressed recipients are rejected at INJECT, not at send time. This prevents wasted delivery attempts and protects sender reputation.
Suppression checks cover:
- Hard bounces (permanent failures — never retried)
- Complaint/FBl entries (recipient marked the message as spam)
- Explicit unsubscribes (List-Unsubscribe confirmed)
- Operator-initiated suppression (manual block)
{
"suppression_result": "rejected",
"reason": "hard_bounce",
"suppressed_at": "2026-07-18T10:05:32Z",
"original_bounce_code": "550 5.1.1 User unknown",
"original_bounce_at": "2026-07-15T08:12:00Z"
}Messages rejected at INJECT due to suppression do not consume a credit — the HOLD is automatically VOIDed and the credits are returned to the balance.
Verified From Requirement in Production
All production sends (epoch_2 and above) must use a Verified From address. A Verified From address is one where the sending domain has passed DKIM, SPF, and DMARC verification and has been confirmed by PostMTA's verification flow.
POST /v1/domains, PostMTA generates the DKIM record and guides you through DNS setup. Verification is complete when all three DNS records (DKIM, SPF, DMARC) are confirmed present and valid.Attempts to send from an unverified domain in a production epoch return:
{
"error": "unverified_sending_domain",
"code": 400,
"message": "Sending from 'mail.unverified.com' requires domain verification. See POST /v1/domains to add and verify this domain.",
"domain_status": "pending"
}View Current Policy State
curl https://api.postmta.com/v1/panel/policy/current \
-H "Authorization: Bearer pmta_live_xxxxxxxxxxxxxxxx"Response:
{
"workspace_id": "ws_01HXABC123DEF456",
"current_epoch": "epoch_2",
"warmup_ladder": "default_30day",
"warmup_day": 18,
"current_daily_limit": 5000,
"burst_multiplier": 4,
"burst_current": 1834,
"burst_reset_at": "2026-07-18T11:00:00Z",
"suppression_list_count": 1247,
"last_epoch_bump_at": "2026-07-10T00:00:00Z",
"next_auto_bump_eligible": "2026-07-24T00:00:00Z"
}Shaping Policy Alerts
Configure alerts for:
- Burst threshold approaching (75% of burst allowance in a rolling 1-hour window)
- Bounce rate exceeds 2% in any rolling 24-hour window
- Complaint rate exceeds 0.1% in any rolling 24-hour window
- Auto-bump eligible (PostMTA recommends bumping to the next epoch)