@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/deliverability.md

@@ -0,0 +1,677 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.deliverability`: Deliverability
+
+17 operations (12 read, 3 write, 1 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.deliverability.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [deliverability.d.ts](deliverability.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`checkDomainBlocklist`](#op-checkdomainblocklist) | `POST /api/v1/deliverability/blocklist/check` | read | `campaigns:read` | Check Domain Blocklist |
+| [`createBlocklistRemovalRequest`](#op-createblocklistremovalrequest) | `POST /api/v1/deliverability/recovery/removal-requests` | write | `campaigns:write` | Create Blocklist Removal Request |
+| [`decideMailboxRetirement`](#op-decidemailboxretirement) | `POST /api/v1/deliverability/recovery/decide` | destructive | `campaigns:delete` | Decide Mailbox Retirement |
+| [`getAutopilotPreferences`](#op-getautopilotpreferences) | `GET /api/v1/deliverability/autopilot/preferences` | read | `campaigns:read` | Get Autopilot Preferences |
+| [`getCapacityPlan`](#op-getcapacityplan) | `GET /api/v1/deliverability/capacity-plan` | read | `campaigns:read` | Get Capacity Plan |
+| [`getDomainReport`](#op-getdomainreport) | `GET /api/v1/deliverability/domain/{domain}/report` | read | `campaigns:read` | Get Domain Report |
+| [`getFleetSummary`](#op-getfleetsummary) | `GET /api/v1/deliverability/fleet-summary` | read | `campaigns:read` | Get Fleet Summary |
+| [`getMailboxRecoveryHistory`](#op-getmailboxrecoveryhistory) | `GET /api/v1/deliverability/recovery/mailboxes/{mailbox_id}/history` | read | `campaigns:read` | Get Mailbox Recovery History |
+| [`getMailboxRecoveryOverview`](#op-getmailboxrecoveryoverview) | `GET /api/v1/deliverability/recovery` | read | `campaigns:read` | Get Mailbox Recovery Overview |
+| [`getSafeToSend`](#op-getsafetosend) | `GET /api/v1/deliverability/safe-to-send` | read | `campaigns:read` | Get Safe To Send |
+| [`getSequencesHealth`](#op-getsequenceshealth) | `GET /api/v1/deliverability/sequences-health` | read | `campaigns:read` | Get Sequences Health |
+| [`listAutopilotApprovals`](#op-listautopilotapprovals) | `GET /api/v1/deliverability/autopilot/approvals` | read | `campaigns:read` | List Autopilot Approvals |
+| [`listDegradedMailboxes`](#op-listdegradedmailboxes) | `GET /api/v1/deliverability/degraded` | read | `campaigns:read` | List Degraded Mailboxes |
+| [`listDeliverabilityFindings`](#op-listdeliverabilityfindings) | `GET /api/v1/deliverability/findings` | read | `campaigns:read` | List Deliverability Findings |
+| [`setAutopilotPreferences`](#op-setautopilotpreferences) | `PUT /api/v1/deliverability/autopilot/preferences` | billable | `campaigns:run` | Set Autopilot Preferences |
+| [`undoMailboxRetirement`](#op-undomailboxretirement) | `POST /api/v1/deliverability/recovery/undo` | write | `campaigns:write` | Undo Mailbox Retirement |
+| [`updateBlocklistRemovalRequest`](#op-updateblocklistremovalrequest) | `PATCH /api/v1/deliverability/recovery/removal-requests/{request_id}` | write | `campaigns:write` | Update Blocklist Removal Request |
+
+---
+
+<a id="op-checkdomainblocklist"></a>
+
+### `g8.api.deliverability.checkDomainBlocklist(input)`
+
+**Check Domain Blocklist**
+
+- HTTP: `POST /api/v1/deliverability/blocklist/check`
+- operationId: `check_domain_blocklist_deliverability_blocklist_check_post` (also callable as `g8.api.call("check_domain_blocklist_deliverability_blocklist_check_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Blocklist verdicts for up to 50 domains. `null` means unknown, never "clean".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BlocklistCheckRequest` | yes | Request body; fields below. |
+
+Body fields (`BlocklistCheckRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domains` | `Array<string>` | yes | Up to 50 domains or hostnames. min items 1, max items 50 |
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.checkDomainBlocklist({ body: { domains: ["acme.com"] } });
+```
+
+---
+
+<a id="op-createblocklistremovalrequest"></a>
+
+### `g8.api.deliverability.createBlocklistRemovalRequest(input)`
+
+**Create Blocklist Removal Request**
+
+- HTTP: `POST /api/v1/deliverability/recovery/removal-requests`
+- operationId: `create_blocklist_removal_request_deliverability_recovery_removal_requests_post` (also callable as `g8.api.call("create_blocklist_removal_request_deliverability_recovery_removal_requests_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Track a removal request you filed for a blocklisted sending domain.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BlocklistRemovalCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`BlocklistRemovalCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain_id` | `integer` | yes | The listed sending domain. min 1 |
+| `body.ticket_ref` | `string \| null` | no | Your reference for the removal ticket. max length 500 |
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.createBlocklistRemovalRequest({ body: { domain_id: 1 } });
+```
+
+---
+
+<a id="op-decidemailboxretirement"></a>
+
+### `g8.api.deliverability.decideMailboxRetirement(input)`
+
+**Decide Mailbox Retirement**
+
+- HTTP: `POST /api/v1/deliverability/recovery/decide`
+- operationId: `decide_mailbox_retirement_deliverability_recovery_decide_post` (also callable as `g8.api.call("decide_mailbox_retirement_deliverability_recovery_decide_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Approve or reject a proposed retirement. Approving schedules the mailbox's cancellation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RetirementDecisionRequest` | yes | Request body; fields below. |
+
+Body fields (`RetirementDecisionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.decision` | `"approved" \| "rejected"` | yes |  |
+| `body.short_code` | `string` | yes | The retirement's 4-character code. pattern `^[A-HJ-NP-Za-hj-np-z2-9]{4}$` |
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.deliverability.decideMailboxRetirement({ body: { decision: "approved", short_code: "example" } });
+```
+
+---
+
+<a id="op-getautopilotpreferences"></a>
+
+### `g8.api.deliverability.getAutopilotPreferences(input?)`
+
+**Get Autopilot Preferences**
+
+- HTTP: `GET /api/v1/deliverability/autopilot/preferences`
+- operationId: `get_autopilot_preferences_deliverability_autopilot_preferences_get` (also callable as `g8.api.call("get_autopilot_preferences_deliverability_autopilot_preferences_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org's autopilot mode, its guardrails, and what it has used this month.
+
+`guardrail_active` true means the org is in `auto` mode but has hit a
+monthly limit, so retirements are queueing for a human again.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getAutopilotPreferences();
+```
+
+---
+
+<a id="op-getcapacityplan"></a>
+
+### `g8.api.deliverability.getCapacityPlan(input)`
+
+**Get Capacity Plan**
+
+- HTTP: `GET /api/v1/deliverability/capacity-plan`
+- operationId: `get_capacity_plan_deliverability_capacity_plan_get` (also callable as `g8.api.call("get_capacity_plan_deliverability_capacity_plan_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+How much sending capacity a target volume needs, and what the shortfall costs.
+
+RECOMMENDATION ONLY. It buys nothing and holds nothing - the credit figure
+it returns is an estimate of what closing the gap WOULD cost. The buying
+is `POST /mailboxes/schedule-buy/plans`, which is a separate, deliberate
+act.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.contacts_per_month` | `integer` | yes | Volume you intend to send per month. |
+| `query.delivery_days` | `integer` | no | Days you want to spread that volume over. default `30` |
+| `query.warmed` | `boolean` | no | Assume new mailboxes must warm up before they count as capacity. default `true` |
+| `query.domain_tld` | `string` | no | Extension to price against. default `".com"` |
+| `query.exclude_committed` | `boolean` | no | Treat the target as ADDITIONAL volume: mailboxes already in live sequences are not capacity. default `false` |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getCapacityPlan({ query: { contacts_per_month: 0 } });
+```
+
+---
+
+<a id="op-getdomainreport"></a>
+
+### `g8.api.deliverability.getDomainReport(input)`
+
+**Get Domain Report**
+
+- HTTP: `GET /api/v1/deliverability/domain/{domain}/report`
+- operationId: `get_domain_report_deliverability_domain__domain__report_get` (also callable as `g8.api.call("get_domain_report_deliverability_domain__domain__report_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One domain's deliverability: its mailboxes' health, its placement, its verdict.
+
+Keyed by domain NAME rather than by `domain_id`, matching the app - a
+report is about the reputation of a name, which outlives any one row.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain` | `string` | yes | Sending domain name, e.g. acme-outreach.com |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getDomainReport({ path: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-getfleetsummary"></a>
+
+### `g8.api.deliverability.getFleetSummary(input?)`
+
+**Get Fleet Summary**
+
+- HTTP: `GET /api/v1/deliverability/fleet-summary`
+- operationId: `get_fleet_summary_deliverability_fleet_summary_get` (also callable as `g8.api.call("get_fleet_summary_deliverability_fleet_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Deliverability across the whole sending fleet, in one object.
+
+Counts by health state, the fleet's inbox rate, and a single
+`safe_to_send` verdict. The right first call before a large send.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getFleetSummary();
+```
+
+---
+
+<a id="op-getmailboxrecoveryhistory"></a>
+
+### `g8.api.deliverability.getMailboxRecoveryHistory(input)`
+
+**Get Mailbox Recovery History**
+
+- HTTP: `GET /api/v1/deliverability/recovery/mailboxes/{mailbox_id}/history`
+- operationId: `get_mailbox_recovery_history_deliverability_recovery_mailboxes__mailbox_id__history_get` (also callable as `g8.api.call("get_mailbox_recovery_history_deliverability_recovery_mailboxes__mailbox_id__history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+A mailbox's daily health snapshots over the last `weeks` weeks.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.mailbox_id` | `integer` | yes | Mailbox id. |
+| `query.weeks` | `integer` | no | default `10` |
+
+**Returns** `ApiResponse_MailboxRecoveryListPayload_`: the envelope `{ data: MailboxRecoveryListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`MailboxRecoveryListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getMailboxRecoveryHistory({ path: { mailbox_id: 1 } });
+```
+
+---
+
+<a id="op-getmailboxrecoveryoverview"></a>
+
+### `g8.api.deliverability.getMailboxRecoveryOverview(input?)`
+
+**Get Mailbox Recovery Overview**
+
+- HTTP: `GET /api/v1/deliverability/recovery`
+- operationId: `get_mailbox_recovery_overview_deliverability_recovery_get` (also callable as `g8.api.call("get_mailbox_recovery_overview_deliverability_recovery_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Mailboxes by domain with their lifecycle, pending retirements, and the spare pool.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getMailboxRecoveryOverview();
+```
+
+---
+
+<a id="op-getsafetosend"></a>
+
+### `g8.api.deliverability.getSafeToSend(input?)`
+
+**Get Safe To Send**
+
+- HTTP: `GET /api/v1/deliverability/safe-to-send`
+- operationId: `get_safe_to_send_deliverability_safe_to_send_get` (also callable as `g8.api.call("get_safe_to_send_deliverability_safe_to_send_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One verdict: can I send right now, and if not, why not.
+
+The cheapest thing to call before a launch. A `false` here with a live
+sequence running is the signal to pause rather than to push.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string \| null` | no | Limit the verdict to one domain. Omit for the whole fleet. |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getSafeToSend();
+```
+
+---
+
+<a id="op-getsequenceshealth"></a>
+
+### `g8.api.deliverability.getSequencesHealth(input?)`
+
+**Get Sequences Health**
+
+- HTTP: `GET /api/v1/deliverability/sequences-health`
+- operationId: `get_sequences_health_deliverability_sequences_health_get` (also callable as `g8.api.call("get_sequences_health_deliverability_sequences_health_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Live sequences that are still sending from degraded or paused mailboxes.
+
+Keyed by sequence id. These are the sequences quietly losing delivery
+right now; swapping their sender mailbox is the fix.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.getSequencesHealth();
+```
+
+---
+
+<a id="op-listautopilotapprovals"></a>
+
+### `g8.api.deliverability.listAutopilotApprovals(input?)`
+
+**List Autopilot Approvals**
+
+- HTTP: `GET /api/v1/deliverability/autopilot/approvals`
+- operationId: `list_autopilot_approvals_deliverability_autopilot_approvals_get` (also callable as `g8.api.call("list_autopilot_approvals_deliverability_autopilot_approvals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Mailbox retirements the autopilot has queued for a person to approve.
+
+Oldest first. `spare_available` says whether a warmed spare is ready to
+take a retired mailbox's place, which is what makes approving one cheap.
+An org whose schema predates the queue gets an empty list, not an error.
+
+**Input**: none.
+
+**Returns** `ApiResponse_MailboxDomainListPayload_`: the envelope `{ data: MailboxDomainListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`MailboxDomainListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.listAutopilotApprovals();
+```
+
+---
+
+<a id="op-listdegradedmailboxes"></a>
+
+### `g8.api.deliverability.listDegradedMailboxes(input?)`
+
+**List Degraded Mailboxes**
+
+- HTTP: `GET /api/v1/deliverability/degraded`
+- operationId: `list_degraded_mailboxes_deliverability_degraded_get` (also callable as `g8.api.call("list_degraded_mailboxes_deliverability_degraded_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Mailboxes whose deliverability is in trouble, worst first.
+
+`watch` is the early warning and `paused` is the mailboxes that have
+already been taken out of rotation. A paused mailbox still belongs to live
+sequences - see `/deliverability/sequences-health` for which.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.min_severity` | `string` | no | 'watch' returns everything of concern; 'paused' only what has already stopped sending. default `"watch"` |
+
+**Returns** `ApiResponse_MailboxDomainListPayload_`: the envelope `{ data: MailboxDomainListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`MailboxDomainListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.listDegradedMailboxes();
+```
+
+---
+
+<a id="op-listdeliverabilityfindings"></a>
+
+### `g8.api.deliverability.listDeliverabilityFindings(input?)`
+
+**List Deliverability Findings**
+
+- HTTP: `GET /api/v1/deliverability/findings`
+- operationId: `list_deliverability_findings_deliverability_findings_get` (also callable as `g8.api.call("list_deliverability_findings_deliverability_findings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Individual deliverability findings the daily routine raised, newest first.
+
+Every filter is CLOSED to the values the lifecycle actually uses, so a
+typo is a 422 naming them rather than a silently empty list.
+
+An org whose schema predates the findings table gets an empty list, not an
+error - absence of findings and absence of the table look the same here on
+purpose.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Filter by lifecycle state. |
+| `query.severity` | `string \| null` | no | Filter by severity. |
+| `query.signal` | `string \| null` | no | Filter by signal name, e.g. dmarc, mailbox_health. |
+| `query.limit` | `integer` | no | Newest first. The app's own ceiling. default `50` |
+
+**Returns** `ApiResponse_MailboxDomainListPayload_`: the envelope `{ data: MailboxDomainListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`MailboxDomainListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.listDeliverabilityFindings();
+```
+
+---
+
+<a id="op-setautopilotpreferences"></a>
+
+### `g8.api.deliverability.setAutopilotPreferences(input)`
+
+**Set Autopilot Preferences**
+
+- HTTP: `PUT /api/v1/deliverability/autopilot/preferences`
+- operationId: `set_autopilot_preferences_deliverability_autopilot_preferences_put` (also callable as `g8.api.call("set_autopilot_preferences_deliverability_autopilot_preferences_put", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Replace the org's autopilot preferences. `mode='auto'` AUTHORISES SPEND.
+
+In `auto` the autopilot retires failing mailboxes and buys replacements on
+its own, without a human decision, until it has done
+`max_auto_retirements_per_month` retirements or spent
+`monthly_spend_ceiling_credits` credits this calendar month - whichever
+comes first. Past either limit it falls back to queueing for approval for
+the rest of the month.
+
+In `approval` (the default) nothing is retired or bought without a person
+saying yes, and the ceilings are inert.
+
+REPLACES all three fields; there is no partial update. Org admins and
+owners only - the app gates this the same way.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AutopilotPreferencesRequest` | yes | Request body; fields below. |
+
+Body fields (`AutopilotPreferencesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.max_auto_retirements_per_month` | `integer` | yes | Ceiling on automatic retirements per calendar month min 0, max 100 |
+| `body.mode` | `"approval" \| "auto"` | yes | 'approval' queues every retirement for a human; 'auto' lets the autopilot act and SPEND |
+| `body.monthly_spend_ceiling_credits` | `integer` | yes | Ceiling on credits the autopilot may spend per calendar month min 0, max 500000 |
+
+**Returns** `ApiResponse_MailboxDomainPayload_`: the envelope `{ data: MailboxDomainPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.deliverability.setAutopilotPreferences({
+  body: {
+    max_auto_retirements_per_month: 0,
+    mode: "approval",
+    monthly_spend_ceiling_credits: 0,
+  },
+});
+```
+
+---
+
+<a id="op-undomailboxretirement"></a>
+
+### `g8.api.deliverability.undoMailboxRetirement(input)`
+
+**Undo Mailbox Retirement**
+
+- HTTP: `POST /api/v1/deliverability/recovery/undo`
+- operationId: `undo_mailbox_retirement_deliverability_recovery_undo_post` (also callable as `g8.api.call("undo_mailbox_retirement_deliverability_recovery_undo_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Reverse an approved retirement while its grace window is open.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RetirementUndoRequest` | yes | Request body; fields below. |
+
+Body fields (`RetirementUndoRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.short_code` | `string` | yes | The retirement's 4-character code. pattern `^[A-HJ-NP-Za-hj-np-z2-9]{4}$` |
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.undoMailboxRetirement({ body: { short_code: "example" } });
+```
+
+---
+
+<a id="op-updateblocklistremovalrequest"></a>
+
+### `g8.api.deliverability.updateBlocklistRemovalRequest(input)`
+
+**Update Blocklist Removal Request**
+
+- HTTP: `PATCH /api/v1/deliverability/recovery/removal-requests/{request_id}`
+- operationId: `update_blocklist_removal_request_deliverability_recovery_removal_requests__request_id__patch` (also callable as `g8.api.call("update_blocklist_removal_request_deliverability_recovery_removal_requests__request_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Attach or change the ticket reference on a removal request.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.request_id` | `integer` | yes | Removal request id. |
+| `body` | `BlocklistRemovalUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`BlocklistRemovalUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ticket_ref` | `string` | yes | min length 1, max length 500 |
+
+**Returns** `ApiResponse_MailboxRecoveryPayload_`: the envelope `{ data: MailboxRecoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.deliverability.updateBlocklistRemovalRequest({ path: { request_id: 1 }, body: { ticket_ref: "example" } });
+```