@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/signatures.md

@@ -0,0 +1,1247 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.signatures`: Signatures
+
+24 operations (7 read, 16 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.signatures.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [signatures.d.ts](signatures.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`archiveSignatureTemplate`](#op-archivesignaturetemplate) | `DELETE /api/v1/signatures/templates/{template_id}` | destructive | `signatures:delete` | Archive Signature Template |
+| [`assignSignatureIdentity`](#op-assignsignatureidentity) | `POST /api/v1/signatures/assignments` | write | `signatures:write` | Assign Signature Identity |
+| [`assignSignatureTemplate`](#op-assignsignaturetemplate) | `POST /api/v1/signatures/templates/{template_id}/assign` | write | `signatures:write` | Assign Signature Template |
+| [`changeSignatureSource`](#op-changesignaturesource) | `POST /api/v1/signatures/mailboxes/{mailbox_id}/source` | write | `signatures:write` | Change Signature Source |
+| [`createSignatureCampaign`](#op-createsignaturecampaign) | `POST /api/v1/signatures/campaigns` | write | `signatures:write` | Create Signature Campaign |
+| [`createSignatureTemplate`](#op-createsignaturetemplate) | `POST /api/v1/signatures/templates` | write | `signatures:write` | Create Signature Template |
+| [`getSignatureReport`](#op-getsignaturereport) | `GET /api/v1/signatures/reports` | read | `signatures:read` | Get Signature Report |
+| [`getSignatureSettings`](#op-getsignaturesettings) | `GET /api/v1/signatures/settings` | read | `signatures:read` | Get Signature Settings |
+| [`getSignatureTemplate`](#op-getsignaturetemplate) | `GET /api/v1/signatures/templates/{template_id}` | read | `signatures:read` | Get Signature Template |
+| [`listSignatureCampaigns`](#op-listsignaturecampaigns) | `GET /api/v1/signatures/campaigns` | read | `signatures:read` | List Signature Campaigns |
+| [`listSignatureDeployments`](#op-listsignaturedeployments) | `GET /api/v1/signatures/mailboxes` | read | `signatures:read` | List Signature Deployments |
+| [`listSignatureMembers`](#op-listsignaturemembers) | `GET /api/v1/signatures/members` | read | `signatures:read` | List Signature Members |
+| [`listSignatureTemplates`](#op-listsignaturetemplates) | `GET /api/v1/signatures/templates` | read | `signatures:read` | List Signature Templates |
+| [`previewSavedSignatureTemplate`](#op-previewsavedsignaturetemplate) | `POST /api/v1/signatures/templates/{template_id}/preview` | write | `signatures:write` | Preview Saved Signature Template |
+| [`previewSignatureCampaign`](#op-previewsignaturecampaign) | `POST /api/v1/signatures/campaigns/preview` | write | `signatures:write` | Preview Signature Campaign |
+| [`previewSignatureSetup`](#op-previewsignaturesetup) | `POST /api/v1/signatures/setup-preview` | write | `signatures:write` | Preview Signature Setup |
+| [`previewSignatureTemplate`](#op-previewsignaturetemplate) | `POST /api/v1/signatures/preview` | write | `signatures:write` | Preview Signature Template |
+| [`pushSignature`](#op-pushsignature) | `POST /api/v1/signatures/mailboxes/{mailbox_id}/push` | write | `signatures:write` | Push Signature |
+| [`pushSignatures`](#op-pushsignatures) | `POST /api/v1/signatures/mailboxes/push` | write | `signatures:write` | Push Signatures |
+| [`restoreSignature`](#op-restoresignature) | `POST /api/v1/signatures/mailboxes/{mailbox_id}/restore` | write | `signatures:write` | Restore Signature |
+| [`setDefaultSignatureTemplate`](#op-setdefaultsignaturetemplate) | `POST /api/v1/signatures/templates/{template_id}/set-default` | write | `signatures:write` | Set Default Signature Template |
+| [`updateSignatureCampaign`](#op-updatesignaturecampaign) | `PATCH /api/v1/signatures/campaigns/{campaign_id}` | write | `signatures:write` | Update Signature Campaign |
+| [`updateSignatureSettings`](#op-updatesignaturesettings) | `PUT /api/v1/signatures/settings` | write | `signatures:write` | Update Signature Settings |
+| [`updateSignatureTemplate`](#op-updatesignaturetemplate) | `PATCH /api/v1/signatures/templates/{template_id}` | write | `signatures:write` | Update Signature Template |
+
+---
+
+<a id="op-archivesignaturetemplate"></a>
+
+### `g8.api.signatures.archiveSignatureTemplate(input)`
+
+**Archive Signature Template**
+
+- HTTP: `DELETE /api/v1/signatures/templates/{template_id}`
+- operationId: `archive_signature_template_signatures_templates__template_id__delete` (also callable as `g8.api.call("archive_signature_template_signatures_templates__template_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `signatures:delete`
+
+Archive a template.
+
+Refused with 409 while the template is still the org default, a department
+default, or assigned to any mailbox — reassign those first. Archiving hides
+the template from the library; already-installed signatures are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+| `query.version` | `integer` | yes | Template version you last read. A mismatch is a 409. |
+
+**Returns** `ApiResponse_SignatureArchiveResponse_`: the envelope `{ data: SignatureArchiveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureArchiveResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `archived` | `boolean` | yes |  |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.signatures.archiveSignatureTemplate({
+  path: { template_id: "00000000-0000-0000-0000-000000000000" },
+  query: { version: 1 },
+});
+```
+
+---
+
+<a id="op-assignsignatureidentity"></a>
+
+### `g8.api.signatures.assignSignatureIdentity(input)`
+
+**Assign Signature Identity**
+
+- HTTP: `POST /api/v1/signatures/assignments`
+- operationId: `assign_signature_identity_signatures_assignments_post` (also callable as `g8.api.call("assign_signature_identity_signatures_assignments_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Bind an employee identity to mailboxes and queue the first install.
+
+This is a TAKEOVER: the mailbox's existing signature is captured for restore
+and replaced, which is why ``confirm_takeover`` must be ``true``. Every
+mailbox id must appear in ``expected_revisions`` (use ``0`` for a mailbox with
+no assignment yet) so a stale client cannot clobber a concurrent change.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureAssignmentWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureAssignmentWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.confirm_takeover` | `true` | yes | Must be true. Acknowledges that the mailbox's current signature is replaced. |
+| `body.data` | `SignatureAssignment` | yes |  |
+| `body.expected_revisions` | `Record<string, integer>` | yes | mailbox_id -> revision you last read. Use 0 for a mailbox with no assignment yet. |
+| `body.mailbox_ids` | `Array<integer>` | yes | min items 1, max items 1000 |
+
+**Returns** `ApiResponse_list_SignatureAssignmentResult__`: the envelope `{ data: Array<SignatureAssignmentResult>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureAssignmentResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `mailbox_id` | `integer` | yes |  |
+| `revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.assignSignatureIdentity({
+  body: {
+    confirm_takeover: true,
+    data: {
+      account_subject: "Example",
+      member_id: "00000000-0000-0000-0000-000000000000",
+      send_as_email: "jane@acme.com",
+    },
+    expected_revisions: {},
+    mailbox_ids: [123],
+  },
+});
+```
+
+---
+
+<a id="op-assignsignaturetemplate"></a>
+
+### `g8.api.signatures.assignSignatureTemplate(input)`
+
+**Assign Signature Template**
+
+- HTTP: `POST /api/v1/signatures/templates/{template_id}/assign`
+- operationId: `assign_signature_template_signatures_templates__template_id__assign_post` (also callable as `g8.api.call("assign_signature_template_signatures_templates__template_id__assign_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Point a set of mailboxes at this template and queue a re-install.
+
+Targets are mutually exclusive: explicit ``mailbox_ids``, every mailbox whose
+employee is in ``department``, or ``all_mailboxes``. Every targeted mailbox
+must already have an employee assignment (422 otherwise).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+| `body` | `SignatureTemplateTargets` | yes | Request body; fields below. |
+
+Body fields (`SignatureTemplateTargets`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.all_mailboxes` | `boolean` | no | Every active, assigned mailbox. default `false` |
+| `body.department` | `string \| null` | no | Every assigned mailbox whose employee is in this department. |
+| `body.mailbox_ids` | `Array<integer>` | no | max items 1000 |
+
+**Returns** `ApiResponse_SignatureBulkTemplateResponse_`: the envelope `{ data: SignatureBulkTemplateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureBulkTemplateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `count` | `integer` | yes |  |
+| `results` | `Array<Record<string, unknown>>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.assignSignatureTemplate({
+  path: { template_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-changesignaturesource"></a>
+
+### `g8.api.signatures.changeSignatureSource(input)`
+
+**Change Signature Source**
+
+- HTTP: `POST /api/v1/signatures/mailboxes/{mailbox_id}/source`
+- operationId: `change_signature_source_signatures_mailboxes__mailbox_id__source_post` (also callable as `g8.api.call("change_signature_source_signatures_mailboxes__mailbox_id__source_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Choose what this mailbox sends: the org/department default, a named
+template, or its own content.
+
+``custom`` performs the same restore as ``POST .../restore``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) — from GET /signatures/mailboxes |
+| `body` | `SignatureSourceWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureSourceWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source` | `"org" \| "template" \| "custom"` | yes |  |
+| `body.version` | `integer` | yes | Revision you last read. A mismatch is a 409. |
+| `body.template_id` | `string (uuid) \| null` | no | Required when source is 'template'. |
+
+**Returns** `ApiResponse_SignatureDeploymentStatus_`: the envelope `{ data: SignatureDeploymentStatus, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureDeploymentStatus` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | yes |  |
+| `message` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.changeSignatureSource({ path: { mailbox_id: 123 }, body: { source: "org", version: 1 } });
+```
+
+---
+
+<a id="op-createsignaturecampaign"></a>
+
+### `g8.api.signatures.createSignatureCampaign(input)`
+
+**Create Signature Campaign**
+
+- HTTP: `POST /api/v1/signatures/campaigns`
+- operationId: `create_signature_campaign_signatures_campaigns_post` (also callable as `g8.api.call("create_signature_campaign_signatures_campaigns_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Create a banner campaign.
+
+The creative must be an OPTIONAL banner block, and ``starts_at`` /
+``ends_at`` must be timezone-aware with the end after the start. Campaigns
+start in ``draft`` unless you set ``status``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureCampaignWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureCampaignWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureCampaign` | yes |  |
+| `body.version` | `integer` | no | Revision you last read. Ignored on create. default `0` |
+
+**Returns** `ApiResponse_SignatureCampaignResponse_`: the envelope `{ data: SignatureCampaignResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureCampaignResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored campaign document. |
+| `id` | `string` | yes |  |
+| `revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.createSignatureCampaign({
+  body: {
+    data: {
+      block: { id: "id", kind: "identity" },
+      ends_at: "2026-01-01T09:00:00Z",
+      name: "Example",
+      starts_at: "2026-01-01T09:00:00Z",
+    },
+  },
+});
+```
+
+---
+
+<a id="op-createsignaturetemplate"></a>
+
+### `g8.api.signatures.createSignatureTemplate(input)`
+
+**Create Signature Template**
+
+- HTTP: `POST /api/v1/signatures/templates`
+- operationId: `create_signature_template_signatures_templates_post` (also callable as `g8.api.call("create_signature_template_signatures_templates_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Create a signature template.
+
+The block list is validated the way the in-app editor validates it: exactly
+one required, locked identity block, at most one optional banner slot, unique
+block ids. A rejected template answers 422 with the reason.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureTemplateWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureTemplateWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureTemplate` | yes |  |
+| `body.version` | `integer` | no | Version you last read. Ignored on create. default `0` |
+
+**Returns** `ApiResponse_SignatureTemplateResponse_`: the envelope `{ data: SignatureTemplateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureTemplateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored template document. |
+| `id` | `string` | yes |  |
+| `version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.createSignatureTemplate({
+  body: {
+    data: { blocks: [{ id: "id", kind: "identity" }], name: "Example" },
+  },
+});
+```
+
+---
+
+<a id="op-getsignaturereport"></a>
+
+### `g8.api.signatures.getSignatureReport(input?)`
+
+**Get Signature Report**
+
+- HTTP: `GET /api/v1/signatures/reports`
+- operationId: `get_signature_report_signatures_reports_get` (also callable as `g8.api.call("get_signature_report_signatures_reports_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+Signature and campaign engagement: impressions and clicks by mailbox and campaign.
+
+**Input**: none.
+
+**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
+const result = await g8.api.signatures.getSignatureReport();
+```
+
+---
+
+<a id="op-getsignaturesettings"></a>
+
+### `g8.api.signatures.getSignatureSettings(input?)`
+
+**Get Signature Settings**
+
+- HTTP: `GET /api/v1/signatures/settings`
+- operationId: `get_signature_settings_signatures_settings_get` (also callable as `g8.api.call("get_signature_settings_signatures_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+Read the org-wide signature policy and its current version.
+
+``mode`` is ``off`` (nothing managed), ``default`` (managed, employees may
+override) or ``enforced`` (managed, overrides refused).
+
+**Input**: none.
+
+**Returns** `ApiResponse_SignatureSettingsResponse_`: the envelope `{ data: SignatureSettingsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureSettingsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored policy document. |
+| `version` | `integer` | yes | Version after the write; pass it to the next update. |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.getSignatureSettings();
+```
+
+---
+
+<a id="op-getsignaturetemplate"></a>
+
+### `g8.api.signatures.getSignatureTemplate(input)`
+
+**Get Signature Template**
+
+- HTTP: `GET /api/v1/signatures/templates/{template_id}`
+- operationId: `get_signature_template_signatures_templates__template_id__get` (also callable as `g8.api.call("get_signature_template_signatures_templates__template_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+Read one template, including the ``version`` needed to update it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+
+**Returns** `ApiResponse_SignatureTemplateResponse_`: the envelope `{ data: SignatureTemplateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureTemplateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored template document. |
+| `id` | `string` | yes |  |
+| `version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.getSignatureTemplate({ path: { template_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listsignaturecampaigns"></a>
+
+### `g8.api.signatures.listSignatureCampaigns(input?)`
+
+**List Signature Campaigns**
+
+- HTTP: `GET /api/v1/signatures/campaigns`
+- operationId: `list_signature_campaigns_signatures_campaigns_get` (also callable as `g8.api.call("list_signature_campaigns_signatures_campaigns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+List signature banner campaigns and the ``revision`` needed to edit one.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_SignatureCampaignResponse__`: the envelope `{ data: Array<SignatureCampaignResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureCampaignResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored campaign document. |
+| `id` | `string` | yes |  |
+| `revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.listSignatureCampaigns();
+```
+
+---
+
+<a id="op-listsignaturedeployments"></a>
+
+### `g8.api.signatures.listSignatureDeployments(input?)`
+
+**List Signature Deployments**
+
+- HTTP: `GET /api/v1/signatures/mailboxes`
+- operationId: `list_signature_deployments_signatures_mailboxes_get` (also callable as `g8.api.call("list_signature_deployments_signatures_mailboxes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+List every mailbox's signature deployment: assignment, revision, status, drift.
+
+``revision`` here is the optimistic-concurrency token for every per-mailbox
+write below. ``alert`` is true when the deployment needs an admin — blocked,
+unassigned, missing a provider grant, drifted, or in restore conflict.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.listSignatureDeployments();
+```
+
+---
+
+<a id="op-listsignaturemembers"></a>
+
+### `g8.api.signatures.listSignatureMembers(input?)`
+
+**List Signature Members**
+
+- HTTP: `GET /api/v1/signatures/members`
+- operationId: `list_signature_members_signatures_members_get` (also callable as `g8.api.call("list_signature_members_signatures_members_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+List the directory employees a mailbox signature can be assigned to.
+
+``id`` is the ``member_id`` required by ``POST /signatures/assignments``.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_SignatureMember__`: the envelope `{ data: Array<SignatureMember>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureMember` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `department` | `string \| null` | no |  |
+| `email` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.listSignatureMembers();
+```
+
+---
+
+<a id="op-listsignaturetemplates"></a>
+
+### `g8.api.signatures.listSignatureTemplates(input?)`
+
+**List Signature Templates**
+
+- HTTP: `GET /api/v1/signatures/templates`
+- operationId: `list_signature_templates_signatures_templates_get` (also callable as `g8.api.call("list_signature_templates_signatures_templates_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `signatures:read`
+
+List every non-archived signature template in the org.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_SignatureTemplateResponse__`: the envelope `{ data: Array<SignatureTemplateResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureTemplateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored template document. |
+| `id` | `string` | yes |  |
+| `version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.listSignatureTemplates();
+```
+
+---
+
+<a id="op-previewsavedsignaturetemplate"></a>
+
+### `g8.api.signatures.previewSavedSignatureTemplate(input)`
+
+**Preview Saved Signature Template**
+
+- HTTP: `POST /api/v1/signatures/templates/{template_id}/preview`
+- operationId: `preview_saved_signature_template_signatures_templates__template_id__preview_post` (also callable as `g8.api.call("preview_saved_signature_template_signatures_templates__template_id__preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Render a stored template. Reads only — nothing is saved or sent.
+
+Supply ``mailbox_id`` AND ``member_id`` to render with that employee's real
+details; omit them for sample data.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+| `body` | `SignatureSavedPreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`SignatureSavedPreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_id` | `integer \| null` | no |  |
+| `body.member_id` | `string (uuid) \| 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
+const result = await g8.api.signatures.previewSavedSignatureTemplate({
+  path: { template_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-previewsignaturecampaign"></a>
+
+### `g8.api.signatures.previewSignatureCampaign(input)`
+
+**Preview Signature Campaign**
+
+- HTTP: `POST /api/v1/signatures/campaigns/preview`
+- operationId: `preview_signature_campaign_signatures_campaigns_preview_post` (also callable as `g8.api.call("preview_signature_campaign_signatures_campaigns_preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Render a campaign banner and, optionally, test who it would reach.
+
+Reads only. With ``mailbox_id`` set, ``matching`` explains whether the
+campaign would apply to that sender and the supplied ``recipients``, and
+which campaign wins on priority.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureCampaignPreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`SignatureCampaignPreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureCampaign` | yes |  |
+| `body.campaign_id` | `string (uuid) \| null` | no | Exclude this campaign from the priority comparison when previewing an edit. |
+| `body.mailbox_id` | `integer \| null` | no | Evaluate the campaign's targeting rules against this mailbox. Omit to render only. |
+| `body.recipients` | `Array<string>` | no | Candidate recipient addresses to test the targeting rules against. max items 100 |
+| `body.version` | `integer` | no | Revision you last read. Ignored on create. default `0` |
+
+**Returns** `ApiResponse_SignatureCampaignPreviewResponse_`: the envelope `{ data: SignatureCampaignPreviewResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureCampaignPreviewResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `html` | `string` | yes |  |
+| `native_static` | `boolean` | yes |  |
+| `plain` | `string` | yes |  |
+| `matching` | `Record<string, unknown> \| null` | no | Targeting evaluation. Null unless mailbox_id was supplied. |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.previewSignatureCampaign({
+  body: {
+    data: {
+      block: { id: "id", kind: "identity" },
+      ends_at: "2026-01-01T09:00:00Z",
+      name: "Example",
+      starts_at: "2026-01-01T09:00:00Z",
+    },
+  },
+});
+```
+
+---
+
+<a id="op-previewsignaturesetup"></a>
+
+### `g8.api.signatures.previewSignatureSetup(input)`
+
+**Preview Signature Setup**
+
+- HTTP: `POST /api/v1/signatures/setup-preview`
+- operationId: `preview_signature_setup_signatures_setup_preview_post` (also callable as `g8.api.call("preview_signature_setup_signatures_setup_preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Dry-run an assignment against the mail provider before committing it.
+
+Confirms the employee account and send-as alias resolve, and returns the
+signature currently installed there. Write capability stays unverified until
+a real deployment succeeds. A provider refusal answers 422 with the state and
+reason rather than a stack trace.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureSetupPreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`SignatureSetupPreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureAssignment` | yes |  |
+| `body.mailbox_id` | `integer` | yes |  |
+
+**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
+const result = await g8.api.signatures.previewSignatureSetup({
+  body: {
+    data: {
+      account_subject: "Example",
+      member_id: "00000000-0000-0000-0000-000000000000",
+      send_as_email: "jane@acme.com",
+    },
+    mailbox_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-previewsignaturetemplate"></a>
+
+### `g8.api.signatures.previewSignatureTemplate(input)`
+
+**Preview Signature Template**
+
+- HTTP: `POST /api/v1/signatures/preview`
+- operationId: `preview_signature_template_signatures_preview_post` (also callable as `g8.api.call("preview_signature_template_signatures_preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Render an unsaved template draft. Reads only — nothing is saved or sent.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignaturePreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`SignaturePreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureTemplate` | yes |  |
+| `body.mailbox_id` | `integer \| null` | no |  |
+| `body.member_id` | `string (uuid) \| null` | no | Render with this employee's real details. Requires mailbox_id; otherwise sample data is used. |
+| `body.overrides` | `Record<string, string>` | 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
+const result = await g8.api.signatures.previewSignatureTemplate({
+  body: {
+    data: { blocks: [{ id: "id", kind: "identity" }], name: "Example" },
+  },
+});
+```
+
+---
+
+<a id="op-pushsignature"></a>
+
+### `g8.api.signatures.pushSignature(input)`
+
+**Push Signature**
+
+- HTTP: `POST /api/v1/signatures/mailboxes/{mailbox_id}/push`
+- operationId: `push_signature_signatures_mailboxes__mailbox_id__push_post` (also callable as `g8.api.call("push_signature_signatures_mailboxes__mailbox_id__push_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Queue a re-compile and re-install for one mailbox.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) — from GET /signatures/mailboxes |
+| `body` | `SignatureRevision` | yes | Request body; fields below. |
+
+Body fields (`SignatureRevision`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.version` | `integer` | yes | Revision you last read. A mismatch is a 409. |
+
+**Returns** `ApiResponse_SignatureDeploymentStatus_`: the envelope `{ data: SignatureDeploymentStatus, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureDeploymentStatus` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | yes |  |
+| `message` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.pushSignature({ path: { mailbox_id: 123 }, body: { version: 1 } });
+```
+
+---
+
+<a id="op-pushsignatures"></a>
+
+### `g8.api.signatures.pushSignatures(input)`
+
+**Push Signatures**
+
+- HTTP: `POST /api/v1/signatures/mailboxes/push`
+- operationId: `push_signatures_signatures_mailboxes_push_post` (also callable as `g8.api.call("push_signatures_signatures_mailboxes_push_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Queue a re-install for several mailboxes at once.
+
+Every mailbox must have a live assignment; a restored or unassigned mailbox
+in the list fails the whole call with 422 rather than half-applying.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureBulkPushRequest` | yes | Request body; fields below. |
+
+Body fields (`SignatureBulkPushRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailbox_ids` | `Array<integer>` | yes | min items 1, max items 1000 |
+
+**Returns** `ApiResponse_SignatureDeploymentStatus_`: the envelope `{ data: SignatureDeploymentStatus, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureDeploymentStatus` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | yes |  |
+| `message` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.pushSignatures({ body: { mailbox_ids: [123] } });
+```
+
+---
+
+<a id="op-restoresignature"></a>
+
+### `g8.api.signatures.restoreSignature(input)`
+
+**Restore Signature**
+
+- HTTP: `POST /api/v1/signatures/mailboxes/{mailbox_id}/restore`
+- operationId: `restore_signature_signatures_mailboxes__mailbox_id__restore_post` (also callable as `g8.api.call("restore_signature_signatures_mailboxes__mailbox_id__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Put back the signature this mailbox had before graph8 took it over.
+
+Refused with 409 while the policy is ``enforced``. If the installed content
+was edited outside graph8 since takeover the deployment is parked as
+``restore_conflict`` and nothing is overwritten.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.mailbox_id` | `integer` | yes | Mailbox id (mailboxes.id) — from GET /signatures/mailboxes |
+| `body` | `SignatureRevision` | yes | Request body; fields below. |
+
+Body fields (`SignatureRevision`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.version` | `integer` | yes | Revision you last read. A mismatch is a 409. |
+
+**Returns** `ApiResponse_SignatureDeploymentStatus_`: the envelope `{ data: SignatureDeploymentStatus, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureDeploymentStatus` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | yes |  |
+| `message` | `string \| null` | no |  |
+| `revision` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.restoreSignature({ path: { mailbox_id: 123 }, body: { version: 1 } });
+```
+
+---
+
+<a id="op-setdefaultsignaturetemplate"></a>
+
+### `g8.api.signatures.setDefaultSignatureTemplate(input)`
+
+**Set Default Signature Template**
+
+- HTTP: `POST /api/v1/signatures/templates/{template_id}/set-default`
+- operationId: `set_default_signature_template_signatures_templates__template_id__set_default_post` (also callable as `g8.api.call("set_default_signature_template_signatures_templates__template_id__set_default_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Make this template the organisation default.
+
+``version`` is the POLICY version (from ``GET /signatures/settings``), not the
+template's — this writes the policy document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+| `body` | `SignatureRevision` | yes | Request body; fields below. |
+
+Body fields (`SignatureRevision`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.version` | `integer` | yes | Revision you last read. A mismatch is a 409. |
+
+**Returns** `ApiResponse_SignatureVersionResponse_`: the envelope `{ data: SignatureVersionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureVersionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.setDefaultSignatureTemplate({
+  path: { template_id: "00000000-0000-0000-0000-000000000000" },
+  body: { version: 1 },
+});
+```
+
+---
+
+<a id="op-updatesignaturecampaign"></a>
+
+### `g8.api.signatures.updateSignatureCampaign(input)`
+
+**Update Signature Campaign**
+
+- HTTP: `PATCH /api/v1/signatures/campaigns/{campaign_id}`
+- operationId: `update_signature_campaign_signatures_campaigns__campaign_id__patch` (also callable as `g8.api.call("update_signature_campaign_signatures_campaigns__campaign_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Replace a campaign's content or schedule. Send the ``revision`` you read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `string (uuid)` | yes | Signature campaign id |
+| `body` | `SignatureCampaignWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureCampaignWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureCampaign` | yes |  |
+| `body.version` | `integer` | no | Revision you last read. Ignored on create. default `0` |
+
+**Returns** `ApiResponse_SignatureCampaignResponse_`: the envelope `{ data: SignatureCampaignResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureCampaignResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored campaign document. |
+| `id` | `string` | yes |  |
+| `revision` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.updateSignatureCampaign({
+  path: { campaign_id: "00000000-0000-0000-0000-000000000000" },
+  body: {
+    data: {
+      block: { id: "id", kind: "identity" },
+      ends_at: "2026-01-01T09:00:00Z",
+      name: "Example",
+      starts_at: "2026-01-01T09:00:00Z",
+    },
+  },
+});
+```
+
+---
+
+<a id="op-updatesignaturesettings"></a>
+
+### `g8.api.signatures.updateSignatureSettings(input)`
+
+**Update Signature Settings**
+
+- HTTP: `PUT /api/v1/signatures/settings`
+- operationId: `update_signature_settings_signatures_settings_put` (also callable as `g8.api.call("update_signature_settings_signatures_settings_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Replace the signature policy.
+
+Enabling management requires a default template; ``enforced`` additionally
+requires every active mailbox to already have an assignment. Send the
+``version`` you read — a concurrent change answers 409.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignatureSettingsWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureSettingsWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureSettings` | yes |  |
+| `body.version` | `integer` | yes | Version you last read. A mismatch is a 409. |
+
+**Returns** `ApiResponse_SignatureSettingsResponse_`: the envelope `{ data: SignatureSettingsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureSettingsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored policy document. |
+| `version` | `integer` | yes | Version after the write; pass it to the next update. |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.updateSignatureSettings({ body: { data: {}, version: 1 } });
+```
+
+---
+
+<a id="op-updatesignaturetemplate"></a>
+
+### `g8.api.signatures.updateSignatureTemplate(input)`
+
+**Update Signature Template**
+
+- HTTP: `PATCH /api/v1/signatures/templates/{template_id}`
+- operationId: `update_signature_template_signatures_templates__template_id__patch` (also callable as `g8.api.call("update_signature_template_signatures_templates__template_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `signatures:write`
+
+Replace a template's content. Send the ``version`` you read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.template_id` | `string (uuid)` | yes | Signature template id |
+| `body` | `SignatureTemplateWrite` | yes | Request body; fields below. |
+
+Body fields (`SignatureTemplateWrite`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.data` | `SignatureTemplate` | yes |  |
+| `body.version` | `integer` | no | Version you last read. Ignored on create. default `0` |
+
+**Returns** `ApiResponse_SignatureTemplateResponse_`: the envelope `{ data: SignatureTemplateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SignatureTemplateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | `Record<string, unknown>` | yes | The stored template document. |
+| `id` | `string` | yes |  |
+| `version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signatures.updateSignatureTemplate({
+  path: { template_id: "00000000-0000-0000-0000-000000000000" },
+  body: {
+    data: { blocks: [{ id: "id", kind: "identity" }], name: "Example" },
+  },
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-signatureassignment"></a>
+
+### `SignatureAssignment`
+
+Which employee a mailbox signs as, and which template it renders.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_subject` | `string` | yes | min length 3, max length 255 |
+| `member_id` | `string (uuid)` | yes |  |
+| `send_as_email` | `string` | yes | min length 3, max length 255 |
+| `integration_id` | `string (uuid) \| null` | no |  |
+| `native_requested` | `boolean` | no | default `false` |
+| `overrides` | `Record<string, string>` | no |  |
+| `template_id` | `string (uuid) \| null` | no |  |
+
+<a id="type-signaturecampaign"></a>
+
+### `SignatureCampaign`
+
+A time-boxed banner campaign injected into managed signatures.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `block` | `Block` | yes |  |
+| `ends_at` | `string (date-time)` | yes |  |
+| `name` | `string` | yes | min length 1, max length 150 |
+| `starts_at` | `string (date-time)` | yes |  |
+| `departments` | `Array<string>` | no | max items 1000 |
+| `excluded_domains` | `Array<string>` | no | max items 1000 |
+| `external_only` | `boolean` | no | default `true` |
+| `mailbox_ids` | `Array<integer>` | no | max items 10000 |
+| `native_static` | `boolean` | no | default `false` |
+| `priority` | `integer` | no | default `0`, min -1000, max 1000 |
+| `recipient_domains` | `Array<string>` | no | max items 1000 |
+| `recipient_list_ids` | `Array<integer>` | no | max items 1000 |
+| `status` | `"draft" \| "scheduled" \| "paused"` | no | default `"draft"` |
+
+<a id="type-signaturesettings"></a>
+
+### `SignatureSettings`
+
+Org-wide signature policy document. Same contract as the in-app editor.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `allow_employee_overrides` | `boolean` | no | default `true` |
+| `cold_sends_variant` | `"full" \| "compact"` | no | default `"compact"` |
+| `default_template_id` | `string (uuid) \| null` | no |  |
+| `department_templates` | `Record<string, string (uuid)>` | no |  |
+| `mode` | `"off" \| "default" \| "enforced"` | no | default `"off"` |
+| `native_enabled` | `boolean` | no | default `false` |
+
+<a id="type-signaturetemplate"></a>
+
+### `SignatureTemplate`
+
+A signature template's blocks, layout and branding.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `blocks` | `Array<Block>` | yes | min items 1, max items 30 |
+| `name` | `string` | yes | min length 1, max length 150 |
+| `brand_source` | `"brand_kit" \| "custom"` | no | default `"brand_kit"` |
+| `font` | `"Arial" \| "Verdana" \| "Georgia" \| "Tahoma"` | no | default `"Arial"` |
+| `layout` | `"classic-stacked" \| "photo-left" \| "logo-left" \| "two-column" \| "compact-inline" \| "banner-hero"` | no | default `"classic-stacked"` |
+| `primary_color` | `string` | no | default `"#222222"`, pattern `^#[a-fA-F0-9]{6}$` |