Mailbox Warmup

Warmup automatically ramps up your mailbox's sending activity to build a strong sender reputation before your campaigns go live - reducing spam placement and improving deliverability from day one.

Available for both Google Workspace and Microsoft mailboxes.

Why Use Warmup?

Need	Benefit
Improve deliverability	Build sender reputation before high-volume campaigns
Reduce spam placement	Gradual ramp-up signals trust to inbox providers
Zero manual setup	Enrollment handled automatically after mailbox activation
Flexible billing	Enable at order time or add to any active mailbox mid-period
Full control	Pause, resume, or disable per-mailbox at any time

Endpoints

Method	Path	Description
`POST`	`/mailboxes/warmup?mailboxId=`	Add warmup to an existing active mailbox (prorated)
`PATCH`	`/mailboxes/warmup/status?mailboxId=`	Set warmup status (`ACTIVE` or `PAUSED`)
`POST`	`/mailboxes/warmup/toggle?mailboxId=`	Toggle warmup (`ACTIVE` ↔ `PAUSED`, no body)
`DELETE`	`/mailboxes/warmup?mailboxId=`	Permanently disable warmup

Enable Warmup at Order Time

Set "onWarmup": true on individual mailbox entries in POST /orders/json?userId=. Warmup is charged alongside the mailbox in the same transaction. If not passed it defaults to "onWarmup": false

POST /orders/json?userId=<userId>
{
  "acmecorp.com": [
    { "username": "alice", "onWarmup": true },
    { "username": "bob",   "onWarmup": true },
    { "username": "carol", "onWarmup": false }
  ]
}

Add Warmup to an Existing Mailbox

POST /mailboxes/warmup?mailboxId=<mailboxId>

A prorated charge is calculated for the remaining days in the current billing period and deducted from wallet. The mailbox must be ACTIVE

Warmup Status

Status	Meaning	Billed at renewal?
`PENDING`	Enrollment in progress	No
`ACTIVE`	Warmup running	Yes
`PAUSED`	Warmup paused	Yes
`STOPPED`	Permanently disabled	No

Scenarios

Pausing Warmup

toggle without a body:

POST /mailboxes/warmup/toggle?mailboxId=<mailboxId>

Warmup pauses immediately but subscription will still be active. Warmup can be turned on again without any charged for that month.

Resuming Warmup

PATCH /mailboxes/warmup/status?mailboxId=<mailboxId>
{ "status": "ACTIVE" }

Warmup resumes immediately and is included in billing at the next renewal.

Disabling Warmup Permanently

DELETE /mailboxes/warmup?mailboxId=<mailboxId>

Warmup stops immediately. Billing stops at the next renewal cycle. No mid-period refund is issued.

Use case: Mailbox no longer needs warmup.

Re-enabling After a Stop

POST /mailboxes/warmup?mailboxId=<mailboxId>

If the mailbox was previously enrolled, re-activation can be instant (existing account is re-enabled). A new prorated warmup charge applies.

Billing

At Order Time

Charged alongside the mailbox in the same transaction:

Total = (mailbox count × mailbox price) + (warmup count × warmup price)

Mid-Period Addition

Prorated for the remaining days in the billing period:

Charge = warmupPrice × (daysRemaining / 30)

Renewal

Only mailboxes with warmupStatus = ACTIVE are billed at renewal. Paused mailboxes are excluded.

Renewal total = (active mailboxes × mailboxPrice) + (active warmup mailboxes × warmupPrice)

Webhook Events

`mailbox.warmup.started`

Fired after warmup is turned (POST /account/warmup/enable) and the mailbox moves to ACTIVE.

{
  "eventType": "mailbox.warmup.started",
  "data": {
    "userId": "HATSA7AB56M513Q6EBF005YFHDQT",
    "userEmail": "partner-user@example.com",
    "mailboxId": "4165WDY91BMKS6JD341FKQ5XVP19",
    "email": "alice@acmecorp.com",
    "domain": "acmecorp.com",
    "workspaceType": "GOOGLE"
  }
}

`mailbox.warmup.removed`

Fired when warmup is permanently disabled via DELETE /mailboxes/warmup?mailboxId=.

{
  "eventType": "mailbox.warmup.removed",
  "data": {
    "mailboxId": "4165WDY91BMKS6JD341FKQ5XVP19",
    "email": "alice@acmecorp.com",
    "domain": "acmecorp.com",
    "workspaceType": "GOOGLE"
  }
}

FAQ

Q: Can I add warmup to Microsoft mailboxes?
Yes. Both Google Workspace and Microsoft mailboxes support warmup.

Q: How long does enrollment take?
A few minutes at most. The mailbox stays in PENDING until enrollment is confirmed, then moves to ACTIVE automatically.

Q: Do I get a refund when I disable warmup mid-period?
No. Billing stops at the next renewal cycle.

Q: Can I re-enable warmup after disabling it?
Yes. Call POST /mailboxes/warmup?mailboxId= again. Previously enrolled mailboxes may re-activate without a full re-enrollment.

Avoid These Common Issues

Confusing pause and disable: POST /mailboxes/warmup/toggle pauses sending but keeps the subscription (and billing) active. DELETE /mailboxes/warmup stops billing at the next renewal but does not refund the current period.

Assuming a mid-period refund: Disabling warmup mid-period stops future billing only — there's no proration refund for the current cycle.

Forgetting onWarmup defaults to false: If you don't explicitly set "onWarmup": true on an order, warmup is not enabled for that mailbox.

Expecting paused mailboxes to be billed at renewal: Only mailboxes with warmupStatus = ACTIVE are billed at renewal — PAUSED mailboxes are excluded from that charge.

Next Steps

Mailbox Warmup Events

Full webhook payloads for warmup started/removed.

Pre-Warmup

Order mailboxes that are already warmed up.

Mailboxes

Provision and manage the mailboxes warmup applies to.

Why Use Warmup?#

Endpoints#

Enable Warmup at Order Time#

Add Warmup to an Existing Mailbox#

Warmup Status#

Scenarios#

Pausing Warmup#

Resuming Warmup#

Disabling Warmup Permanently#

Re-enabling After a Stop#

Billing#

At Order Time#

Mid-Period Addition#

Renewal#

Webhook Events#

mailbox.warmup.started#

mailbox.warmup.removed#

FAQ#

Avoid These Common Issues#

Next Steps#