@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/newsletter.md

@@ -0,0 +1,2746 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.newsletter`: Newsletter
+
+61 operations (19 read, 18 write, 5 destructive, 7 billable, 12 external).
+
+15 of these also have a hand-written method (`g8.newsletter`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+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: [newsletter.d.ts](newsletter.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`activateNewsletter`](#op-activatenewsletter) | `POST /api/v1/newsletters/{newsletter_id}/activate` | external | `newsletter:run` | Activate Newsletter |
+| [`addSubscriber`](#op-addsubscriber) ★ | `POST /api/v1/newsletters/{newsletter_id}/subscribers` | external | `newsletter:run` | Add Subscriber |
+| [`batchTemplateGenerationStatus`](#op-batchtemplategenerationstatus) | `POST /api/v1/newsletters/templates/generation-status` | read | `newsletter:read` | Batch Template Generation Status |
+| [`cancelSend`](#op-cancelsend) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/cancel` | write | `newsletter:write` | Cancel Send |
+| [`cloneTemplate`](#op-clonetemplate) | `POST /api/v1/newsletters/templates/clone` | billable | `newsletter:run` | Clone Template |
+| [`completeNewsletter`](#op-completenewsletter) | `POST /api/v1/newsletters/{newsletter_id}/complete` | write | `newsletter:write` | Complete Newsletter |
+| [`createIssue`](#op-createissue) ★ | `POST /api/v1/newsletters/{newsletter_id}/issues` | external | `newsletter:run` | Create Issue |
+| [`createNewsletter`](#op-createnewsletter) ★ | `POST /api/v1/newsletters` | external | `newsletter:run` | Create Newsletter |
+| [`createTemplateFromLayout`](#op-createtemplatefromlayout) | `POST /api/v1/newsletters/templates/layout` | billable | `newsletter:run` | Create Template From Layout |
+| [`createTemplateFromPrompt`](#op-createtemplatefromprompt) | `POST /api/v1/newsletters/templates/custom` | billable | `newsletter:run` | Create Template From Prompt |
+| [`deleteIssue`](#op-deleteissue) | `DELETE /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | destructive | `newsletter:delete` | Delete Issue |
+| [`deleteNewsletterTemplate`](#op-deletenewslettertemplate) | `DELETE /api/v1/newsletters/templates/{template_id}` | destructive | `newsletter:delete` | Delete Newsletter Template |
+| [`deleteSubscriber`](#op-deletesubscriber) | `DELETE /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}` | destructive | `newsletter:delete` | Delete Subscriber |
+| [`disableNewsletterListSync`](#op-disablenewsletterlistsync) | `DELETE /api/v1/newsletters/{newsletter_id}/list-syncs/{audience_list_id}` | destructive | `newsletter:delete` | Disable Newsletter List Sync |
+| [`duplicateIssue`](#op-duplicateissue) ★ | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/duplicate` | external | `newsletter:run` | Duplicate Issue |
+| [`enableNewsletterListSync`](#op-enablenewsletterlistsync) | `POST /api/v1/newsletters/{newsletter_id}/list-syncs` | write | `newsletter:write` | Enable Newsletter List Sync |
+| [`generateNewsletterIssue`](#op-generatenewsletterissue) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generate` | billable | `newsletter:run` | Generate Newsletter Issue |
+| [`getIssue`](#op-getissue) ★ | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | read | `newsletter:read` | Get Issue |
+| [`getIssueAnalyticsKpis`](#op-getissueanalyticskpis) ★ | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/analytics/kpis` | read | `newsletter:read` | Get Issue Analytics Kpis |
+| [`getIssueGenerationStatus`](#op-getissuegenerationstatus) | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generation-status` | read | `newsletter:read` | Get Issue Generation Status |
+| [`getNewsletter`](#op-getnewsletter) ★ | `GET /api/v1/newsletters/{newsletter_id}` | read | `newsletter:read` | Get Newsletter |
+| [`getNewsletterIssueConversation`](#op-getnewsletterissueconversation) | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/conversation` | read | `newsletter:read` | Get Newsletter Issue Conversation |
+| [`getNewsletterSettings`](#op-getnewslettersettings) | `GET /api/v1/newsletters/{newsletter_id}/settings` | read | `newsletter:read` | Get Newsletter Settings |
+| [`getNewsletterSubscriberVerification`](#op-getnewslettersubscriberverification) | `GET /api/v1/newsletters/{newsletter_id}/subscribers/verify/status` | read | `newsletter:read` | Get Newsletter Subscriber Verification |
+| [`getSendStatus`](#op-getsendstatus) | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send` | read | `newsletter:read` | Get Send Status |
+| [`getSubscriberTimeline`](#op-getsubscribertimeline) | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/analytics/subscribers/{subscriber_id}/timeline` | read | `newsletter:read` | Get Subscriber Timeline |
+| [`importSubscribersFromAudience`](#op-importsubscribersfromaudience) | `POST /api/v1/newsletters/{newsletter_id}/subscribers/import-audience` | billable | `newsletter:run` | Import Subscribers From Audience |
+| [`linkNewsletterCampaign`](#op-linknewslettercampaign) | `PUT /api/v1/newsletters/{newsletter_id}/campaign` | write | `newsletter:write` | Link Newsletter Campaign |
+| [`listIssues`](#op-listissues) ★ | `GET /api/v1/newsletters/{newsletter_id}/issues` | read | `newsletter:read` | List Issues |
+| [`listNewsletterIssueVersions`](#op-listnewsletterissueversions) | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/versions` | read | `newsletter:read` | List Newsletter Issue Versions |
+| [`listNewsletterListSyncs`](#op-listnewsletterlistsyncs) | `GET /api/v1/newsletters/{newsletter_id}/list-syncs` | read | `newsletter:read` | List Newsletter List Syncs |
+| [`listNewsletters`](#op-listnewsletters) ★ | `GET /api/v1/newsletters` | read | `newsletter:read` | List Newsletters |
+| [`listSubscribers`](#op-listsubscribers) ★ | `GET /api/v1/newsletters/{newsletter_id}/subscribers` | read | `newsletter:read` | List Subscribers |
+| [`listTemplates`](#op-listtemplates) ★ | `GET /api/v1/newsletters/templates` | read | `newsletter:read` | List Templates |
+| [`newsletterDomainStatus`](#op-newsletterdomainstatus) | `GET /api/v1/newsletters/{newsletter_id}/settings/domain-status` | read | `newsletter:read` | Newsletter Domain Status |
+| [`pauseNewsletter`](#op-pausenewsletter) | `POST /api/v1/newsletters/{newsletter_id}/pause` | write | `newsletter:write` | Pause Newsletter |
+| [`pauseSend`](#op-pausesend) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/pause` | write | `newsletter:write` | Pause Send |
+| [`previewNewsletterSubscriberVerification`](#op-previewnewslettersubscriberverification) | `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify/preview` | read | `newsletter:read` | Preview Newsletter Subscriber Verification |
+| [`restoreNewsletterIssueVersion`](#op-restorenewsletterissueversion) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/versions/{version_num}/restore` | write | `newsletter:write` | Restore Newsletter Issue Version |
+| [`resumeNewsletter`](#op-resumenewsletter) | `POST /api/v1/newsletters/{newsletter_id}/resume` | external | `newsletter:run` | Resume Newsletter |
+| [`resumeSend`](#op-resumesend) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/resume` | external | `newsletter:run` | Resume Send |
+| [`rewriteIssueText`](#op-rewriteissuetext) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/rewrite-text` | billable | `newsletter:run` | Rewrite Issue Text |
+| [`runNewsletterListSync`](#op-runnewsletterlistsync) | `POST /api/v1/newsletters/{newsletter_id}/list-syncs/{audience_list_id}/run` | write | `newsletter:write` | Run Newsletter List Sync |
+| [`sendIssue`](#op-sendissue) ★ | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send` | external | `newsletter:run` | Send Issue |
+| [`sendTestEmail`](#op-sendtestemail) ★ | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send-test` | external | `newsletter:run` | Send Test Email |
+| [`setIssueButtonAction`](#op-setissuebuttonaction) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-button-action` | write | `newsletter:write` | Set Issue Button Action |
+| [`setIssueMediaEdit`](#op-setissuemediaedit) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-media-edit` | write | `newsletter:write` | Set Issue Media Edit |
+| [`setIssueText`](#op-setissuetext) | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-text` | write | `newsletter:write` | Set Issue Text |
+| [`setTemplateApproval`](#op-settemplateapproval) | `POST /api/v1/newsletters/templates/{template_id}/approval` | write | `newsletter:write` | Set Template Approval |
+| [`setTemplateButtonAction`](#op-settemplatebuttonaction) | `POST /api/v1/newsletters/templates/{template_id}/set-button-action` | write | `newsletter:write` | Set Template Button Action |
+| [`setTemplateMediaEdit`](#op-settemplatemediaedit) | `POST /api/v1/newsletters/templates/{template_id}/set-media-edit` | write | `newsletter:write` | Set Template Media Edit |
+| [`templateGenerationStatus`](#op-templategenerationstatus) | `GET /api/v1/newsletters/templates/{template_id}/generation-status` | read | `newsletter:read` | Template Generation Status |
+| [`unlinkNewsletterCampaign`](#op-unlinknewslettercampaign) | `DELETE /api/v1/newsletters/{newsletter_id}/campaign` | destructive | `newsletter:delete` | Unlink Newsletter Campaign |
+| [`unsubscribeSubscriber`](#op-unsubscribesubscriber) ★ | `PATCH /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}/unsubscribe` | external | `newsletter:run` | Unsubscribe Subscriber |
+| [`updateIssue`](#op-updateissue) ★ | `PUT /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | external | `newsletter:run` | Update Issue |
+| [`updateNewsletter`](#op-updatenewsletter) | `PATCH /api/v1/newsletters/{newsletter_id}` | write | `newsletter:write` | Update Newsletter |
+| [`updateNewsletterSettings`](#op-updatenewslettersettings) | `PUT /api/v1/newsletters/{newsletter_id}/settings` | write | `newsletter:write` | Update Newsletter Settings |
+| [`updateNewsletterTemplate`](#op-updatenewslettertemplate) | `PATCH /api/v1/newsletters/templates/{template_id}` | write | `newsletter:write` | Update Newsletter Template |
+| [`useTemplate`](#op-usetemplate) | `POST /api/v1/newsletters/templates/{template_id}/use` | write | `newsletter:write` | Use Template |
+| [`verifyNewsletterDomain`](#op-verifynewsletterdomain) | `POST /api/v1/newsletters/{newsletter_id}/settings/verify-domain` | external | `newsletter:run` | Verify Newsletter Domain |
+| [`verifyNewsletterSubscribers`](#op-verifynewslettersubscribers) | `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify` | billable | `newsletter:run` | Verify Newsletter Subscribers |
+
+---
+
+<a id="op-activatenewsletter"></a>
+
+### `g8.api.newsletter.activateNewsletter(input)`
+
+**Activate Newsletter**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/activate`
+- operationId: `activate_newsletter_newsletters__newsletter_id__activate_post` (also callable as `g8.api.call("activate_newsletter_newsletters__newsletter_id__activate_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: `newsletter:run`
+
+Take a draft newsletter live. LAUNCH-CLASS.
+
+Once active, the scheduler will send any issue whose scheduled time has
+passed - so this is not a metadata change, it is the switch that lets mail
+leave the building. Gated on `campaigns:launch`, the same permission the
+in-app route requires.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.activateNewsletter({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-addsubscriber"></a>
+
+### `g8.api.newsletter.addSubscriber(input)`
+
+**Add Subscriber**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/subscribers`
+- operationId: `add_subscriber_newsletters__newsletter_id__subscribers_post` (also callable as `g8.api.call("add_subscriber_newsletters__newsletter_id__subscribers_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.addSubscriber()`](../sdk-clients.md#g8-newsletter-addsubscriber)
+
+Add a single subscriber (staff action, status=subscribed). Also
+creates/links a first-class CRM contact so the subscriber joins the
+central suppression model (mirrors the manual public subscribe form).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `body` | `SubscriberAddRequest` | yes | Request body; fields below. |
+
+Body fields (`SubscriberAddRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.email` | `string` | yes | max length 255 |
+| `body.first_name` | `string \| null` | no | max length 255 |
+| `body.last_name` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_SubscriberSummary_`: the envelope `{ data: SubscriberSummary, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SubscriberSummary` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string \| null` | no |  |
+| `email` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `verification_status` | `string \| null` | no |  |
+
+**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.newsletter.addSubscriber({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { email: "jane@acme.com" },
+});
+```
+
+---
+
+<a id="op-batchtemplategenerationstatus"></a>
+
+### `g8.api.newsletter.batchTemplateGenerationStatus(input)`
+
+**Batch Template Generation Status**
+
+- HTTP: `POST /api/v1/newsletters/templates/generation-status`
+- operationId: `batch_template_generation_status_newsletters_templates_generation_status_post` (also callable as `g8.api.call("batch_template_generation_status_newsletters_templates_generation_status_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+Poll many template builds at once.
+
+A POST because the id list is the request, not a filter. Capped at 200 ids
+- the cap is the app's, and it exists because this is polled every couple
+of seconds.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TemplateGenerationStatusBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`TemplateGenerationStatusBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.template_ids` | `Array<integer>` | yes | max items 200 |
+
+**Returns** `ApiResponse_NewsletterListPayload_`: the envelope `{ data: NewsletterListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NewsletterListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.batchTemplateGenerationStatus({ body: { template_ids: [123] } });
+```
+
+---
+
+<a id="op-cancelsend"></a>
+
+### `g8.api.newsletter.cancelSend(input)`
+
+**Cancel Send**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/cancel`
+- operationId: `cancel_send_newsletters__newsletter_id__issues__issue_id__send_cancel_post` (also callable as `g8.api.call("cancel_send_newsletters__newsletter_id__issues__issue_id__send_cancel_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Abandon a send for good.
+
+Unlike pause, there is no resuming from here: whoever has already received
+the issue has received it, and nobody else will. Ungated for the same
+reason pause is.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `SendControlRequest` | no | Request body; fields below. |
+
+Body fields (`SendControlRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.reason` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.cancelSend({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-clonetemplate"></a>
+
+### `g8.api.newsletter.cloneTemplate(input)`
+
+**Clone Template**
+
+- HTTP: `POST /api/v1/newsletters/templates/clone`
+- operationId: `clone_template_newsletters_templates_clone_post` (also callable as `g8.api.call("clone_template_newsletters_templates_clone_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Import an existing email as a template.
+
+`source` decides which of `url`, `issue_id` and `html` is read - the other
+two are ignored rather than rejected, so sending all three is not an error
+and not a merge.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TemplateCloneRequest` | yes | Request body; fields below. |
+
+Body fields (`TemplateCloneRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source` | `string` | yes | `url`, `past_issue` or `html`. |
+| `body.html` | `string \| null` | no |  |
+| `body.issue_id` | `string \| null` | no |  |
+| `body.keep_images` | `boolean` | no | Keep the original images rather than dropping them. default `false` |
+| `body.reskin` | `boolean` | no | Restyle the import to the org's brand. default `true` |
+| `body.url` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.cloneTemplate({ body: { source: "example" } });
+```
+
+---
+
+<a id="op-completenewsletter"></a>
+
+### `g8.api.newsletter.completeNewsletter(input)`
+
+**Complete Newsletter**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/complete`
+- operationId: `complete_newsletter_newsletters__newsletter_id__complete_post` (also callable as `g8.api.call("complete_newsletter_newsletters__newsletter_id__complete_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Mark a newsletter completed. Terminal - it stops sending for good.
+
+The internal handler validates the transition, so an illegal move from the
+current status is refused there rather than silently applied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStatusResponse_`: the envelope `{ data: NewsletterStatusResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NewsletterStatusResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| null` | no |  |
+| `status` | `string \| null` | no | Status after the transition, e.g. `paused`, `completed`. |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.completeNewsletter({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-createissue"></a>
+
+### `g8.api.newsletter.createIssue(input)`
+
+**Create Issue**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues`
+- operationId: `create_issue_newsletters__newsletter_id__issues_post` (also callable as `g8.api.call("create_issue_newsletters__newsletter_id__issues_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.createIssue()`](../sdk-clients.md#g8-newsletter-createissue)
+
+Create a draft newsletter issue.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `body` | `IssueCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`IssueCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.html_body` | `string` | yes |  |
+| `body.subject` | `string` | yes | max length 2000 |
+| `body.plain_text` | `string \| null` | no |  |
+| `body.preview_text` | `string \| null` | no | max length 500 |
+| `body.reply_to` | `string (email) \| null` | no |  |
+| `body.sender_email` | `string (email) \| null` | no |  |
+| `body.sender_name` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_IssueDetail_`: the envelope `{ data: IssueDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IssueDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `newsletter_id` | `string \| null` | no |  |
+| `sent_at` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**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.newsletter.createIssue({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { html_body: "example", subject: "Example" },
+});
+```
+
+---
+
+<a id="op-createnewsletter"></a>
+
+### `g8.api.newsletter.createNewsletter(input)`
+
+**Create Newsletter**
+
+- HTTP: `POST /api/v1/newsletters`
+- operationId: `create_newsletter_newsletters_post` (also callable as `g8.api.call("create_newsletter_newsletters_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.create()`](../sdk-clients.md#g8-newsletter-create)
+
+Create a new newsletter (the parent container issues live under).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `NewsletterCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`NewsletterCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | max length 255 |
+| `body.goal` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterDetail_`: the envelope `{ data: NewsletterDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NewsletterDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience_list_id` | `unknown \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `goal` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `slug` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**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.newsletter.createNewsletter({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-createtemplatefromlayout"></a>
+
+### `g8.api.newsletter.createTemplateFromLayout(input)`
+
+**Create Template From Layout**
+
+- HTTP: `POST /api/v1/newsletters/templates/layout`
+- operationId: `create_template_from_layout_newsletters_templates_layout_post` (also callable as `g8.api.call("create_template_from_layout_newsletters_templates_layout_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Build a template from a named layout archetype. ASYNC and AI-backed.
+
+202 rather than 201: the row exists immediately but the copy inside it is
+still being generated. Poll
+`GET /newsletters/templates/{template_id}/generation-status` - a template
+read before that reports done is a half-written one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TemplateFromLayoutRequest` | yes | Request body; fields below. |
+
+Body fields (`TemplateFromLayoutRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.archetype_key` | `string` | yes | Which layout to build from. |
+| `body.audience_id` | `string \| null` | no | Audience the copy is aimed at. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.createTemplateFromLayout({ body: { archetype_key: "example" } });
+```
+
+---
+
+<a id="op-createtemplatefromprompt"></a>
+
+### `g8.api.newsletter.createTemplateFromPrompt(input)`
+
+**Create Template From Prompt**
+
+- HTTP: `POST /api/v1/newsletters/templates/custom`
+- operationId: `create_template_from_prompt_newsletters_templates_custom_post` (also callable as `g8.api.call("create_template_from_prompt_newsletters_templates_custom_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Build a template from a plain-language idea. ASYNC and AI-backed.
+
+`voice_reference_issue_ids` points the model at past issues to imitate,
+which is the difference between generic copy and something that sounds like
+the organisation. Same polling contract as `/templates/layout`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TemplateFromPromptRequest` | yes | Request body; fields below. |
+
+Body fields (`TemplateFromPromptRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.idea` | `string` | yes | What the email should say, in plain words. |
+| `body.audience_id` | `string \| null` | no |  |
+| `body.goal` | `string` | no | What it is for, e.g. `product`. default `"product"` |
+| `body.length` | `string \| null` | no |  |
+| `body.tone` | `string \| null` | no |  |
+| `body.variants` | `integer \| null` | no | How many alternatives to generate. default `1` |
+| `body.voice_reference_issue_ids` | `Array<string>` | no | Past issues to imitate the voice of. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.createTemplateFromPrompt({ body: { idea: "example" } });
+```
+
+---
+
+<a id="op-deleteissue"></a>
+
+### `g8.api.newsletter.deleteIssue(input)`
+
+**Delete Issue**
+
+- HTTP: `DELETE /api/v1/newsletters/{newsletter_id}/issues/{issue_id}`
+- operationId: `delete_issue_newsletters__newsletter_id__issues__issue_id__delete` (also callable as `g8.api.call("delete_issue_newsletters__newsletter_id__issues__issue_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `newsletter:delete`
+
+Delete a DRAFT issue.
+
+Drafts only - an issue that has been sent is a record of mail real people
+received and the app refuses to remove it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.deleteIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-deletenewslettertemplate"></a>
+
+### `g8.api.newsletter.deleteNewsletterTemplate(input)`
+
+**Delete Newsletter Template**
+
+- HTTP: `DELETE /api/v1/newsletters/templates/{template_id}`
+- operationId: `delete_newsletter_template_newsletters_templates__template_id__delete` (also callable as `g8.api.call("delete_newsletter_template_newsletters_templates__template_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `newsletter:delete`
+
+Delete an org template.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `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.newsletter.deleteNewsletterTemplate({ path: { template_id: 123 } });
+```
+
+---
+
+<a id="op-deletesubscriber"></a>
+
+### `g8.api.newsletter.deleteSubscriber(input)`
+
+**Delete Subscriber**
+
+- HTTP: `DELETE /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}`
+- operationId: `delete_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__delete` (also callable as `g8.api.call("delete_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `newsletter:delete`
+
+Remove a subscriber outright.
+
+DIFFERENT from `PATCH .../subscribers/{id}/unsubscribe`, which keeps the
+row and records that they opted out. Deleting loses that record, so the
+same address can be re-imported and mailed again - which is usually not
+what a person who unsubscribed wanted. Unsubscribe unless you are erasing
+someone on request.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.subscriber_id` | `integer` | yes | Subscriber id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.deleteSubscriber({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    subscriber_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-disablenewsletterlistsync"></a>
+
+### `g8.api.newsletter.disableNewsletterListSync(input)`
+
+**Disable Newsletter List Sync**
+
+- HTTP: `DELETE /api/v1/newsletters/{newsletter_id}/list-syncs/{audience_list_id}`
+- operationId: `disable_newsletter_list_sync_newsletters__newsletter_id__list_syncs__audience_list_id__delete` (also callable as `g8.api.call("disable_newsletter_list_sync_newsletters__newsletter_id__list_syncs__audience_list_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `newsletter:delete`
+
+Detach an audience list. Subscribers already added are NOT removed -
+this stops future syncs, it does not unsubscribe anyone.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.audience_list_id` | `integer` | yes | Audience list id. |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `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.newsletter.disableNewsletterListSync({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    audience_list_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-duplicateissue"></a>
+
+### `g8.api.newsletter.duplicateIssue(input)`
+
+**Duplicate Issue**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/duplicate`
+- operationId: `duplicate_issue_newsletters__newsletter_id__issues__issue_id__duplicate_post` (also callable as `g8.api.call("duplicate_issue_newsletters__newsletter_id__issues__issue_id__duplicate_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.duplicateIssue()`](../sdk-clients.md#g8-newsletter-duplicateissue)
+
+Duplicate any issue as a new draft.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Source issue id (any status) |
+
+**Returns** `ApiResponse_IssueDetail_`: the envelope `{ data: IssueDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IssueDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `newsletter_id` | `string \| null` | no |  |
+| `sent_at` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**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.newsletter.duplicateIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-enablenewsletterlistsync"></a>
+
+### `g8.api.newsletter.enableNewsletterListSync(input)`
+
+**Enable Newsletter List Sync**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/list-syncs`
+- operationId: `enable_newsletter_list_sync_newsletters__newsletter_id__list_syncs_post` (also callable as `g8.api.call("enable_newsletter_list_sync_newsletters__newsletter_id__list_syncs_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Attach an audience list, and run the first sync inline.
+
+`attested_text` is stored VERBATIM: it is the consent wording the operator
+saw when they asserted these people opted in, kept so the trail survives
+future copy edits. Pass the exact text your UI showed - not a summary.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `body` | `ListSyncEnableRequest` | yes | Request body; fields below. |
+
+Body fields (`ListSyncEnableRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_list_id` | `integer` | yes | Audience list to attach. |
+| `body.attested_text` | `string \| null` | no | The exact consent wording shown to the operator, stored VERBATIM so the trail survives future copy edits. Send what your UI displayed, not a summary of it. |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.enableNewsletterListSync({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { audience_list_id: 123 },
+});
+```
+
+---
+
+<a id="op-generatenewsletterissue"></a>
+
+### `g8.api.newsletter.generateNewsletterIssue(input)`
+
+**Generate Newsletter Issue**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generate`
+- operationId: `generate_newsletter_issue_newsletters__newsletter_id__issues__issue_id__generate_post` (also callable as `g8.api.call("generate_newsletter_issue_newsletters__newsletter_id__issues__issue_id__generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Generate the issue's content with AI (runs a model; billable). Poll `generation-status`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `NewsletterIssueGenerateRequest` | yes | Request body; fields below. |
+
+Body fields (`NewsletterIssueGenerateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.html_mode` | `"email_safe" \| "modern"` | no | `email_safe`: table layout, inline CSS. `modern`: div layout. default `"email_safe"` |
+| `body.prompt` | `string \| null` | no | What the issue should cover. |
+| `body.template_id` | `integer \| null` | no | Base the issue on this template. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `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.newsletter.generateNewsletterIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: {},
+});
+```
+
+---
+
+<a id="op-getissue"></a>
+
+### `g8.api.newsletter.getIssue(input)`
+
+**Get Issue**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}`
+- operationId: `get_issue_newsletters__newsletter_id__issues__issue_id__get` (also callable as `g8.api.call("get_issue_newsletters__newsletter_id__issues__issue_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.getIssue()`](../sdk-clients.md#g8-newsletter-getissue)
+
+Get a single newsletter issue with stats.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Issue id |
+
+**Returns** `ApiResponse_IssueDetail_`: the envelope `{ data: IssueDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IssueDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `newsletter_id` | `string \| null` | no |  |
+| `sent_at` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-getissueanalyticskpis"></a>
+
+### `g8.api.newsletter.getIssueAnalyticsKpis(input)`
+
+**Get Issue Analytics Kpis**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/analytics/kpis`
+- operationId: `get_issue_analytics_kpis_newsletters__newsletter_id__issues__issue_id__analytics_kpis_get` (also callable as `g8.api.call("get_issue_analytics_kpis_newsletters__newsletter_id__issues__issue_id__analytics_kpis_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.issueKpis()`](../sdk-clients.md#g8-newsletter-issuekpis)
+
+Bucketed KPI counters for a sent issue (opens, clicks, bounces, ...).
+
+Honors the stale-flag pattern: a backend read failure returns HTTP 200
+with ``stale=true`` and an empty ``kpis`` bucket rather than a 500, so
+callers can distinguish "genuinely zero engagement yet" from "read
+failed" without a try/except.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Issue id |
+
+**Returns** `ApiResponse_IssueAnalyticsKpis_`: the envelope `{ data: IssueAnalyticsKpis, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IssueAnalyticsKpis` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `kpis` | `Record<string, unknown>` | no |  |
+| `last_updated_at` | `string \| null` | no |  |
+| `stale` | `boolean \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getIssueAnalyticsKpis({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-getissuegenerationstatus"></a>
+
+### `g8.api.newsletter.getIssueGenerationStatus(input)`
+
+**Get Issue Generation Status**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generation-status`
+- operationId: `get_issue_generation_status_newsletters__newsletter_id__issues__issue_id__generation_status_get` (also callable as `g8.api.call("get_issue_generation_status_newsletters__newsletter_id__issues__issue_id__generation_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+How far along an issue's AI generation is.
+
+Read this before sending a generated issue: an issue whose generation has
+not finished has partial HTML, and sending it mails the partial version.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getIssueGenerationStatus({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-getnewsletter"></a>
+
+### `g8.api.newsletter.getNewsletter(input)`
+
+**Get Newsletter**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}`
+- operationId: `get_newsletter_newsletters__newsletter_id__get` (also callable as `g8.api.call("get_newsletter_newsletters__newsletter_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.get()`](../sdk-clients.md#g8-newsletter-get)
+
+Get a single newsletter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+
+**Returns** `ApiResponse_NewsletterDetail_`: the envelope `{ data: NewsletterDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NewsletterDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience_list_id` | `unknown \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `goal` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `slug` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getNewsletter({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getnewsletterissueconversation"></a>
+
+### `g8.api.newsletter.getNewsletterIssueConversation(input)`
+
+**Get Newsletter Issue Conversation**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/conversation`
+- operationId: `get_newsletter_issue_conversation_newsletters__newsletter_id__issues__issue_id__conversation_get` (also callable as `g8.api.call("get_newsletter_issue_conversation_newsletters__newsletter_id__issues__issue_id__conversation_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+The AI editing conversation recorded on an issue.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getNewsletterIssueConversation({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-getnewslettersettings"></a>
+
+### `g8.api.newsletter.getNewsletterSettings(input)`
+
+**Get Newsletter Settings**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/settings`
+- operationId: `get_newsletter_settings_newsletters__newsletter_id__settings_get` (also callable as `g8.api.call("get_newsletter_settings_newsletters__newsletter_id__settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+Who this newsletter sends as, and whether double opt-in is active.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getNewsletterSettings({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getnewslettersubscriberverification"></a>
+
+### `g8.api.newsletter.getNewsletterSubscriberVerification(input)`
+
+**Get Newsletter Subscriber Verification**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/subscribers/verify/status`
+- operationId: `get_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_status_get` (also callable as `g8.api.call("get_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+The verification job in progress for this newsletter, if any.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getNewsletterSubscriberVerification({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getsendstatus"></a>
+
+### `g8.api.newsletter.getSendStatus(input)`
+
+**Get Send Status**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send`
+- operationId: `get_send_status_newsletters__newsletter_id__issues__issue_id__send_get` (also callable as `g8.api.call("get_send_status_newsletters__newsletter_id__issues__issue_id__send_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+Where an in-flight send has got to.
+
+GET on the same path the published POST starts a send on. `{"active": false}`
+means nothing is running - which is also what you get after a send has
+finished, so this is a progress read rather than a history one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getSendStatus({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-getsubscribertimeline"></a>
+
+### `g8.api.newsletter.getSubscriberTimeline(input)`
+
+**Get Subscriber Timeline**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/analytics/subscribers/{subscriber_id}/timeline`
+- operationId: `get_subscriber_timeline_newsletters__newsletter_id__issues__issue_id__analytics_subscribers__subscriber_id__timeline_get` (also callable as `g8.api.call("get_subscriber_timeline_newsletters__newsletter_id__issues__issue_id__analytics_subscribers__subscriber_id__timeline_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+One subscriber's whole story for one issue: delivered, opened, clicked,
+bounced, complained, and when.
+
+The published KPI read gives the totals; this answers "what happened to
+THIS person", which is what a support question actually needs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `path.subscriber_id` | `integer` | yes | Subscriber id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.getSubscriberTimeline({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+    subscriber_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-importsubscribersfromaudience"></a>
+
+### `g8.api.newsletter.importSubscribersFromAudience(input)`
+
+**Import Subscribers From Audience**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/subscribers/import-audience`
+- operationId: `import_subscribers_from_audience_newsletters__newsletter_id__subscribers_import_audience_post` (also callable as `g8.api.call("import_subscribers_from_audience_newsletters__newsletter_id__subscribers_import_audience_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Bulk-import an audience list's contacts as subscribers.
+
+Asynchronous: the response acknowledges the job rather than reporting a
+final count. Whether the imported addresses are verified on the way in
+depends on `auto_verify_on_import` in the newsletter's settings, and
+verification SPENDS CREDIT.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `body` | `ImportAudienceRequest` | yes | Request body; fields below. |
+
+Body fields (`ImportAudienceRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_id` | `integer` | yes | Integer audience id, not a UUID. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.importSubscribersFromAudience({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { audience_id: 123 },
+});
+```
+
+---
+
+<a id="op-linknewslettercampaign"></a>
+
+### `g8.api.newsletter.linkNewsletterCampaign(input)`
+
+**Link Newsletter Campaign**
+
+- HTTP: `PUT /api/v1/newsletters/{newsletter_id}/campaign`
+- operationId: `link_newsletter_campaign_newsletters__newsletter_id__campaign_put` (also callable as `g8.api.call("link_newsletter_campaign_newsletters__newsletter_id__campaign_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Link a Studio campaign to this newsletter (replaces any existing link).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `body` | `NewsletterCampaignLinkRequest` | yes | Request body; fields below. |
+
+Body fields (`NewsletterCampaignLinkRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.campaign_id` | `string` | yes | The Studio campaign to link. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.linkNewsletterCampaign({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { campaign_id: "id" },
+});
+```
+
+---
+
+<a id="op-listissues"></a>
+
+### `g8.api.newsletter.listIssues(input)`
+
+**List Issues**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues`
+- operationId: `list_issues_newsletters__newsletter_id__issues_get` (also callable as `g8.api.call("list_issues_newsletters__newsletter_id__issues_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.listIssues()`](../sdk-clients.md#g8-newsletter-listissues)
+
+List all issues for a newsletter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+
+**Returns** `ApiResponse_list_`: the envelope `{ data: Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listIssues({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listnewsletterissueversions"></a>
+
+### `g8.api.newsletter.listNewsletterIssueVersions(input)`
+
+**List Newsletter Issue Versions**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/versions`
+- operationId: `list_newsletter_issue_versions_newsletters__newsletter_id__issues__issue_id__versions_get` (also callable as `g8.api.call("list_newsletter_issue_versions_newsletters__newsletter_id__issues__issue_id__versions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+An issue's saved versions, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listNewsletterIssueVersions({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-listnewsletterlistsyncs"></a>
+
+### `g8.api.newsletter.listNewsletterListSyncs(input)`
+
+**List Newsletter List Syncs**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/list-syncs`
+- operationId: `list_newsletter_list_syncs_newsletters__newsletter_id__list_syncs_get` (also callable as `g8.api.call("list_newsletter_list_syncs_newsletters__newsletter_id__list_syncs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+Audience lists feeding this newsletter's subscribers.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `query.audience_list_id` | `integer \| null` | no | Resolve a CANDIDATE list that has no saved row yet. Returns a synthetic disabled entry carrying the live name and count, so a rebuilt enable dialog can state the number the worker will actually act on rather than a stale one. |
+
+**Returns** `ApiResponse_ListSyncListResponse_`: the envelope `{ data: ListSyncListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListSyncListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `list_syncs` | `Array<ListSync>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listNewsletterListSyncs({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listnewsletters"></a>
+
+### `g8.api.newsletter.listNewsletters(input?)`
+
+**List Newsletters**
+
+- HTTP: `GET /api/v1/newsletters`
+- operationId: `list_newsletters_newsletters_get` (also callable as `g8.api.call("list_newsletters_newsletters_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.list()`](../sdk-clients.md#g8-newsletter-list)
+
+List all newsletters for the org.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_`: the envelope `{ data: Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listNewsletters();
+```
+
+---
+
+<a id="op-listsubscribers"></a>
+
+### `g8.api.newsletter.listSubscribers(input)`
+
+**List Subscribers**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/subscribers`
+- operationId: `list_subscribers_newsletters__newsletter_id__subscribers_get` (also callable as `g8.api.call("list_subscribers_newsletters__newsletter_id__subscribers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.listSubscribers()`](../sdk-clients.md#g8-newsletter-listsubscribers)
+
+Paginated subscriber list for a newsletter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `query.page` | `integer` | no | default `1` |
+| `query.page_size` | `integer` | no | default `25` |
+| `query.search` | `string \| null` | no | Free-text search over email/name |
+| `query.status` | `string \| null` | no | Comma-separated status filter (e.g. 'subscribed,bounced') |
+
+**Returns** `ApiResponse_SubscriberListResponse_`: the envelope `{ data: SubscriberListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SubscriberListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<SubscriberSummary>` | no |  |
+| `page` | `integer` | no | default `1` |
+| `page_size` | `integer` | no | default `25` |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listSubscribers({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listtemplates"></a>
+
+### `g8.api.newsletter.listTemplates(input?)`
+
+**List Templates**
+
+- HTTP: `GET /api/v1/newsletters/templates`
+- operationId: `list_templates_newsletters_templates_get` (also callable as `g8.api.call("list_templates_newsletters_templates_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+- ★ Hand-written: [`g8.newsletter.templates()`](../sdk-clients.md#g8-newsletter-templates)
+
+List org-level newsletter templates (reusable HTML scaffolds).
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_`: the envelope `{ data: Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.listTemplates();
+```
+
+---
+
+<a id="op-newsletterdomainstatus"></a>
+
+### `g8.api.newsletter.newsletterDomainStatus(input)`
+
+**Newsletter Domain Status**
+
+- HTTP: `GET /api/v1/newsletters/{newsletter_id}/settings/domain-status`
+- operationId: `newsletter_domain_status_newsletters__newsletter_id__settings_domain_status_get` (also callable as `g8.api.call("newsletter_domain_status_newsletters__newsletter_id__settings_domain_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+Whether the sending domain and its DKIM keys have verified yet.
+
+Poll this after adding the DNS records. It is not a passive read: when the
+provider reports the domain verified, this call is what promotes it into
+the sender picker.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `query.domain` | `string` | yes | The domain to check. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.newsletterDomainStatus({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  query: { domain: "acme.com" },
+});
+```
+
+---
+
+<a id="op-pausenewsletter"></a>
+
+### `g8.api.newsletter.pauseNewsletter(input)`
+
+**Pause Newsletter**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/pause`
+- operationId: `pause_newsletter_newsletters__newsletter_id__pause_post` (also callable as `g8.api.call("pause_newsletter_newsletters__newsletter_id__pause_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Pause a running newsletter. Stops further sends; the newsletter and its
+issues are untouched and it can be resumed in the app.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStatusResponse_`: the envelope `{ data: NewsletterStatusResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NewsletterStatusResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| null` | no |  |
+| `status` | `string \| null` | no | Status after the transition, e.g. `paused`, `completed`. |
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.pauseNewsletter({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-pausesend"></a>
+
+### `g8.api.newsletter.pauseSend(input)`
+
+**Pause Send**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/pause`
+- operationId: `pause_send_newsletters__newsletter_id__issues__issue_id__send_pause_post` (also callable as `g8.api.call("pause_send_newsletters__newsletter_id__issues__issue_id__send_pause_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Ask a running send to stop. The stop button.
+
+A REQUEST, not an instant state: recipients already leased by a worker are
+still delivered, and the reported state stays `pausing` until the
+reconciler confirms it settled. It does not lie about that, so poll
+`GET .../send` rather than assuming.
+
+Deliberately NOT gated on the launch permission. Requiring a launch right
+to STOP a send would invert the safety model, and the app leaves it open
+for that reason.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `SendControlRequest` | no | Request body; fields below. |
+
+Body fields (`SendControlRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.reason` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.pauseSend({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-previewnewslettersubscriberverification"></a>
+
+### `g8.api.newsletter.previewNewsletterSubscriberVerification(input)`
+
+**Preview Newsletter Subscriber Verification**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify/preview`
+- operationId: `preview_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_preview_post` (also callable as `g8.api.call("preview_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+How many addresses would be verified and what it would cost. Free; submits nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.previewNewsletterSubscriberVerification({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-restorenewsletterissueversion"></a>
+
+### `g8.api.newsletter.restoreNewsletterIssueVersion(input)`
+
+**Restore Newsletter Issue Version**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/versions/{version_num}/restore`
+- operationId: `restore_newsletter_issue_version_newsletters__newsletter_id__issues__issue_id__versions__version_num__restore_post` (also callable as `g8.api.call("restore_newsletter_issue_version_newsletters__newsletter_id__issues__issue_id__versions__version_num__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Restore an issue to one of its saved versions.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `path.version_num` | `integer` | yes | The version to restore. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.restoreNewsletterIssueVersion({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+    version_num: 1,
+  },
+});
+```
+
+---
+
+<a id="op-resumenewsletter"></a>
+
+### `g8.api.newsletter.resumeNewsletter(input)`
+
+**Resume Newsletter**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/resume`
+- operationId: `resume_newsletter_newsletters__newsletter_id__resume_post` (also callable as `g8.api.call("resume_newsletter_newsletters__newsletter_id__resume_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: `newsletter:run`
+
+Un-pause a newsletter. LAUNCH-CLASS, and the counterpart to the
+published `POST /newsletters/{id}/pause`.
+
+Resuming alone can put mail in real inboxes: pausing reverts scheduled
+issues to draft, but nothing prevents an issue being scheduled while the
+newsletter is paused, and the scheduler's due-issue query filters on the
+NEWSLETTER's status. Gated on `campaigns:launch` for that reason.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.resumeNewsletter({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-resumesend"></a>
+
+### `g8.api.newsletter.resumeSend(input)`
+
+**Resume Send**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/resume`
+- operationId: `resume_send_newsletters__newsletter_id__issues__issue_id__send_resume_post` (also callable as `g8.api.call("resume_send_newsletters__newsletter_id__issues__issue_id__send_resume_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: `newsletter:run`
+
+Restart a paused send. LAUNCH-CLASS.
+
+This is the one send control that starts delivery again, which is why it
+carries the `campaigns:launch` gate its two neighbours do not.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.resumeSend({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-rewriteissuetext"></a>
+
+### `g8.api.newsletter.rewriteIssueText(input)`
+
+**Rewrite Issue Text**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/rewrite-text`
+- operationId: `rewrite_issue_text_newsletters__newsletter_id__issues__issue_id__rewrite_text_post` (also callable as `g8.api.call("rewrite_issue_text_newsletters__newsletter_id__issues__issue_id__rewrite_text_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Rewrite one element with an AI instruction. THIS SPENDS AI CREDIT.
+
+The deliberate counterpart to `set-text`: same target, but the model
+decides the wording. Use `set-text` when you already know what it should
+say - it is free, deterministic and cannot surprise you.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `RewriteTextRequest` | yes | Request body; fields below. |
+
+Body fields (`RewriteTextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.element_id` | `string` | yes | max length 200 |
+| `body.instruction` | `string` | yes | What to change, in plain words. max length 2000 |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.rewriteIssueText({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: { element_id: "id", instruction: "example" },
+});
+```
+
+---
+
+<a id="op-runnewsletterlistsync"></a>
+
+### `g8.api.newsletter.runNewsletterListSync(input)`
+
+**Run Newsletter List Sync**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/list-syncs/{audience_list_id}/run`
+- operationId: `run_newsletter_list_sync_newsletters__newsletter_id__list_syncs__audience_list_id__run_post` (also callable as `g8.api.call("run_newsletter_list_sync_newsletters__newsletter_id__list_syncs__audience_list_id__run_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Re-run a sync now rather than waiting for the worker.
+
+Idempotent in effect: it reconciles the list into the subscriber base, so
+running it twice adds nobody twice.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+| `path.audience_list_id` | `integer` | yes | Audience list id. |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.runNewsletterListSync({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    audience_list_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-sendissue"></a>
+
+### `g8.api.newsletter.sendIssue(input)`
+
+**Send Issue**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send`
+- operationId: `send_issue_newsletters__newsletter_id__issues__issue_id__send_post` (also callable as `g8.api.call("send_issue_newsletters__newsletter_id__issues__issue_id__send_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.sendIssue()`](../sdk-clients.md#g8-newsletter-sendissue)
+
+Enqueue or schedule a newsletter issue for sending.
+
+202 Accepted: the request is validated and handed to the send worker
+(or persisted as scheduled) — actual SES delivery happens
+asynchronously. Poll ``g8_newsletter_get_issue`` to observe completion.
+``scheduled_at`` omitted/null sends immediately; a malformed
+``scheduled_at`` string returns 422 (not 500).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Issue id |
+| `body` | `IssueSendRequest` | yes | Request body; fields below. |
+
+Body fields (`IssueSendRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.scheduled_at` | `string \| 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
+// 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.newsletter.sendIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: {},
+});
+```
+
+---
+
+<a id="op-sendtestemail"></a>
+
+### `g8.api.newsletter.sendTestEmail(input)`
+
+**Send Test Email**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send-test`
+- operationId: `send_test_email_newsletters__newsletter_id__issues__issue_id__send_test_post` (also callable as `g8.api.call("send_test_email_newsletters__newsletter_id__issues__issue_id__send_test_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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.sendTestEmail()`](../sdk-clients.md#g8-newsletter-sendtestemail)
+
+Send a test email for a newsletter issue to a single address.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Issue id |
+| `body` | `IssueSendTestRequest` | yes | Request body; fields below. |
+
+Body fields (`IssueSendTestRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.test_email` | `string` | yes | max length 255 |
+
+**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
+// 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.newsletter.sendTestEmail({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: { test_email: "jane@acme.com" },
+});
+```
+
+---
+
+<a id="op-setissuebuttonaction"></a>
+
+### `g8.api.newsletter.setIssueButtonAction(input)`
+
+**Set Issue Button Action**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-button-action`
+- operationId: `set_issue_button_action_newsletters__newsletter_id__issues__issue_id__set_button_action_post` (also callable as `g8.api.call("set_issue_button_action_newsletters__newsletter_id__issues__issue_id__set_button_action_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Repoint a button in an issue. Deterministic - no AI, no credit.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `SetButtonActionRequest` | yes | Request body; fields below. |
+
+Body fields (`SetButtonActionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action_type` | `"url" \| "mailto"` | yes |  |
+| `body.g8_action_id` | `string` | yes | min length 1, max length 120 |
+| `body.email` | `string \| null` | no | For `mailto`. max length 320 |
+| `body.href` | `string \| null` | no | For `url`. max length 2048 |
+| `body.target` | `"_self" \| "_blank" \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setIssueButtonAction({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: { action_type: "url", g8_action_id: "id" },
+});
+```
+
+---
+
+<a id="op-setissuemediaedit"></a>
+
+### `g8.api.newsletter.setIssueMediaEdit(input)`
+
+**Set Issue Media Edit**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-media-edit`
+- operationId: `set_issue_media_edit_newsletters__newsletter_id__issues__issue_id__set_media_edit_post` (also callable as `g8.api.call("set_issue_media_edit_newsletters__newsletter_id__issues__issue_id__set_media_edit_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Change or remove an image in an issue. Deterministic - no AI.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `SetMediaEditRequest` | yes | Request body; fields below. |
+
+Body fields (`SetMediaEditRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.g8_action_id` | `string` | yes | min length 1, max length 120 |
+| `body.align` | `"left" \| "center" \| "right" \| null` | no |  |
+| `body.alt` | `string \| null` | no | max length 500 |
+| `body.height` | `integer \| null` | no | min 1, max 3000 |
+| `body.remove` | `boolean` | no | Delete the image. Other fields are then ignored. default `false` |
+| `body.src` | `string \| null` | no | max length 2048 |
+| `body.width` | `integer \| null` | no | min 1, max 3000 |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setIssueMediaEdit({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: { g8_action_id: "id" },
+});
+```
+
+---
+
+<a id="op-setissuetext"></a>
+
+### `g8.api.newsletter.setIssueText(input)`
+
+**Set Issue Text**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/set-text`
+- operationId: `set_issue_text_newsletters__newsletter_id__issues__issue_id__set_text_post` (also callable as `g8.api.call("set_issue_text_newsletters__newsletter_id__issues__issue_id__set_text_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Replace one element's text, exactly as given. No AI and no credit.
+
+`element_id` is the `g8` id in the issue's rendered HTML, which is what
+makes this addressable at all - it edits a named element rather than
+re-writing the document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `path.issue_id` | `integer` | yes | Issue id. |
+| `body` | `SetTextRequest` | yes | Request body; fields below. |
+
+Body fields (`SetTextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.element_id` | `string` | yes | `g8` element id from the rendered HTML. max length 200 |
+| `body.new_text` | `string` | yes | max length 5000 |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setIssueText({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: { element_id: "id", new_text: "example" },
+});
+```
+
+---
+
+<a id="op-settemplateapproval"></a>
+
+### `g8.api.newsletter.setTemplateApproval(input)`
+
+**Set Template Approval**
+
+- HTTP: `POST /api/v1/newsletters/templates/{template_id}/approval`
+- operationId: `set_template_approval_newsletters_templates__template_id__approval_post` (also callable as `g8.api.call("set_template_approval_newsletters_templates__template_id__approval_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Move a template through its lifecycle.
+
+`approved` is what makes it usable in the gallery; `archived` takes it out
+of circulation without destroying it. One explicit status rather than
+separate approve and reject calls, so a retry is idempotent instead of
+toggling.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+| `body` | `SetTemplateApprovalRequest` | yes | Request body; fields below. |
+
+Body fields (`SetTemplateApprovalRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `"draft" \| "approved" \| "archived"` | yes |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setTemplateApproval({ path: { template_id: 123 }, body: { status: "draft" } });
+```
+
+---
+
+<a id="op-settemplatebuttonaction"></a>
+
+### `g8.api.newsletter.setTemplateButtonAction(input)`
+
+**Set Template Button Action**
+
+- HTTP: `POST /api/v1/newsletters/templates/{template_id}/set-button-action`
+- operationId: `set_template_button_action_newsletters_templates__template_id__set_button_action_post` (also callable as `g8.api.call("set_template_button_action_newsletters_templates__template_id__set_button_action_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Repoint a button in a template. Deterministic - no AI, no credit.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+| `body` | `SetButtonActionRequest` | yes | Request body; fields below. |
+
+Body fields (`SetButtonActionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action_type` | `"url" \| "mailto"` | yes |  |
+| `body.g8_action_id` | `string` | yes | min length 1, max length 120 |
+| `body.email` | `string \| null` | no | For `mailto`. max length 320 |
+| `body.href` | `string \| null` | no | For `url`. max length 2048 |
+| `body.target` | `"_self" \| "_blank" \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setTemplateButtonAction({
+  path: { template_id: 123 },
+  body: { action_type: "url", g8_action_id: "id" },
+});
+```
+
+---
+
+<a id="op-settemplatemediaedit"></a>
+
+### `g8.api.newsletter.setTemplateMediaEdit(input)`
+
+**Set Template Media Edit**
+
+- HTTP: `POST /api/v1/newsletters/templates/{template_id}/set-media-edit`
+- operationId: `set_template_media_edit_newsletters_templates__template_id__set_media_edit_post` (also callable as `g8.api.call("set_template_media_edit_newsletters_templates__template_id__set_media_edit_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Change or remove an image in a template. Deterministic - no AI.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+| `body` | `SetMediaEditRequest` | yes | Request body; fields below. |
+
+Body fields (`SetMediaEditRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.g8_action_id` | `string` | yes | min length 1, max length 120 |
+| `body.align` | `"left" \| "center" \| "right" \| null` | no |  |
+| `body.alt` | `string \| null` | no | max length 500 |
+| `body.height` | `integer \| null` | no | min 1, max 3000 |
+| `body.remove` | `boolean` | no | Delete the image. Other fields are then ignored. default `false` |
+| `body.src` | `string \| null` | no | max length 2048 |
+| `body.width` | `integer \| null` | no | min 1, max 3000 |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.setTemplateMediaEdit({ path: { template_id: 123 }, body: { g8_action_id: "id" } });
+```
+
+---
+
+<a id="op-templategenerationstatus"></a>
+
+### `g8.api.newsletter.templateGenerationStatus(input)`
+
+**Template Generation Status**
+
+- HTTP: `GET /api/v1/newsletters/templates/{template_id}/generation-status`
+- operationId: `template_generation_status_newsletters_templates__template_id__generation_status_get` (also callable as `g8.api.call("template_generation_status_newsletters_templates__template_id__generation_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `newsletter:read`
+
+How far along one template build is.
+
+Durable, not in-memory: a poll that arrives after a worker restart still
+gets the truth rather than a reset.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.templateGenerationStatus({ path: { template_id: 123 } });
+```
+
+---
+
+<a id="op-unlinknewslettercampaign"></a>
+
+### `g8.api.newsletter.unlinkNewsletterCampaign(input)`
+
+**Unlink Newsletter Campaign**
+
+- HTTP: `DELETE /api/v1/newsletters/{newsletter_id}/campaign`
+- operationId: `unlink_newsletter_campaign_newsletters__newsletter_id__campaign_delete` (also callable as `g8.api.call("unlink_newsletter_campaign_newsletters__newsletter_id__campaign_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `newsletter:delete`
+
+Unlink the Studio campaign. The campaign itself is untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `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.newsletter.unlinkNewsletterCampaign({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-unsubscribesubscriber"></a>
+
+### `g8.api.newsletter.unsubscribeSubscriber(input)`
+
+**Unsubscribe Subscriber**
+
+- HTTP: `PATCH /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}/unsubscribe`
+- operationId: `unsubscribe_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__unsubscribe_patch` (also callable as `g8.api.call("unsubscribe_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__unsubscribe_patch", 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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.unsubscribe()`](../sdk-clients.md#g8-newsletter-unsubscribe)
+
+Soft-unsubscribe a subscriber (sets status, preserves the row —
+does NOT hard-delete).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.subscriber_id` | `integer` | yes | Subscriber id |
+
+**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
+// 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.newsletter.unsubscribeSubscriber({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    subscriber_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-updateissue"></a>
+
+### `g8.api.newsletter.updateIssue(input)`
+
+**Update Issue**
+
+- HTTP: `PUT /api/v1/newsletters/{newsletter_id}/issues/{issue_id}`
+- operationId: `update_issue_newsletters__newsletter_id__issues__issue_id__put` (also callable as `g8.api.call("update_issue_newsletters__newsletter_id__issues__issue_id__put", 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: `newsletter:run`
+- ★ Hand-written: [`g8.newsletter.updateIssue()`](../sdk-clients.md#g8-newsletter-updateissue)
+
+Update a draft issue in place. Only fields sent are changed. Rejects
+with 400 for issues no longer in a draft-editable state (mirrors the
+internal handler's own ValueError -> 400 mapping).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter UUID |
+| `path.issue_id` | `integer` | yes | Issue id |
+| `body` | `IssueUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`IssueUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.html_body` | `string \| null` | no |  |
+| `body.plain_text` | `string \| null` | no |  |
+| `body.preview_text` | `string \| null` | no | max length 500 |
+| `body.reply_to` | `string (email) \| null` | no |  |
+| `body.sender_email` | `string (email) \| null` | no |  |
+| `body.sender_name` | `string \| null` | no | max length 255 |
+| `body.subject` | `string \| null` | no | max length 2000 |
+
+**Returns** `ApiResponse_IssueDetail_`: the envelope `{ data: IssueDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`IssueDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `newsletter_id` | `string \| null` | no |  |
+| `sent_at` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**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.newsletter.updateIssue({
+  path: {
+    newsletter_id: "00000000-0000-0000-0000-000000000000",
+    issue_id: 123,
+  },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatenewsletter"></a>
+
+### `g8.api.newsletter.updateNewsletter(input)`
+
+**Update Newsletter**
+
+- HTTP: `PATCH /api/v1/newsletters/{newsletter_id}`
+- operationId: `update_newsletter_newsletters__newsletter_id__patch` (also callable as `g8.api.call("update_newsletter_newsletters__newsletter_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Rename a newsletter, restate its goal, or repoint its audience.
+
+Repointing the audience changes where NEW subscribers come from. It does
+not move, remove or re-import anybody already subscribed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `body` | `UpdateNewsletterRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateNewsletterRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_list_id` | `string \| null` | no | The audience new subscribers are drawn from. Changing it does NOT move anybody who is already subscribed. |
+| `body.goal` | `string \| null` | no | What the newsletter is for. Steers AI drafting. |
+| `body.name` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.updateNewsletter({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatenewslettersettings"></a>
+
+### `g8.api.newsletter.updateNewsletterSettings(input)`
+
+**Update Newsletter Settings**
+
+- HTTP: `PUT /api/v1/newsletters/{newsletter_id}/settings`
+- operationId: `update_newsletter_settings_newsletters__newsletter_id__settings_put` (also callable as `g8.api.call("update_newsletter_settings_newsletters__newsletter_id__settings_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Set the sender identity and the opt-in policy.
+
+Set `double_opt_in_intent` rather than `double_opt_in`: the active flag the
+send pipeline reads is promoted automatically once the domain is verified
+and a sender address exists, and writing the active flag directly asks for
+a state the pipeline is not ready for.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `body` | `UpdateNewsletterSettingsRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateNewsletterSettingsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.auto_verify_on_import` | `boolean \| null` | no |  |
+| `body.default_reply_to` | `string \| null` | no |  |
+| `body.default_sender_email` | `string \| null` | no |  |
+| `body.default_sender_name` | `string \| null` | no |  |
+| `body.double_opt_in` | `boolean \| null` | no | The ACTIVE double-opt-in flag the send pipeline reads. Legacy: a `true` written here is routed to `double_opt_in_intent` and the active flag is auto-promoted once the domain and sender are ready. |
+| `body.double_opt_in_intent` | `boolean \| null` | no | The REQUEST for double opt-in, independent of readiness. Set this rather than `double_opt_in` - it is promoted automatically. |
+| `body.sending_domain` | `string \| null` | no | Must be verified first - see `settings/verify-domain`. |
+| `body.skip_unverified_subscribers` | `boolean \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.updateNewsletterSettings({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatenewslettertemplate"></a>
+
+### `g8.api.newsletter.updateNewsletterTemplate(input)`
+
+**Update Newsletter Template**
+
+- HTTP: `PATCH /api/v1/newsletters/templates/{template_id}`
+- operationId: `update_newsletter_template_newsletters_templates__template_id__patch` (also callable as `g8.api.call("update_newsletter_template_newsletters_templates__template_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Edit a template's name, subject, preview text or HTML.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+| `body` | `NewsletterTemplateUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`NewsletterTemplateUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.html_body` | `string \| null` | no |  |
+| `body.name` | `string \| null` | no |  |
+| `body.preview_text` | `string \| null` | no |  |
+| `body.subject` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.updateNewsletterTemplate({ path: { template_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-usetemplate"></a>
+
+### `g8.api.newsletter.useTemplate(input)`
+
+**Use Template**
+
+- HTTP: `POST /api/v1/newsletters/templates/{template_id}/use`
+- operationId: `use_template_newsletters_templates__template_id__use_post` (also callable as `g8.api.call("use_template_newsletters_templates__template_id__use_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `newsletter:write`
+
+Turn a template into a new DRAFT issue on a newsletter.
+
+A copy, not a link: editing the issue afterwards leaves the template alone,
+and editing the template does not reach back into issues already made from
+it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `integer` | yes | Template id. |
+| `body` | `UseTemplateRequest` | yes | Request body; fields below. |
+
+Body fields (`UseTemplateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.newsletter_id` | `string (uuid)` | yes | Which newsletter the draft issue is created on. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.newsletter.useTemplate({
+  path: { template_id: 123 },
+  body: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+});
+```
+
+---
+
+<a id="op-verifynewsletterdomain"></a>
+
+### `g8.api.newsletter.verifyNewsletterDomain(input)`
+
+**Verify Newsletter Domain**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/settings/verify-domain`
+- operationId: `verify_newsletter_domain_newsletters__newsletter_id__settings_verify_domain_post` (also callable as `g8.api.call("verify_newsletter_domain_newsletters__newsletter_id__settings_verify_domain_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: `newsletter:run`
+
+Start verification of a sending domain and get the DNS records back.
+
+The records include DMARC, which Gmail and Yahoo require of bulk senders -
+publishing SPF and DKIM alone will pass this check and still land in spam.
+Domains bought through graph8 have their DNS added automatically; for a
+domain you own, the records have to be added at your own provider.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id (UUID). |
+| `body` | `VerifyDomainRequest` | yes | Request body; fields below. |
+
+Body fields (`VerifyDomainRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Sending subdomain, e.g. `updates.acme.com`. |
+
+**Returns** `ApiResponse_NewsletterPayload_`: the envelope `{ data: NewsletterPayload, ... }`. `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.newsletter.verifyNewsletterDomain({
+  path: { newsletter_id: "00000000-0000-0000-0000-000000000000" },
+  body: { domain: "acme.com" },
+});
+```
+
+---
+
+<a id="op-verifynewslettersubscribers"></a>
+
+### `g8.api.newsletter.verifyNewsletterSubscribers(input)`
+
+**Verify Newsletter Subscribers**
+
+- HTTP: `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify`
+- operationId: `verify_newsletter_subscribers_newsletters__newsletter_id__subscribers_verify_post` (also callable as `g8.api.call("verify_newsletter_subscribers_newsletters__newsletter_id__subscribers_verify_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `newsletter:run`
+
+Verify every unverified subscriber address (charges credits per address).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.newsletter_id` | `string (uuid)` | yes | Newsletter id. |
+
+**Returns** `ApiResponse_NewsletterStudioPayload_`: the envelope `{ data: NewsletterStudioPayload, ... }`. `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.newsletter.verifyNewsletterSubscribers({ path: { newsletter_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-listsync"></a>
+
+### `ListSync`
+
+One audience list feeding a newsletter's subscribers.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience_list_id` | `integer \| null` | no |  |
+| `contact_count` | `integer \| null` | no | Live count the worker will act on. |
+| `enabled` | `boolean \| null` | no | False on a SYNTHETIC candidate row - a list resolved by `?audience_list_id=` that has no saved sync yet. |
+| `name` | `string \| null` | no | Live list name. |