# GTM Inboxes

> API-first cold email infrastructure for agencies and technical operators. GTM Inboxes manages client workspaces, domains, DNS, SMTP inboxes, credentials, readiness checks, deliverability monitoring, campaign intelligence, alerts, webhooks, and sequencer exports.

Canonical app URL: https://app.gtminboxes.com

## Primary Docs

- [Agency API quickstart](/docs/quickstart): shortest safe path from empty account to workspace, domain, complete email DNS, SMTP inboxes, readiness checks, seed-placement gate evidence, and sequencer export.
- [SMTP package calculator](/pricing): planning tool for translating prospects, touches, sending days, risk tolerance, and package mix into domains, inboxes, SMTP IP capacity, warmup assumptions, and monthly cost. Output is not a deliverability, warmup, ban-immunity, official-reseller, or final-price guarantee.
- [Provider comparisons](/compare): buyer-facing comparison pages for Cheap Inboxes/Zapmail, Forge Stack, Mailreef/Mission Inbox, Maildoso/Inframail, and ScaledMail. Positioning is API-first, readiness-gated inbox infrastructure; comparisons avoid unproven deliverability, reseller-status, pre-warmed inventory, and ban-immunity claims.
- [Free email tools](/tools): no-auth utilities for cold email infrastructure — a DNS + auth-record checker (`/tools/dns-checker`), SPF/DKIM/DMARC record generators (`/tools/spf-generator`, `/tools/dkim-generator`, `/tools/dmarc-generator`), an email spam checker (`/tools/spam-checker`), SPF/DMARC record lookups (`/tools/spf-lookup`, `/tools/dmarc-lookup`), a DKIM selector checker (`/tools/dkim-selector-checker`), an email blacklist checker (`/tools/blacklist-checker`), a cold email domain checker with RDAP age (`/tools/cold-email-domain-checker`), and an inbox readiness checker (`/tools/inbox-readiness-checker`). All outputs are advisory, not placement proof; nothing entered is stored. DKIM keypairs are generated in-browser. JSON endpoints (no auth, rate-limited by source): `GET /api/public/dns-lookup?domain=example.com`, `GET /api/public/blacklist-check?target=ip-or-domain`, `GET /api/public/domain-check?domain=example.com`.
- [Interactive API reference](/docs): Scalar-rendered OpenAPI reference for endpoint schemas, permissions, pagination, and error envelopes.
- [OpenAPI JSON](/openapi.json): machine-readable OpenAPI 3.1 document.
- [Competitive battlecards](https://github.com/mherzog4/gtminboxes/blob/main/docs/competitive-battlecards.md): sales-facing win/loss scenarios, landmines, proof points, and safe objection handling.
- [Production launch target inventory](https://github.com/mherzog4/gtminboxes/blob/main/docs/production-launch-target-inventory.md): redacted worksheet for collecting the production URL, workspace, domains, inboxes, integration, recipient allowlists, and operator access paths before first-prospect readiness checks.
- [Production go/no-go runbook](https://github.com/mherzog4/gtminboxes/blob/main/docs/production-go-no-go-runbook.md): operator checklist for first real prospect traffic, hard stops, proof sources, and rollback.
- [Local secret exposure runbook](https://github.com/mherzog4/gtminboxes/blob/main/docs/local-secret-exposure-runbook.md): response steps for local agent/tool history, secret scanning, and credential rotation.
- Local CLI and MCP: from the repo checkout, use `pnpm gtmi commands list`, authenticate with `GTMI_API_KEY` or `pnpm gtmi auth login --api-key-stdin`, run read-only workspace/domain/inbox/alert/deliverability/readiness/reseller-order commands including `pnpm gtmi readiness report --workspace-id workspace_id`, `pnpm gtmi reseller-orders list --workspace-id workspace_id`, and `pnpm gtmi readiness doctor --workspace-id workspace_id` (one go/no-go verdict; exit 0 go, 2 warnings, 1 no-go), or start `pnpm gtmi mcp serve` for read-only assistant tools such as `gtmi_get_workspace_readiness_report`, `gtmi_list_reseller_orders`, and `gtmi_get_reseller_order`. Read-only is the default; set `GTMINBOXES_MCP_WRITE_ENABLED=true` to also expose one gated, agent-native write tool (`gtmi_provision_inboxes`, requires `write:inboxes`) that drives the existing auto-provision coordinator and never returns SMTP secrets.

## Agent Context

- [Operational concepts](/agent-docs/operational-concepts.md): product model, API conventions, readiness, webhooks, background jobs, and integration flow.
- [Safety and confirmation rules](/agent-docs/safety-and-confirmation.md): actions agents may take automatically, actions requiring care, and actions requiring explicit human confirmation.
- [Sending policy](/agent-docs/sending-policy.md): default sending limits, warmup rules, throttling triggers, and deliverability guardrails.
- [Webhook events](/agent-docs/webhook-events.md): public event types and what they represent.
- [Background jobs](/agent-docs/background-jobs.md): recurring and scheduled job families, cost profiles, and operator expectations.

## Useful API Areas

- Workspaces: create one isolated workspace per client or operating unit; read `GET /api/v1/workspaces/{workspaceId}/readiness-report`, `pnpm gtmi readiness report --workspace-id workspace_id`, or MCP tool `gtmi_get_workspace_readiness_report` for a redacted proof bundle across domains, inboxes, inbox recovery plans, launch gate, seed placement, alerts, exportability, and 30-day proof metrics with public/customer/internal visibility.
- Domains: add, register, import, provision DNS records, validate DNS, and inspect reputation.
- Inboxes: create SMTP inboxes, capture one-time plaintext passwords at creation, retrieve redacted credential metadata later, inspect DNS/MTA/smoke-test `smtpReadiness`, pause, resume, and bulk manage.
- Seed placement: record Gmail/Outlook inbox, spam, and missing counts before first prospect traffic, then inspect the latest workspace gate result and recent history.
- Public proof feed: `GET /api/public/deliverability-proof` (no auth) and the `/proof` page publish pooled, redacted deliverability metrics from operator-opted-in workspaces. Only `public_safe`, uncapped, threshold-passing metrics surface with exact sample sizes; it stays empty until a measured cohort accrues enough evidence — never synthetic numbers.
- First prospect go/no-go: use the production runbook before approving tiny-batch or open prospect traffic; launch-gate bounce/complaint rates use the configured signal window and overlapping UTC send-volume buckets.
- Integrations: connect Smartlead, Instantly, or EmailBison, discover/import provider accounts where supported, and export only readiness-passing inboxes while the workspace launch gate is not paused or hard-stopped. Export job and row errors are redacted customer guidance; raw provider payloads, tokens, SMTP passwords, encrypted credentials, and stack traces must not be exposed.
- Auto-provision coordinator: `POST /api/v1/workspaces/{workspaceId}/auto-provision` starts one async job (existing domain → DKIM provisioning → inbox creation) and defers warmup and sequencer export to the readiness and launch gates; poll `GET /api/v1/provisioning-jobs/{jobId}` for per-step state and redacted errors. It chains existing endpoints behind one call and never bypasses a gate — the export step stays blocked until launch gate and per-inbox SMTP readiness pass, and re-POSTing the same domain resumes the job and retries a gate-blocked export. It does not register or buy domains; register a domain first.
- Reseller orders: `GET /api/v1/reseller-orders`, `GET /api/v1/reseller-orders/{orderId}`, `pnpm gtmi reseller-orders list`, `pnpm gtmi reseller-orders get`, MCP tool `gtmi_list_reseller_orders`, and MCP tool `gtmi_get_reseller_order` expose customer-safe order status, required action, owner, mailbox readiness, connection model, and sequencer compatibility for reseller-backed inbox workflows. `POST /api/v1/reseller-orders` records an order request only. Live Microsoft/Google fulfillment remains simulated-default and operator-gated until partner access is proven; agents must not claim official reseller status, trigger provider provisioning, approve replacements/refunds, or expose provider references/secrets.
- Campaign intelligence: inspect prospect, outbound-message, and reply lifecycle rows, or ingest normalized provider campaign events through integration-scoped endpoints.
- Webhooks: subscribe to operational events with HMAC-SHA256 Standard Webhooks signatures.
- Unsubscribe: GET links are scanner-safe confirmation pages; only signed RFC 8058 POST requests with `List-Unsubscribe=One-Click` mutate suppression state.
- Alerts and logs: inspect DNS, SMTP, blacklist, warmup, infrastructure, background-job signals, and budget-gated alert analysis.
- CLI/MCP: use compact JSON by default in CLI mode, `--pretty` for humans, read-only MCP tools for assistant inspection, and never print API keys or other secrets. Prefer the workspace readiness report command/tool for first-run troubleshooting because it combines SMTP/IMAP readiness, safe inbox recovery guidance, seed placement, launch gate, active alerts, and exportability in one redacted bundle.

## Response Conventions

All public API responses use one envelope:

```json
{ "success": true, "data": {} }
```

```json
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message" } }
```

Authenticate with `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`. API keys are permission-scoped; missing scopes return `403 FORBIDDEN`.

## Agent Safety Summary

- Safe to read docs, OpenAPI schemas, workspaces, workspace readiness reports, domains, inbox readiness, alerts, logs, webhook delivery history, and provider health when authenticated with a read-scoped key.
- Safe to create low-volume test workspaces, domains, and inboxes only when the user explicitly asks and provides an API key with write scopes.
- Require human confirmation before registering or buying domains, exporting inboxes to sequencers, changing DNS, rotating traffic, provisioning infrastructure, changing send limits, pausing active inboxes, deleting resources, or handling secrets.
- Require human confirmation before creating or advancing reseller-backed orders, triggering provider provisioning, approving reseller reliability actions, replacing provider-backed resources, cancelling reseller orders, issuing refunds, or changing reseller billing/support state.
- Never print API keys, SMTP passwords, encrypted password values, password hashes, webhook secrets, provider tokens, raw provider payloads, or unsanitized export errors.
- Run `pnpm scan:secrets` before sharing logs, local agent state, or release candidates; follow the local secret exposure runbook if command history contains credentials.
- Never create or use ad hoc internal bulk-send endpoints; internal SMTP proof must use the allowlisted one-inbox smoke-test path.

## Optional

- Read `/agent-docs/operational-concepts.md` before planning non-trivial automation.
- Read `/agent-docs/safety-and-confirmation.md` before taking any mutating action.
- Read `/agent-docs/sending-policy.md` before changing volume, warmup, export, or deliverability behavior.