Warm up a sending domain

A verified domain can send. Whether mailbox providers trust it at your normal volume is a separate question, and the answer comes from the mail itself: bounces, complaints, and deliveries observed as you send. Warming is how you introduce campaign traffic on a domain through an automated policy, with the domain's own evidence in front of you at each step.

Warming governs campaign runs only. Direct sends from the domain, such as receipts and password resets, are counted in the domain's window but are never delayed.

How it works

1. Start a policy on a verified domain. Say whether the domain is new, migrating from another provider, or returning after a quiet period. Set the first day's campaign-recipient allowance, a whole-percent daily growth rate, and the daily target cap.
2. Samva opens the first window immediately. It is a 24-hour capacity window with a sequence, allowance, and snapshot of the policy that authorized it. When a safe window closes, Samva opens the next window from that policy; it never opens overlapping windows or grows above the target.
3. Schedule campaigns as usual. Each page of recipients from a campaign run draws from the policy window that is open when that page is ready. A run whose next page finds no open window, or a window too small for that page, pauses and names the reason. The next system-created window resumes capacity-held runs when it can.
4. Read the evidence and tune the policy when needed. The domain's rolling 24-hour window shows sends, permanent bounces, and complaints against the same limits that pause an organization. Below 200 sends the window reads as not enough evidence yet, and nothing is decided from it.
5. Complete the policy when the domain is at its normal volume. Campaign runs are no longer staged in warming windows; the organization safeguards still apply.

The domain rule

Once a domain's window holds at least 200 sends, the domain rule holds the plan if either limit is crossed:

A hold stops campaign runs from the domain at their next page. It does not pause the organization or delay direct sends. The hold names the observed rate, and it lifts only when you resume the plan with the window back under both limits; resuming earlier is refused with the rate that still stands. An organization pause always overrides a plan.

From the dashboard

Open the domain and select Warming. The tab shows the verdict, the domain's window with its bounce and complaint meters, the open policy window with what campaign runs have reserved from it, every window and its policy snapshot, and the decision history. Start or tune the policy, pause, resume, and complete it from there.

From the API

import { Effect } from "effect";
import * as Email from "samva/effect/email";

const program = Effect.gen(function* () {
  yield* Email.createDomainWarmingPlan({
    id: "dom_...",
    identity: "new",
    initialDailyRecipients: 500,
    dailyGrowthPercent: 25,
    targetDailyRecipients: 5000,
  });
  const warming = yield* Email.updateDomainWarmingPolicy({
    id: "dom_...",
    dailyGrowthPercent: 20,
    targetDailyRecipients: 4000,
    note: "Reduce future growth while we compare this domain's recent campaign traffic",
  });
  console.log(warming.evidence.verdict, warming.batches);
});

curl -X PATCH https://api.samva.dev/v1/email/domains/dom_.../warming/policy \
  -H "x-api-key: $SAMVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "dailyGrowthPercent": 20, "targetDailyRecipients": 4000 }'

GET /v1/email/domains/{id}/warming returns the policy, its system-created windows with sequence, allowance, reserved and accepted recipients, and the policy snapshot that authorized each window. It also returns the window hour by hour with its verdict, any organization or provider pause above the policy, and the decision history. Pause, resume, complete, and cancel a scheduled or open window are separate endpoints under the same path. A campaign run the policy is holding reports the reason in holdReason and the domain in holdDomainId.

Every customer action and automatic policy or safety decision publishes a domain.warming.updated webhook. A window event includes its sequence, allowance, and policy snapshot.

Next steps