> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Deliverability & Warmup

> How domain reputation works on Gork and how to scale sending without surprises.

Mailbox providers (Gmail, Outlook, Yahoo) decide inbox vs spam mostly by **domain reputation**: who you send to, how recipients react, and how fast volume grows on a new domain. This page explains what Gork enforces, what is your job, and the exact numbers involved.

## What Gork enforces (pattern brakes, not calendars)

Paid workspaces get their **full quota from day 0** — there is no warmup period, no ramp, no locked volume. Instead, sending pauses only when traffic looks abusive or reputation collapses:

| Brake                      | Trips when                                                | Effect                                     |
| -------------------------- | --------------------------------------------------------- | ------------------------------------------ |
| Sandbox single-recipient   | Free workspace, more than 1 recipient                     | `403 sandbox_bulk_not_allowed`             |
| Bulk tripwire              | 50+ unique recipients in 10 minutes                       | Workspace sending paused for review        |
| Reputation circuit breaker | 7-day complaints ≥ 0.30% or bounces ≥ 5% (min. 20 sends)  | `sendingApproved = false`, account review  |
| Send-time suppressions     | Recipient previously bounced, complained, or unsubscribed | `422 recipient_suppressed` before dispatch |
| Daily / spend caps         | Plan, workspace, or domain ceiling reached                | `402` / `429` with reset info              |

Legitimate conversational agent mail — low volume, real replies, high engagement — never trips any of these.

## Your job: ramp new domains gradually

A brand-new custom domain has no reputation. Day-one blasts to thousands of cold addresses will spike bounces and complaints and trip the breaker above — on any provider, not just Gork. Ramp instead:

<Steps>
  <Step title="Start small and engaged">
    Begin with 25–100 sends/day to recipients most likely to engage (existing users, warm contacts). Engagement is a positive reputation signal.
  </Step>

  <Step title="Grow ~1.5–2x daily while healthy">
    Double-check bounce and complaint rates each morning (per-domain numbers live on the **Domains** page). If both are near zero, grow; if climbing, hold volume and clean the list.
  </Step>

  <Step title="Clean before you scale">
    Run lists through an email-verification tool first. Invalid addresses are the fastest way to spike bounces past 5%.
  </Step>

  <Step title="Skip tracking pixels during ramp">
    Open tracking adds a pixel some providers flag as marketing-like. Gork's `trackOpens` defaults to off — leave it off until the domain is established.
  </Step>
</Steps>

### Ramping over the API

There is no campaign scheduler — pace the loop yourself. Send idempotently so retries never double-send:

```python theme={null}
import time, requests, os

HEADERS = {"Authorization": f"Bearer {os.getenv('GORK_API_KEY')}"}
DAY_BUDGET = 100  # raise as the domain proves itself

sent = 0
for recipient in prospects:
    if sent >= DAY_BUDGET:
        break  # resume tomorrow; the domain ceiling below can enforce this for you
    res = requests.post(
        "https://api.gork.email/v1/messages/send",
        headers={**HEADERS, "Idempotency-Key": f"warmup-{recipient}"},
        json={"inboxId": "inb_...", "to": [recipient], "subject": ..., "text": ...},
    )
    if res.status_code == 429:  # ceiling or rate limit — back off, don't hammer
        break
    sent += 1
```

## Voluntary domain ceilings

On the **Domains** page you can set a **daily sending ceiling** per verified domain — a static cap you control that never changes on its own:

* `NULL` (default) means no ceiling; plan and workspace caps still apply.
* Sends past the ceiling fail with `429 domain_daily_cap_reached`, including the exact usage (`used`, `cap`) and the UTC-midnight `resetsAt` — plus a `Retry-After` header. Nothing is silently dropped or queued.
* Failed provider attempts **refund** the day's count, so `used` always equals mail actually accepted.
* Setting a ceiling below today's already-sent count pauses the domain until reset — the console warns you before saving.

Use it as your own guardrail: set day one's budget, raise it as the domain proves itself, remove it when established. Programmatic control lives at `PATCH /v1/domains/{id}` — see [Update domain ceiling](/api-reference/domains/update-ceiling).

## Monitor, don't guess

* **Per-domain health** (Domains page, or `GET /v1/domains/{id}/health`): today's ceiling usage with exact reset time, plus 7-day bounce/complaint rates against the suspension thresholds, with plain-language guidance.
* **Suppressions** (`GET /v1/suppressions`): every bounce, complaint, and unsubscribe on record — your cleaning list.
* **Webhook deliveries** (`GET /v1/webhooks/deliveries`): confirm `email.bounced` / `email.complained` events reach your systems in real time.

<Note>
  Transactional mail (password resets, receipts, OTPs) should never be throttled by warmup logic — it is expected, engaged traffic. Ramp only bulk/outreach volume.
</Note>