Warmup

Warmup per mailbox and its inbox placement. 3 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

Warmup for every mailbox

GET/api/v1/warmup

Each mailbox's warmup settings, today's volume and its warmup health score (inbox vs spam over 7 days, by provider). Warmup counts inside the mailbox's daily limit.

MCP tool list_warmupRead-only

Returns

mailboxesrequiredobject[]

cURL

curl https://ballast.to/api/v1/warmup \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Warmup for one mailbox

GET/api/v1/warmup/{mailboxId}

Settings, health by provider and the last 14 days (sent, inbox, spam, missing).

MCP tool get_mailbox_warmupRead-only

Parameters

mailboxIdrequiredpath · string

Returns

mailboxIdrequiredstring
emailrequiredstring
supportedrequiredboolean: Google OAuth mailboxes can't warm up yet
enabledrequiredboolean
targetrequirednumber: Warmup emails a day once the ramp is done
rampStartrequirednumber
rampIncrementrequirednumber
rampDaysLeftrequirednumber
replyRaterequirednumber: Percent of this mailbox's warmup emails that get a reply
todayTargetrequirednumber
sentTodayrequirednumber
receivedTodayrequirednumber
dailyLimitrequirednumber: The mailbox's daily limit, which warmup counts inside
healthrequiredobject
daysrequiredobject[]

cURL

curl https://ballast.to/api/v1/warmup/<mailboxId> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Turn warmup on or off and tune it

PATCH/api/v1/warmup/{mailboxId}

Warmup emails go to other mailboxes in the pool (other workspaces too) and count inside the daily limit.

MCP tool update_mailbox_warmupOwners and admins

Parameters

mailboxIdrequiredpath · string
enabledboolean
targetinteger
rampStartinteger
rampIncrementinteger
replyRateinteger
restartRampboolean: Start the warmup ramp again from day 1

Returns

mailboxIdrequiredstring
emailrequiredstring
supportedrequiredboolean: Google OAuth mailboxes can't warm up yet
enabledrequiredboolean
targetrequirednumber: Warmup emails a day once the ramp is done
rampStartrequirednumber
rampIncrementrequirednumber
rampDaysLeftrequirednumber
replyRaterequirednumber: Percent of this mailbox's warmup emails that get a reply
todayTargetrequirednumber
sentTodayrequirednumber
receivedTodayrequirednumber
dailyLimitrequirednumber: The mailbox's daily limit, which warmup counts inside
healthrequiredobject

cURL

curl -X PATCH https://ballast.to/api/v1/warmup/<mailboxId> \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"target":0}'

Warmup for one mailbox

GET/api/v1/warmup/{mailboxId}

Settings, health by provider and the last 14 days (sent, inbox, spam, missing).

MCP tool get_mailbox_warmupRead-only

Parameters

mailboxIdrequiredpath · string

Returns

mailboxIdrequiredstring
emailrequiredstring
supportedrequiredboolean: Google OAuth mailboxes can't warm up yet
enabledrequiredboolean
targetrequirednumber: Warmup emails a day once the ramp is done
rampStartrequirednumber
rampIncrementrequirednumber
rampDaysLeftrequirednumber
replyRaterequirednumber: Percent of this mailbox's warmup emails that get a reply
todayTargetrequirednumber
sentTodayrequirednumber
receivedTodayrequirednumber
dailyLimitrequirednumber: The mailbox's daily limit, which warmup counts inside
healthrequiredobject
daysrequiredobject[]

Turn warmup on or off and tune it

PATCH/api/v1/warmup/{mailboxId}

Warmup emails go to other mailboxes in the pool (other workspaces too) and count inside the daily limit.

MCP tool update_mailbox_warmupOwners and admins

Parameters

mailboxIdrequiredpath · string
enabledboolean
targetinteger
rampStartinteger
rampIncrementinteger
replyRateinteger
restartRampboolean: Start the warmup ramp again from day 1

Returns

mailboxIdrequiredstring
emailrequiredstring
supportedrequiredboolean: Google OAuth mailboxes can't warm up yet
enabledrequiredboolean
targetrequirednumber: Warmup emails a day once the ramp is done
rampStartrequirednumber
rampIncrementrequirednumber
rampDaysLeftrequirednumber
replyRaterequirednumber: Percent of this mailbox's warmup emails that get a reply
todayTargetrequirednumber
sentTodayrequirednumber
receivedTodayrequirednumber
dailyLimitrequirednumber: The mailbox's daily limit, which warmup counts inside
healthrequiredobject