---
sidebar_position: 8
title: Mailbox warm-up and deliverability
description: How FilesHub warms up every sending mailbox with persona conversations, measures real replies, tunes each mailbox's daily limit every night, and exposes the numbers and controls on the Management API.
keywords: [mailbox warm-up, email deliverability api, inbox placement, sending limits, bounce rate, complaint rate, warm-up personas, deliverability policy]
tags: [email-marketing]
last_update:
  date: 2026-10-20
  author: Ahsan Mahmood
---

# Mailbox warm-up and deliverability

Since backend `2026.10.20.1`. FilesHub sends from your own mailboxes, so their reputation is yours to keep.
Three server-side parts do that work, and the Management API exposes their numbers and controls.

## Warm-up, for every mailbox

Any mailbox with **Warm-up** switched on in Nova takes part, whatever its purpose. Between 08:00 and 20:00 a
mailbox sends at most one short plain-text note every 10 minutes, spread across the day. Each purpose has
its own ramp:

| Purpose | Notes per day (first day → step → most) | Share of threads answered |
|---|---|---|
| Marketing | 3 → +2 → 40 | 65% |
| Outreach | 2 → +1 → 20 | 50% |
| Transactional | 2 → +1 → 15 | 50% |
| Warm-up partner | replies only, up to 15 | 45% |

A **warm-up partner** is an extra inbox (for example a long-standing Gmail account). It only receives, reads
and answers warm-up notes. It never starts a thread and never sends campaign or transactional mail.

Each mailbox writes as a **persona** to a few regular correspondents. Every pair shares a story that moves
slowly through life chapters, and a thread goes back and forth 2–5 times using its last notes as memory.
Notes are written by AI through FilesHub's own AI routing, with a local fallback, and never contain links,
email addresses or markup. A reader opens each note 3–180 minutes after it arrives, marks it read and flagged
(Important on Gmail), moves it out of Spam if it landed there, and files it away. It touches only messages
carrying a warm-up token it sent.

Warm-up notes count toward a mailbox's daily limit.

## Measuring real engagement

Once an hour FilesHub reads only the `In-Reply-To` and `References` headers of new inbox messages on
marketing and outreach mailboxes, and marks the campaign send each reply answers (`replied_at`). Nothing in
the inbox is flagged, moved or marked read. Bounce and complaint reports are read from the same inboxes.

## The nightly tuner

At 02:30 each mailbox is measured over the policy window (7 days by default), and the tuner acts on the result:

- **Repeated failures** (3 sends in a row): a warm-up partner stops warming up; a marketing or outreach
  mailbox is paused from campaigns.
- **Trouble** (hard bounces over 2%, complaints over 0.1%, or warm-up notes landing in spam): a marketing or
  outreach mailbox's limit is cut to 75% (never below its floor) and it is paused for 48 hours. Its warm-up
  volume goes up.
- **Healthy and busy** (bounces under 1%, no complaints, 95%+ inbox, 80%+ of the limit used): the limit rises
  by 12%, at most once a week, up to the purpose's ceiling (marketing 150, outreach 40).

**Transactional mailboxes never have their limit cut or their sending paused.** Only their warm-up volume
moves. A rate with too little evidence behind it is `null` and never triggers anything. Every change, from
the tuner, the API or Nova, is stored with its reason. The owner gets a notification only when a mailbox
needs attention, and a reminder once a week has passed without a recorded review.

## API

All endpoints are on the Management plane (`https://fileshub.zaions.com/api/public/v1`, `Authorization:
Bearer fh_pat_…`). They need `can_manage_email_marketing` **and** a token for every project, because the
mailboxes serve every product; otherwise they answer 403. An unknown id answers 404.

| Method and path | What it does |
|---|---|
| `GET /email-marketing/deliverability` | Every mailbox: settings, warm-up state, persona, and `last_7_days` / `last_30_days` numbers. Also capacity, the policy with defaults and bounds, the last 30 tuning events and the last review. `?dns=1` adds SPF, DKIM and DMARC per domain. |
| `PATCH /email-marketing/mailboxes/{id}` | Change `daily_limit`, `warmup_enabled`, `warmup_max` (1–100 or null), `marketing_paused_until` (within 30 days, or null) or `is_active`. `reason` is required and stored with each change. A marketing or outreach limit must sit inside the policy's floor and ceiling. |
| `GET /email-marketing/deliverability/policy` | The rules in force, the defaults and each rule's bounds. |
| `PUT /email-marketing/deliverability/policy` | `{"rules": {…}, "notes": "…"}` — change some or all rules. One bad rule refuses the whole request (`INVALID_RULES`, each problem in `error.details.rules`). The version goes up by one. |
| `POST /email-marketing/deliverability/reviews` | `{"summary": "…", "model": "…", "changes_applied": […]}` records a review → 201 with `next_review_due`. |
| `GET /email-marketing/warmup/personas` | Personas, relationships (kind, chapter, story so far), and the available kinds and life arcs. |
| `PATCH /email-marketing/warmup/personas/{id}` | `display_name`, `bio`, `voice`, `interests` (up to 5), `timezone`. Plain text only. |
| `PATCH /email-marketing/warmup/relationships/{id}` | `kind`, `chapter`, `story_summary`. Plain text only. |

The per-mailbox numbers come straight from the send and warm-up records:

- `campaign`: `sent`, `failed`, `bounced`, `complained`, `opened`, `clicked`, `replied`, `unsubscribed`, and
  `bounce_rate`, `complaint_rate`, `reply_rate`, `click_rate` (null below `min_sends_for_rates` sends).
- `warmup`: `sent`, `received`, `found_inbox`, `found_spam`, `rescued`, `not_found`, `replied`, `inbox_share`
  (null below `min_found_for_inbox_share`).
- `utilisation` (sends a day ÷ limit), `failure_streak` and `last_failure`.

The older `GET /email-marketing/warmup` still answers. Since this release its `ramp` is the per-purpose map
shown above, and its rows include every mailbox in warm-up.

## What to expect

Warm-up replies come from your own network. They help inbox placement but are not engagement. Real
recipients decide your reputation: keep hard bounces under 2% and complaints well under 0.3%, the ceiling
Gmail and Yahoo enforce for bulk senders, and expect cold outreach to draw a few percent of replies. A
healthy mailbox carries roughly 50–150 cold emails a day after four to six weeks of warm-up, so a daily
volume in the thousands needs mailboxes spread over several domains.