@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/providerDomains.md

@@ -0,0 +1,1446 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.providerDomains`: Provider Domains
+
+34 operations (13 read, 2 write, 4 destructive, 9 billable, 6 external).
+
+No hand-written client covers this area. Call it through `g8.api.providerDomains.*` 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: [providerDomains.d.ts](providerDomains.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addExternalDomains`](#op-addexternaldomains) | `POST /api/v1/provider-domains/add-external` | billable | `campaigns:run` | Add External Domains |
+| [`cancelDomainTransfer`](#op-canceldomaintransfer) | `POST /api/v1/provider-domains/cancel-transfer` | destructive | `campaigns:delete` | Cancel Domain Transfer |
+| [`checkDomainAvailability`](#op-checkdomainavailability) | `POST /api/v1/provider-domains/check-availability` | billable | `campaigns:run` | Check Domain Availability |
+| [`checkDomainPropagation`](#op-checkdomainpropagation) | `POST /api/v1/provider-domains/{domain_id}/check-propagation` | billable | `campaigns:run` | Check Domain Propagation |
+| [`checkExternalAvailability`](#op-checkexternalavailability) | `POST /api/v1/provider-domains/check-external-availability` | read | `campaigns:read` | Check External Availability |
+| [`checkMailboxStatus`](#op-checkmailboxstatus) | `POST /api/v1/provider-domains/{domain_id}/check-mailbox-status` | write | `campaigns:write` | Check Mailbox Status |
+| [`checkTransferAvailability`](#op-checktransferavailability) | `POST /api/v1/provider-domains/check-transfer-availability` | read | `campaigns:read` | Check Transfer Availability |
+| [`checkoutPurchaseDomains`](#op-checkoutpurchasedomains) | `POST /api/v1/provider-domains/checkout-purchase` | billable | `campaigns:run` | Checkout Purchase Domains |
+| [`checkoutPurchaseMailboxes`](#op-checkoutpurchasemailboxes) | `POST /api/v1/provider-domains/{domain_id}/checkout-mailboxes` | billable | `campaigns:run` | Checkout Purchase Mailboxes |
+| [`checkoutTransferDomain`](#op-checkouttransferdomain) | `POST /api/v1/provider-domains/checkout-transfer` | billable | `campaigns:run` | Checkout Transfer Domain |
+| [`connectProvider`](#op-connectprovider) | `POST /api/v1/provider-domains/{domain_id}/connect-provider` | billable | `campaigns:run` | Connect Provider |
+| [`deleteDomainForwarding`](#op-deletedomainforwarding) | `DELETE /api/v1/provider-domains/{domain_id}/forwarding` | destructive | `campaigns:delete` | Delete Domain Forwarding |
+| [`deleteDomainMailbox`](#op-deletedomainmailbox) | `POST /api/v1/provider-domains/{domain_id}/delete-mailbox` | destructive | `campaigns:delete` | Delete Domain Mailbox |
+| [`generateDomainNames`](#op-generatedomainnames) | `POST /api/v1/provider-domains/generate-domains` | read | `campaigns:read` | Generate Domain Names |
+| [`getDomainInfo`](#op-getdomaininfo) | `POST /api/v1/provider-domains/{domain_id}/info` | read | `campaigns:read` | Get Domain Info |
+| [`getExternalDomainInfo`](#op-getexternaldomaininfo) | `POST /api/v1/provider-domains/{domain_id}/external-info` | read | `campaigns:read` | Get External Domain Info |
+| [`getProviderStatus`](#op-getproviderstatus) | `POST /api/v1/provider-domains/{domain_id}/provider-status` | read | `campaigns:read` | Get Provider Status |
+| [`getProvisioningStates`](#op-getprovisioningstates) | `POST /api/v1/provider-domains/{domain_id}/provisioning-states` | read | `campaigns:read` | Get Provisioning States |
+| [`getSendingDomainStats`](#op-getsendingdomainstats) | `GET /api/v1/provider-domains/stats` | read | `campaigns:read` | Get Sending Domain Stats |
+| [`getSendingPricing`](#op-getsendingpricing) | `GET /api/v1/provider-domains/pricing` | read | `campaigns:read` | Get Sending Pricing |
+| [`getTransferInfo`](#op-gettransferinfo) | `POST /api/v1/provider-domains/{domain_id}/transfer-info` | read | `campaigns:read` | Get Transfer Info |
+| [`listDomainMailboxes`](#op-listdomainmailboxes) | `GET /api/v1/provider-domains/{domain_id}/mailboxes` | read | `campaigns:read` | List Domain Mailboxes |
+| [`listMailboxesForStat`](#op-listmailboxesforstat) | `GET /api/v1/provider-domains/stats/mailboxes/{stat_key}` | read | `campaigns:read` | List Mailboxes For Stat |
+| [`listProviderDomains`](#op-listproviderdomains) | `GET /api/v1/provider-domains` | read | `campaigns:read` | List Provider Domains |
+| [`refreshDomainFromProvider`](#op-refreshdomainfromprovider) | `POST /api/v1/provider-domains/{domain_id}/refresh-from-provider` | write | `campaigns:write` | Refresh Domain From Provider |
+| [`regenerateNameservers`](#op-regeneratenameservers) | `POST /api/v1/provider-domains/{domain_id}/regenerate-nameservers` | external | `campaigns:run` | Regenerate Nameservers |
+| [`resendRegistrantVerification`](#op-resendregistrantverification) | `POST /api/v1/provider-domains/{domain_id}/resend-verification` | external | `campaigns:run` | Resend Registrant Verification |
+| [`resendTransferPassword`](#op-resendtransferpassword) | `POST /api/v1/provider-domains/{domain_id}/resend-transfer-password` | external | `campaigns:run` | Resend Transfer Password |
+| [`resetMailboxPassword`](#op-resetmailboxpassword) | `POST /api/v1/provider-domains/{domain_id}/reset-password` | destructive | `campaigns:delete` | Reset Mailbox Password |
+| [`setAutoWarmup`](#op-setautowarmup) | `POST /api/v1/provider-domains/{domain_id}/auto-warmup` | billable | `campaigns:run` | Set Auto Warmup |
+| [`setDnsRecords`](#op-setdnsrecords) | `POST /api/v1/provider-domains/{domain_id}/dns` | billable | `campaigns:run` | Set Dns Records |
+| [`setDomainForwarding`](#op-setdomainforwarding) | `POST /api/v1/provider-domains/{domain_id}/forwarding` | external | `campaigns:run` | Set Domain Forwarding |
+| [`setNameservers`](#op-setnameservers) | `POST /api/v1/provider-domains/{domain_id}/set-nameservers` | external | `campaigns:run` | Set Nameservers |
+| [`updateMailboxProfilePicture`](#op-updatemailboxprofilepicture) | `POST /api/v1/provider-domains/{domain_id}/mailbox-profile-picture` | external | `campaigns:run` | Update Mailbox Profile Picture |
+
+---
+
+<a id="op-addexternaldomains"></a>
+
+### `g8.api.providerDomains.addExternalDomains(input)`
+
+**Add External Domains**
+
+- HTTP: `POST /api/v1/provider-domains/add-external`
+- operationId: `add_external_domains_provider_domains_add_external_post` (also callable as `g8.api.call("add_external_domains_provider_domains_add_external_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Register domains you already own elsewhere for use as sending domains.
+Spends no credits — no registrar purchase happens here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AddExternalDomainsRequest` | yes | Request body; fields below. |
+
+Body fields (`AddExternalDomainsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domains` | `Array<string>` | yes | Domains already owned outside graph8, e.g. ['acme.com'] |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.addExternalDomains({ body: { domains: ["acme.com"] } });
+```
+
+---
+
+<a id="op-canceldomaintransfer"></a>
+
+### `g8.api.providerDomains.cancelDomainTransfer(input)`
+
+**Cancel Domain Transfer**
+
+- HTTP: `POST /api/v1/provider-domains/cancel-transfer`
+- operationId: `cancel_domain_transfer_provider_domains_cancel_transfer_post` (also callable as `g8.api.call("cancel_domain_transfer_provider_domains_cancel_transfer_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Abort an in-flight transfer.
+
+Refunds are the registrar's business, not graph8's: cancelling stops the
+move, it does not guarantee the transfer fee back.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainTransferCancelRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainTransferCancelRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain_id` | `integer` | yes | Provider domain id whose transfer should be aborted > 0 |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.providerDomains.cancelDomainTransfer({ body: { domain_id: 1 } });
+```
+
+---
+
+<a id="op-checkdomainavailability"></a>
+
+### `g8.api.providerDomains.checkDomainAvailability(input)`
+
+**Check Domain Availability**
+
+- HTTP: `POST /api/v1/provider-domains/check-availability`
+- operationId: `check_domain_availability_provider_domains_check_availability_post` (also callable as `g8.api.call("check_domain_availability_provider_domains_check_availability_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Check whether a domain is available to buy, and its price. Spends no credits.
+
+Proxies the same handler the in-app purchase wizard's first step calls.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainAvailabilityCheckRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainAvailabilityCheckRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Domain to check, e.g. acme-outreach.com |
+| `body.provider` | `"registrar" \| "managed"` | no | Provisioning path to check availability/price against. default `"registrar"` |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.checkDomainAvailability({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-checkdomainpropagation"></a>
+
+### `g8.api.providerDomains.checkDomainPropagation(input)`
+
+**Check Domain Propagation**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/check-propagation`
+- operationId: `check_domain_propagation_provider_domains__domain_id__check_propagation_post` (also callable as `g8.api.call("check_domain_propagation_provider_domains__domain_id__check_propagation_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Check whether a connected domain's nameservers have propagated yet.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Provider domain ID (provider_domains.id) — from GET /provider-domains |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.checkDomainPropagation({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-checkexternalavailability"></a>
+
+### `g8.api.providerDomains.checkExternalAvailability(input)`
+
+**Check External Availability**
+
+- HTTP: `POST /api/v1/provider-domains/check-external-availability`
+- operationId: `check_external_availability_provider_domains_check_external_availability_post` (also callable as `g8.api.call("check_external_availability_provider_domains_check_external_availability_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Can this domain be attached as an EXTERNAL sending domain? SPENDS NOTHING.
+
+External means graph8 never owns or bills the registration - you keep the
+domain where it is and point its DNS here. The follow-up is
+`POST /provider-domains/add-external`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ExternalDomainAvailabilityRequest` | yes | Request body; fields below. |
+
+Body fields (`ExternalDomainAvailabilityRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Domain to check, e.g. acme.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.providerDomains.checkExternalAvailability({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-checkmailboxstatus"></a>
+
+### `g8.api.providerDomains.checkMailboxStatus(input)`
+
+**Check Mailbox Status**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/check-mailbox-status`
+- operationId: `check_mailbox_status_provider_domains__domain_id__check_mailbox_status_post` (also callable as `g8.api.call("check_mailbox_status_provider_domains__domain_id__check_mailbox_status_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Re-check one mailbox's provisioning with the provider, and record the answer.
+
+Not a pure read: a mailbox the provider now reports as ready is flipped to
+active here, which is what makes it usable for sending.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `DomainMailboxRefRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainMailboxRefRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) on this domain > 0 |
+
+**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.providerDomains.checkMailboxStatus({ path: { domain_id: 123 }, body: { mailbox_id: 1 } });
+```
+
+---
+
+<a id="op-checktransferavailability"></a>
+
+### `g8.api.providerDomains.checkTransferAvailability(input)`
+
+**Check Transfer Availability**
+
+- HTTP: `POST /api/v1/provider-domains/check-transfer-availability`
+- operationId: `check_transfer_availability_provider_domains_check_transfer_availability_post` (also callable as `g8.api.call("check_transfer_availability_provider_domains_check_transfer_availability_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Can this domain be transferred in, and what would it cost? SPENDS NOTHING.
+
+Different question from `check-availability`, which asks whether a domain
+is free to REGISTER. This one asks about a domain you already own at
+another registrar.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainTransferAvailabilityRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainTransferAvailabilityRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Domain to check, 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.providerDomains.checkTransferAvailability({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-checkoutpurchasedomains"></a>
+
+### `g8.api.providerDomains.checkoutPurchaseDomains(input)`
+
+**Checkout Purchase Domains**
+
+- HTTP: `POST /api/v1/provider-domains/checkout-purchase`
+- operationId: `checkout_purchase_domains_provider_domains_checkout_purchase_post` (also callable as `g8.api.call("checkout_purchase_domains_provider_domains_checkout_purchase_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Buy one or more sending domains. SPENDS REAL CREDITS — unrestricted, same
+as the app; there is no per-key spend cap.
+
+Send an ``Idempotency-Key`` header to make a retry safe (a repeat with the
+same key returns the original response instead of buying twice). Returns
+402 if the credit hold can't clear, 422 if the org's plan can't fund a
+purchase at all (same gate the app UI checks), 400 for a pilot-only
+provider or an unsupported TLD.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainPurchaseRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainPurchaseRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_info` | `Record<string, string>` | yes | Registrant contact used for domain registration |
+| `body.domains` | `Array<string>` | yes | Domains to buy, e.g. ['acme-outreach.com']. Up to 50 per request. max items 50 |
+| `body.period` | `integer` | no | Registration period, in years default `1`, min 1 |
+| `body.provider` | `"registrar" \| "managed" \| "pilot"` | no | Provisioning path. 'pilot' is limited to allowlisted orgs and otherwise returns 400. default `"registrar"` |
+| `body.spare_domains` | `Array<string>` | no | Extra domains bought as spare warm-up capacity (warm from day 0, excluded from sending until promoted). Up to 50 per request. max items 50 |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.checkoutPurchaseDomains({ body: { contact_info: {}, domains: ["acme.com"] } });
+```
+
+---
+
+<a id="op-checkoutpurchasemailboxes"></a>
+
+### `g8.api.providerDomains.checkoutPurchaseMailboxes(input)`
+
+**Checkout Purchase Mailboxes**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/checkout-mailboxes`
+- operationId: `checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post` (also callable as `g8.api.call("checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Buy one or more mailboxes on a domain. SPENDS REAL CREDITS — unrestricted,
+same as the app; there is no per-key spend cap.
+
+Send an ``Idempotency-Key`` header to make a retry safe. Returns 402 if
+the credit hold can't clear, 422 if the org's plan can't fund a purchase
+at all, 400 for an unconnected/wrong-platform domain, too many mailboxes,
+or a missing username, 404 if ``domain_id`` doesn't belong to this org.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Provider domain ID (provider_domains.id) — from GET /provider-domains |
+| `body` | `MailboxPurchaseRequest` | yes | Request body; fields below. |
+
+Body fields (`MailboxPurchaseRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailboxes` | `Array<MailboxPurchaseItem>` | yes | Mailboxes to create. Up to 5 per domain for a provider='managed' purchase, and up to 250 per request. max items 250 |
+| `body.enable_warmup` | `boolean` | no | Enroll each mailbox in warmup immediately after purchase default `true` |
+| `body.platform` | `"GOOGLE" \| "MICROSOFT" \| null` | no | Mailbox platform. Required when provider='managed'. |
+| `body.provider` | `"registrar" \| "managed" \| "pilot"` | no | default `"registrar"` |
+| `body.warmup_engine` | `"instantly" \| "smartlead" \| "managed" \| null` | no | Warmup engine. Omit to use the account default. |
+| `body.warmup_settings` | `Record<string, unknown> \| null` | no |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.checkoutPurchaseMailboxes({ path: { domain_id: 123 }, body: { mailboxes: [{}] } });
+```
+
+---
+
+<a id="op-checkouttransferdomain"></a>
+
+### `g8.api.providerDomains.checkoutTransferDomain(input)`
+
+**Checkout Transfer Domain**
+
+- HTTP: `POST /api/v1/provider-domains/checkout-transfer`
+- operationId: `checkout_transfer_domain_provider_domains_checkout_transfer_post` (also callable as `g8.api.call("checkout_transfer_domain_provider_domains_checkout_transfer_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Transfer a domain you own elsewhere into graph8. SPENDS REAL CREDITS.
+
+This is a purchase: it pays the registrar to move the domain and extends
+the registration. There is no per-key spend cap, the same as the app.
+
+Send an `Idempotency-Key` header so a retry cannot pay twice. 202 means
+the transfer was accepted and is now in the registrar's hands - it
+completes asynchronously and can take days. 402 if the credit hold cannot
+clear, 422 if the org's plan cannot fund a purchase at all.
+
+Get `auth_info` from your current registrar first; a wrong code fails the
+transfer at the registrar AFTER the money has moved.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainTransferRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainTransferRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.auth_info` | `string` | yes | Transfer authorisation code from your current registrar |
+| `body.contact_info` | `Record<string, string>` | yes | Registrant contact recorded with the registrar |
+| `body.domain` | `string` | yes | Domain to transfer in, 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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.providerDomains.checkoutTransferDomain({
+  body: { auth_info: "example", contact_info: {}, domain: "acme.com" },
+});
+```
+
+---
+
+<a id="op-connectprovider"></a>
+
+### `g8.api.providerDomains.connectProvider(input)`
+
+**Connect Provider**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/connect-provider`
+- operationId: `connect_provider_provider_domains__domain_id__connect_provider_post` (also callable as `g8.api.call("connect_provider_provider_domains__domain_id__connect_provider_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Connect a purchased domain to the managed mailbox-provisioning backend.
+
+Required once per domain before ``checkout-mailboxes`` will succeed for a
+managed (``provider='managed'``) purchase — an unconnected domain 400s
+there with an actionable message pointing back here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Provider domain ID (provider_domains.id) — from GET /provider-domains |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.connectProvider({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-deletedomainforwarding"></a>
+
+### `g8.api.providerDomains.deleteDomainForwarding(input)`
+
+**Delete Domain Forwarding**
+
+- HTTP: `DELETE /api/v1/provider-domains/{domain_id}/forwarding`
+- operationId: `delete_domain_forwarding_provider_domains__domain_id__forwarding_delete` (also callable as `g8.api.call("delete_domain_forwarding_provider_domains__domain_id__forwarding_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Stop forwarding this domain's mail. Mail then lands in its own mailboxes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.providerDomains.deleteDomainForwarding({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-deletedomainmailbox"></a>
+
+### `g8.api.providerDomains.deleteDomainMailbox(input)`
+
+**Delete Domain Mailbox**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/delete-mailbox`
+- operationId: `delete_domain_mailbox_provider_domains__domain_id__delete_mailbox_post` (also callable as `g8.api.call("delete_domain_mailbox_provider_domains__domain_id__delete_mailbox_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete a mailbox at the provider. NOT REVERSIBLE.
+
+The mailbox stops existing upstream and its mail goes with it. Different
+from `DELETE /mailboxes/{mailbox_id}`, which removes graph8's record of a
+mailbox and leaves the provider's copy alone. A domain's admin mailbox
+cannot be deleted - it is what manages the domain.
+
+To stop paying for a purchased mailbox without destroying it, use
+`POST /mailboxes/{mailbox_id}/request-cancellation` instead.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `DomainMailboxRefRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainMailboxRefRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) on this domain > 0 |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.providerDomains.deleteDomainMailbox({ path: { domain_id: 123 }, body: { mailbox_id: 1 } });
+```
+
+---
+
+<a id="op-generatedomainnames"></a>
+
+### `g8.api.providerDomains.generateDomainNames(input)`
+
+**Generate Domain Names**
+
+- HTTP: `POST /api/v1/provider-domains/generate-domains`
+- operationId: `generate_domain_names_provider_domains_generate_domains_post` (also callable as `g8.api.call("generate_domain_names_provider_domains_generate_domains_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Suggest buyable domain names around a keyword. SPENDS NOTHING.
+
+A naming aid, not a reservation: a name returned here can still be gone by
+the time you buy it, so `check-availability` remains the authority.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainNameGenerateRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainNameGenerateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword` | `string` | yes | Seed word the generated names are built around, e.g. 'acme' |
+| `body.count` | `integer` | no | How many suggestions to return default `5`, min 1, max 100 |
+| `body.prefixes` | `string \| null` | no | Comma-separated prefixes to try, e.g. 'get,try' |
+| `body.provider` | `"registrar" \| "managed" \| "pilot"` | no | Provisioning path to generate for default `"registrar"` |
+| `body.suffixes` | `string \| null` | no | Comma-separated suffixes to try, e.g. 'hq,mail' |
+
+**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.providerDomains.generateDomainNames({ body: { keyword: "example" } });
+```
+
+---
+
+<a id="op-getdomaininfo"></a>
+
+### `g8.api.providerDomains.getDomainInfo(input)`
+
+**Get Domain Info**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/info`
+- operationId: `get_domain_info_provider_domains__domain_id__info_post` (also callable as `g8.api.call("get_domain_info_provider_domains__domain_id__info_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The registrar's record for this domain: expiry, nameservers, lock state.
+
+Read-only, and live - it asks the registrar rather than returning the last
+thing graph8 stored.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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.providerDomains.getDomainInfo({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-getexternaldomaininfo"></a>
+
+### `g8.api.providerDomains.getExternalDomainInfo(input)`
+
+**Get External Domain Info**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/external-info`
+- operationId: `get_external_domain_info_provider_domains__domain_id__external_info_post` (also callable as `g8.api.call("get_external_domain_info_provider_domains__domain_id__external_info_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The DNS records an EXTERNAL domain must publish for graph8 to send from it.
+
+Read-only. Add them at whoever hosts the domain's DNS, then confirm with
+`POST /provider-domains/{domain_id}/check-propagation`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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.providerDomains.getExternalDomainInfo({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-getproviderstatus"></a>
+
+### `g8.api.providerDomains.getProviderStatus(input)`
+
+**Get Provider Status**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/provider-status`
+- operationId: `get_provider_status_provider_domains__domain_id__provider_status_post` (also callable as `g8.api.call("get_provider_status_provider_domains__domain_id__provider_status_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+How far this domain has got through managed provisioning. Reads only.
+
+`provider_status` is the connection state; the `provider_*_uid` fields are
+opaque references you may need when contacting support.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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.providerDomains.getProviderStatus({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-getprovisioningstates"></a>
+
+### `g8.api.providerDomains.getProvisioningStates(input)`
+
+**Get Provisioning States**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/provisioning-states`
+- operationId: `get_provisioning_states_provider_domains__domain_id__provisioning_states_post` (also callable as `g8.api.call("get_provisioning_states_provider_domains__domain_id__provisioning_states_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Live provisioning step and last error for up to 50 mailboxes. Reads only.
+
+Best-effort by design: a mailbox with no live provisioning run - finished,
+never started, or aged out - comes back `null` rather than erroring, so
+poll this and fall back to the mailbox's own status.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `ProvisioningStatesRequest` | yes | Request body; fields below. |
+
+Body fields (`ProvisioningStatesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_ids` | `Array<integer>` | no | Mailbox ids to report on. Up to 50. max items 50 |
+
+**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.providerDomains.getProvisioningStates({ path: { domain_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-getsendingdomainstats"></a>
+
+### `g8.api.providerDomains.getSendingDomainStats(input?)`
+
+**Get Sending Domain Stats**
+
+- HTTP: `GET /api/v1/provider-domains/stats`
+- operationId: `get_sending_domain_stats_provider_domains_stats_get` (also callable as `g8.api.call("get_sending_domain_stats_provider_domains_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Counts across the org's sending domains and mailboxes. Reads only.
+
+Totals, active and external domains, provisioning progress, domains whose
+registrant has not verified, and the warmed mailboxes that are ready for
+outreach but not yet in any live sequence. The same figures the app's
+dashboard tiles show.
+
+**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.providerDomains.getSendingDomainStats();
+```
+
+---
+
+<a id="op-getsendingpricing"></a>
+
+### `g8.api.providerDomains.getSendingPricing(input?)`
+
+**Get Sending Pricing**
+
+- HTTP: `GET /api/v1/provider-domains/pricing`
+- operationId: `get_sending_pricing_provider_domains_pricing_get` (also callable as `g8.api.call("get_sending_pricing_provider_domains_pricing_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+What a mailbox and its warmup cost, in credits. SPENDS NOTHING.
+
+`credits_per_warmup_month` is the RECURRING monthly charge per mailbox
+while warmup is on - the number `auto-warmup` commits you to for every
+mailbox bought on a domain afterwards.
+
+**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.providerDomains.getSendingPricing();
+```
+
+---
+
+<a id="op-gettransferinfo"></a>
+
+### `g8.api.providerDomains.getTransferInfo(input)`
+
+**Get Transfer Info**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/transfer-info`
+- operationId: `get_transfer_info_provider_domains__domain_id__transfer_info_post` (also callable as `g8.api.call("get_transfer_info_provider_domains__domain_id__transfer_info_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Where an in-flight transfer has got to. Reads only.
+
+POST rather than GET because that is the app's own spelling, kept so the
+two surfaces describe one operation rather than two.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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.providerDomains.getTransferInfo({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-listdomainmailboxes"></a>
+
+### `g8.api.providerDomains.listDomainMailboxes(input)`
+
+**List Domain Mailboxes**
+
+- HTTP: `GET /api/v1/provider-domains/{domain_id}/mailboxes`
+- operationId: `list_domain_mailboxes_provider_domains__domain_id__mailboxes_get` (also callable as `g8.api.call("list_domain_mailboxes_provider_domains__domain_id__mailboxes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The mailboxes on one sending domain, a page at a time. Reads only.
+
+GET here although the app spells it POST: it changes nothing, and a read
+should be cacheable and retryable as one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `query.start_row` | `integer` | no | First row, zero-based default `0` |
+| `query.end_row` | `integer` | no | Row after the last one returned default `100` |
+
+**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.providerDomains.listDomainMailboxes({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-listmailboxesforstat"></a>
+
+### `g8.api.providerDomains.listMailboxesForStat(input)`
+
+**List Mailboxes For Stat**
+
+- HTTP: `GET /api/v1/provider-domains/stats/mailboxes/{stat_key}`
+- operationId: `list_mailboxes_for_stat_provider_domains_stats_mailboxes__stat_key__get` (also callable as `g8.api.call("list_mailboxes_for_stat_provider_domains_stats_mailboxes__stat_key__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The mailboxes a stat counts - its result set IS that number's denominator.
+
+Use this rather than filtering `GET /mailboxes` yourself, so your list and
+the count can never disagree about which mailboxes match.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.stat_key` | `"warmup_ready_to_outreach"` | yes | Which stat to drill into |
+| `query.limit` | `integer` | no | Newest first. The app's own ceiling. default `500` |
+
+**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.providerDomains.listMailboxesForStat({ path: { stat_key: "warmup_ready_to_outreach" } });
+```
+
+---
+
+<a id="op-listproviderdomains"></a>
+
+### `g8.api.providerDomains.listProviderDomains(input?)`
+
+**List Provider Domains**
+
+- HTTP: `GET /api/v1/provider-domains`
+- operationId: `list_provider_domains_provider_domains_get` (also callable as `g8.api.call("list_provider_domains_provider_domains_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+List the org's sending domains.
+
+This is the discovery route: every per-domain endpoint below needs a
+``domain_id`` from here first. Mirrors the core of the app's own
+``POST /provider-domains/fetch`` (mailbox count via a correlated
+subquery), without its ag-grid filter/sort surface.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `20` |
+
+**Returns** `ApiResponse_List_ProviderDomainResponse__`: the envelope `{ data: Array<ProviderDomainResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ProviderDomainResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `id` | `integer` | yes |  |
+| `provider_connected` | `boolean` | yes | Whether this domain is connected to the managed mailbox-provisioning backend. Required before checkout-mailboxes will succeed for a managed purchase — connect it first with POST .../connect-provider. |
+| `source` | `string` | yes | How the domain entered the org, e.g. purchased \| transferred \| external |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `dns_zone_created` | `boolean` | no | default `false` |
+| `expires_at` | `string \| null` | no |  |
+| `is_external` | `boolean` | no | default `false` |
+| `is_transfer` | `boolean` | no | default `false` |
+| `mailbox_count` | `integer` | no | default `0` |
+| `purchase_date` | `string \| null` | no |  |
+| `purchase_period` | `integer \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.providerDomains.listProviderDomains();
+```
+
+---
+
+<a id="op-refreshdomainfromprovider"></a>
+
+### `g8.api.providerDomains.refreshDomainFromProvider(input)`
+
+**Refresh Domain From Provider**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/refresh-from-provider`
+- operationId: `refresh_domain_from_provider_provider_domains__domain_id__refresh_from_provider_post` (also callable as `g8.api.call("refresh_domain_from_provider_provider_domains__domain_id__refresh_from_provider_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Pull this domain's current state from the provisioning backend and store it.
+
+Writes: graph8's copy is replaced with what the provider says. Use it when
+`provider-status` looks stale against reality.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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.providerDomains.refreshDomainFromProvider({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-regeneratenameservers"></a>
+
+### `g8.api.providerDomains.regenerateNameservers(input)`
+
+**Regenerate Nameservers**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/regenerate-nameservers`
+- operationId: `regenerate_nameservers_provider_domains__domain_id__regenerate_nameservers_post` (also callable as `g8.api.call("regenerate_nameservers_provider_domains__domain_id__regenerate_nameservers_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Mint a fresh set of nameservers for this domain.
+
+For a domain whose propagation window expired or whose nameservers were
+changed elsewhere. It issues NEW values - you still have to apply them,
+with `set-nameservers` for a graph8-registered domain or at your own DNS
+host for an external one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.regenerateNameservers({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-resendregistrantverification"></a>
+
+### `g8.api.providerDomains.resendRegistrantVerification(input)`
+
+**Resend Registrant Verification**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/resend-verification`
+- operationId: `resend_registrant_verification_provider_domains__domain_id__resend_verification_post` (also callable as `g8.api.call("resend_registrant_verification_provider_domains__domain_id__resend_verification_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Re-send the registrant verification mail.
+
+ICANN suspends a domain whose registrant never verifies, which takes the
+mailboxes on it down with it. Worth calling for any domain whose
+verification status is not `Verified`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.resendRegistrantVerification({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-resendtransferpassword"></a>
+
+### `g8.api.providerDomains.resendTransferPassword(input)`
+
+**Resend Transfer Password**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/resend-transfer-password`
+- operationId: `resend_transfer_password_provider_domains__domain_id__resend_transfer_password_post` (also callable as `g8.api.call("resend_transfer_password_provider_domains__domain_id__resend_transfer_password_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Re-send the transfer authorisation mail to the registrant address.
+
+Use when the original never arrived. It reaches a real inbox, so it is not
+a free retry loop - the registrar rate-limits it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.resendTransferPassword({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-resetmailboxpassword"></a>
+
+### `g8.api.providerDomains.resetMailboxPassword(input)`
+
+**Reset Mailbox Password**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/reset-password`
+- operationId: `reset_mailbox_password_provider_domains__domain_id__reset_password_post` (also callable as `g8.api.call("reset_mailbox_password_provider_domains__domain_id__reset_password_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Replace a provider mailbox's password.
+
+Anything already signed in with the old password - including graph8's own
+sending connection until it re-reads the mailbox - stops working
+immediately. The new password is write-only and is never returned by this
+or any other endpoint.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `MailboxPasswordResetRequest` | yes | Request body; fields below. |
+
+Body fields (`MailboxPasswordResetRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.email` | `string` | yes | Mailbox address whose password is being replaced |
+| `body.new_password` | `string` | yes | Write-only. Never returned by any endpoint. |
+
+**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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.providerDomains.resetMailboxPassword({
+  path: { domain_id: 123 },
+  body: { email: "jane@acme.com", new_password: "example" },
+});
+```
+
+---
+
+<a id="op-setautowarmup"></a>
+
+### `g8.api.providerDomains.setAutoWarmup(input)`
+
+**Set Auto Warmup**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/auto-warmup`
+- operationId: `set_auto_warmup_provider_domains__domain_id__auto_warmup_post` (also callable as `g8.api.call("set_auto_warmup_provider_domains__domain_id__auto_warmup_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Turn automatic warmup enrolment on or off for this domain. ON COMMITS SPEND.
+
+ON: every mailbox bought on this domain from now on is enrolled in warmup
+automatically, and warmup is a RECURRING monthly credit charge per mailbox
+(`GET /provider-domains/pricing` has the figure). It is the default.
+
+OFF: new mailboxes are not enrolled and not billed for warmup. It does NOT
+stop warmup already running on existing mailboxes - use
+`POST /warmup/{mailbox_id}/disable` for that - and it does not affect
+warmup you start by hand.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `AutoWarmupRequest` | yes | Request body; fields below. |
+
+Body fields (`AutoWarmupRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.enabled` | `boolean` | yes | True enrols new mailboxes automatically and bills warmup for them |
+
+**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.providerDomains.setAutoWarmup({ path: { domain_id: 123 }, body: { enabled: true } });
+```
+
+---
+
+<a id="op-setdnsrecords"></a>
+
+### `g8.api.providerDomains.setDnsRecords(input)`
+
+**Set Dns Records**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/dns`
+- operationId: `set_dns_records_provider_domains__domain_id__dns_post` (also callable as `g8.api.call("set_dns_records_provider_domains__domain_id__dns_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Set (or reset to default) the sending DNS records for a domain.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Provider domain ID (provider_domains.id) — from GET /provider-domains |
+| `body` | `DnsRecordsRequest` | yes | Request body; fields below. |
+
+Body fields (`DnsRecordsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.records` | `Record<string, Array<Record<string, unknown>>>` | no | DNS records by type, e.g. {'TXT': [...], 'MX': [...], 'CNAME': [...]} |
+| `body.reset_to_default` | `boolean` | no | Discard `records` and (re)apply graph8's default sending DNS zone default `false` |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.providerDomains.setDnsRecords({ path: { domain_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-setdomainforwarding"></a>
+
+### `g8.api.providerDomains.setDomainForwarding(input)`
+
+**Set Domain Forwarding**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/forwarding`
+- operationId: `set_domain_forwarding_provider_domains__domain_id__forwarding_post` (also callable as `g8.api.call("set_domain_forwarding_provider_domains__domain_id__forwarding_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Forward mail arriving at this domain to another address.
+
+REPLACES the current forwarding configuration rather than merging into it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `DomainForwardingRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainForwardingRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.attributes` | `Record<string, unknown>` | yes | Forwarding attributes accepted by the registrar |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.setDomainForwarding({ path: { domain_id: 123 }, body: { attributes: {} } });
+```
+
+---
+
+<a id="op-setnameservers"></a>
+
+### `g8.api.providerDomains.setNameservers(input)`
+
+**Set Nameservers**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/set-nameservers`
+- operationId: `set_nameservers_provider_domains__domain_id__set_nameservers_post` (also callable as `g8.api.call("set_nameservers_provider_domains__domain_id__set_nameservers_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Point this domain's nameservers at the managed mail backend, at the registrar.
+
+Only meaningful for a domain graph8 registered or transferred in. DNS
+propagation is not instant; confirm with `check-propagation`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.setNameservers({ path: { domain_id: 123 } });
+```
+
+---
+
+<a id="op-updatemailboxprofilepicture"></a>
+
+### `g8.api.providerDomains.updateMailboxProfilePicture(input)`
+
+**Update Mailbox Profile Picture**
+
+- HTTP: `POST /api/v1/provider-domains/{domain_id}/mailbox-profile-picture`
+- operationId: `update_mailbox_profile_picture_provider_domains__domain_id__mailbox_profile_picture_post` (also callable as `g8.api.call("update_mailbox_profile_picture_provider_domains__domain_id__mailbox_profile_picture_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Set the avatar recipients see on mail from this mailbox.
+
+`profile_picture` must be a URL the provider can fetch; it is downloaded
+server-side, not proxied through graph8.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain_id` | `integer` | yes | Sending domain id (provider_domains.id) - from GET /provider-domains |
+| `body` | `MailboxProfilePictureRequest` | yes | Request body; fields below. |
+
+Body fields (`MailboxProfilePictureRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) on this domain > 0 |
+| `body.profile_picture` | `string` | yes | Publicly reachable image URL |
+
+**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
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.providerDomains.updateMailboxProfilePicture({
+  path: { domain_id: 123 },
+  body: { mailbox_id: 1, profile_picture: "example" },
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-mailboxpurchaseitem"></a>
+
+### `MailboxPurchaseItem`
+
+One mailbox to create. Supply `username` for a managed purchase (`provider='managed'`) or a full `email` for `registrar`/`pilot`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `email` | `string \| null` | no | Full mailbox address, e.g. sales@acme.com |
+| `first_name` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no | Required (non-empty) for a managed purchase — an empty last name is rejected upstream and stalls provisioning. |
+| `password` | `string \| null` | no | Write-only. Never returned by any endpoint. |
+| `username` | `string \| null` | no | Local-part, e.g. 'sales' for sales@domain |