@lessly/sdk-app 76.1.0 → 78.0.0

package/src/gen/types.gen.ts

@@ -74678,38 +74678,65 @@ attachedServiceId: (string | null)
 
 export interface MailApikeyCreateInput {
 /**
- * Human-readable label for the key
+ * Human-readable label for the key, e.g. "production sender"
  */
 name: string
 /**
- * Permission scope: 'full_access' or 'sending_access'
+ * Permission scope: full_access can call every mail tool, sending_access can only send email
  */
 scope: ("full_access" | "sending_access")
 /**
- * Optional Domain id this key is locked to
+ * Lock the key to this sending domain; omit to let it send from any verified domain
  */
 domainId?: string
 }
 
 export interface MailApikeyCreateOutput {
+/**
+ * API key id; pass it to mail_apikey_delete to revoke the key
+ */
 id: string
+/**
+ * The full secret. Returned only by this call and never retrievable again — store it now
+ */
 key: string
+/**
+ * Human-readable label given when the key was issued
+ */
 name: string
-scope: string
+/**
+ * Permission scope: full_access can call every mail tool, sending_access can only send email
+ */
+scope: ("full_access" | "sending_access")
+/**
+ * Opening characters of the secret, so a key can be recognised in a log or a header
+ */
 prefix: string
+/**
+ * Sending domain this key is locked to; null if it may send from any verified domain
+ */
 domainId: (string | null)
+/**
+ * When the key was issued (ISO 8601 UTC)
+ */
 createdAt: string
 }
 
 export interface MailApikeyDeleteInput {
 /**
- * UUID of the API key to revoke
+ * Id of the API key to revoke; revocation is immediate and permanent
  */
 id: string
 }
 
 export interface MailApikeyDeleteOutput {
+/**
+ * Id of the key that was revoked
+ */
 id: string
+/**
+ * Always true; the call throws rather than reporting a failure here
+ */
 revoked: true
 }
 
@@ -74717,12 +74744,33 @@ export interface MailApikeyListInput {
 
 }
 
+/**
+ * Active API keys for the current product, secrets omitted
+ */
 export type MailApikeyListOutput = {
+/**
+ * API key id; pass it to mail_apikey_delete to revoke the key
+ */
 id: string
+/**
+ * Human-readable label given when the key was issued
+ */
 name: string
-scope: string
+/**
+ * Permission scope: full_access can call every mail tool, sending_access can only send email
+ */
+scope: ("full_access" | "sending_access")
+/**
+ * Opening characters of the secret, so a key can be recognised in a log or a header
+ */
 prefix: string
+/**
+ * Sending domain this key is locked to; null if it may send from any verified domain
+ */
 domainId: (string | null)
+/**
+ * When the key was issued (ISO 8601 UTC)
+ */
 createdAt: string
 }[]
 
@@ -74734,9 +74782,21 @@ name: string
 }
 
 export interface MailAudienceCreateOutput {
+/**
+ * Audience id
+ */
 id: string
+/**
+ * Human label for the audience
+ */
 name: string
+/**
+ * When the audience was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the audience was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
 }
 
@@ -74748,6 +74808,9 @@ id: string
 }
 
 export interface MailAudienceDeleteOutput {
+/**
+ * True once the audience and its contacts are gone
+ */
 deleted: boolean
 }
 
@@ -74759,9 +74822,21 @@ id: string
 }
 
 export interface MailAudienceGetOutput {
+/**
+ * Audience id
+ */
 id: string
+/**
+ * Human label for the audience
+ */
 name: string
+/**
+ * When the audience was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the audience was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
 }
 
@@ -74770,9 +74845,21 @@ export interface MailAudienceListInput {
 }
 
 export type MailAudienceListOutput = {
+/**
+ * Audience id
+ */
 id: string
+/**
+ * Human label for the audience
+ */
 name: string
+/**
+ * When the audience was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the audience was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
 }[]
 
@@ -74788,235 +74875,724 @@ name?: string
 }
 
 export interface MailAudienceUpdateOutput {
+/**
+ * Audience id
+ */
 id: string
+/**
+ * Human label for the audience
+ */
 name: string
+/**
+ * When the audience was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the audience was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
 }
 
 export interface MailBroadcastCancelInput {
+/**
+ * Broadcast id
+ */
 id: string
 }
 
 export interface MailBroadcastCancelOutput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }
 
 export interface MailBroadcastCreateInput {
+/**
+ * Sender on a verified domain, e.g. "Name <you@your-domain.com>"
+ */
 from: string
+/**
+ * HTML body. Inline content only — forbidden with a template.
+ */
 html?: string
+/**
+ * Internal label for the broadcast — never shown to recipients
+ */
 name: string
+/**
+ * Plain-text body. Inline content only — forbidden with a template.
+ */
 text?: string
+/**
+ * Custom MIME headers added to every message. Defaults to {}.
+ */
 headers?: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses. Defaults to [] — replies go to `from`.
+ */
 replyTo?: string[]
+/**
+ * Subject line, capped at the RFC-5322 line limit. Required with inline content, forbidden with a template.
+ */
 subject?: string
+/**
+ * Send by reference to a published template instead of inline content
+ */
 template?: {
+/**
+ * Published template id to render for every recipient
+ */
 id: string
+/**
+ * Values for the template variables, the same for every recipient. Defaults to {}.
+ */
 variables?: {
 [k: string]: (string | number | boolean)
 }
 }
+/**
+ * Audience whose subscribed contacts receive this broadcast
+ */
 audienceId: string
 }
 
 export interface MailBroadcastCreateOutput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }
 
 export interface MailBroadcastDeleteInput {
+/**
+ * Broadcast id
+ */
 id: string
 }
 
 export interface MailBroadcastDeleteOutput {
+/**
+ * Id of the deleted broadcast
+ */
 id: string
+/**
+ * True when the broadcast was removed
+ */
 deleted: boolean
 }
 
 export interface MailBroadcastGetInput {
+/**
+ * Broadcast id
+ */
 id: string
 }
 
 export interface MailBroadcastGetOutput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }
 
 export interface MailBroadcastListInput {
+/**
+ * Page size, 1-100. Defaults to 50.
+ */
 limit?: number
+/**
+ * Opaque cursor from the previous page’s `nextCursor`. Omit for the first page.
+ */
 cursor?: string
 }
 
 export interface MailBroadcastListOutput {
+/**
+ * The broadcasts on this page, newest first
+ */
 items: {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }[]
+/**
+ * Pass as `cursor` for the next page; null on the last page
+ */
 nextCursor: (string | null)
 }
 
 export interface MailBroadcastQueueInput {
+/**
+ * Broadcast id
+ */
 id: string
 }
 
 export interface MailBroadcastQueueOutput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }
 
 export interface MailBroadcastStatsInput {
+/**
+ * Broadcast id
+ */
 id: string
 }
 
 export interface MailBroadcastStatsOutput {
+/**
+ * Messages that could not be handed to the provider
+ */
 failed: number
+/**
+ * Messages opened at least once, as seen by the tracking pixel
+ */
 opened: number
+/**
+ * Messages that bounced, hard or soft
+ */
 bounced: number
+/**
+ * Messages with at least one tracked link click
+ */
 clicked: number
+/**
+ * Messages the receiving server accepted
+ */
 delivered: number
+/**
+ * Contacts the broadcast fanned out to
+ */
 recipients: number
+/**
+ * Recipients skipped because they are on the suppression list
+ */
 suppressed: number
 }
 
 export interface MailBroadcastUpdateInput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender on a verified domain, e.g. "Name <you@your-domain.com>"
+ */
 from?: string
+/**
+ * HTML body. Inline content only — forbidden with a template.
+ */
 html?: string
+/**
+ * Internal label for the broadcast — never shown to recipients
+ */
 name?: string
+/**
+ * Plain-text body. Inline content only — forbidden with a template.
+ */
 text?: string
+/**
+ * Custom MIME headers added to every message. Defaults to {}.
+ */
 headers?: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses. Defaults to [] — replies go to `from`.
+ */
 replyTo?: string[]
+/**
+ * Subject line, capped at the RFC-5322 line limit. Required with inline content, forbidden with a template.
+ */
 subject?: string
+/**
+ * Send by reference to a published template instead of inline content
+ */
 template?: {
+/**
+ * Published template id to render for every recipient
+ */
 id: string
+/**
+ * Values for the template variables, the same for every recipient. Defaults to {}.
+ */
 variables?: {
 [k: string]: (string | number | boolean)
 }
 }
+/**
+ * Audience whose subscribed contacts receive this broadcast
+ */
 audienceId?: string
 }
 
 export interface MailBroadcastUpdateOutput {
+/**
+ * Broadcast id
+ */
 id: string
+/**
+ * Sender the messages are sent as
+ */
 from: string
+/**
+ * Inline HTML body; null when a template supplies it
+ */
 html: (string | null)
+/**
+ * Internal label — never shown to recipients
+ */
 name: string
+/**
+ * Inline plain-text body; null when a template supplies it
+ */
 text: (string | null)
+/**
+ * When the last message left; null until sending finishes
+ */
 sentAt: (string | null)
-status: string
+/**
+ * Lifecycle state: draft (editable), queued (fanned out, sending), sent, failed, canceled
+ */
+status: ("draft" | "queued" | "sent" | "failed" | "canceled")
+/**
+ * Custom MIME headers added to every message
+ */
 headers: {
 [k: string]: string
 }
+/**
+ * Reply-To addresses; empty when replies go to `from`
+ */
 replyTo: string[]
+/**
+ * Subject line for inline content; null when a template supplies it
+ */
 subject: (string | null)
+/**
+ * When the broadcast was queued; null while it is a draft
+ */
 queuedAt: (string | null)
+/**
+ * When the broadcast was created
+ */
 createdAt: string
+/**
+ * Why the broadcast failed; null unless status is failed
+ */
 lastError: (string | null)
+/**
+ * Product the broadcast belongs to
+ */
 productId: string
+/**
+ * When the broadcast was last modified
+ */
 updatedAt: string
-variables?: unknown
+/**
+ * Values passed to the template variables; {} for inline content
+ */
+variables: ({
+[k: string]: unknown
+} | null)
+/**
+ * Audience whose contacts this broadcast is sent to
+ */
 audienceId: string
+/**
+ * Template rendered for every recipient; null for inline content
+ */
 templateId: (string | null)
+/**
+ * Contacts the broadcast fanned out to; 0 while it is still a draft
+ */
 recipientCount: number
 }
 
@@ -75042,12 +75618,30 @@ unsubscribed?: boolean
 }
 
 export interface MailContactCreateOutput {
+/**
+ * Contact id
+ */
 id: string
+/**
+ * Contact email address, normalized to lowercase
+ */
 email: string
+/**
+ * When the contact was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the contact was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Audience the contact belongs to
+ */
 audienceId: string
 properties?: unknown
+/**
+ * Marketing opt-out flag for this audience
+ */
 unsubscribed: boolean
 }
 
@@ -75063,6 +75657,9 @@ audience_id: string
 }
 
 export interface MailContactDeleteOutput {
+/**
+ * True once the contact is gone
+ */
 deleted: boolean
 }
 
@@ -75078,12 +75675,30 @@ audience_id: string
 }
 
 export interface MailContactGetOutput {
+/**
+ * Contact id
+ */
 id: string
+/**
+ * Contact email address, normalized to lowercase
+ */
 email: string
+/**
+ * When the contact was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the contact was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Audience the contact belongs to
+ */
 audienceId: string
 properties?: unknown
+/**
+ * Marketing opt-out flag for this audience
+ */
 unsubscribed: boolean
 }
 
@@ -75093,7 +75708,7 @@ export interface MailContactListInput {
  */
 limit?: number
 /**
- * Opaque pagination cursor from a prior page
+ * Opaque pagination cursor from a prior page; omit for the first page
  */
 cursor?: string
 /**
@@ -75107,15 +75722,39 @@ unsubscribed?: (("true" | "false") | boolean)
 }
 
 export interface MailContactListOutput {
+/**
+ * Contacts on this page, newest first
+ */
 data: {
+/**
+ * Contact id
+ */
 id: string
+/**
+ * Contact email address, normalized to lowercase
+ */
 email: string
+/**
+ * When the contact was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the contact was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Audience the contact belongs to
+ */
 audienceId: string
 properties?: unknown
+/**
+ * Marketing opt-out flag for this audience
+ */
 unsubscribed: boolean
 }[]
+/**
+ * Cursor for the next page; null on the last page
+ */
 nextCursor: (string | null)
 }
 
@@ -75141,12 +75780,30 @@ unsubscribed?: boolean
 }
 
 export interface MailContactUpdateOutput {
+/**
+ * Contact id
+ */
 id: string
+/**
+ * Contact email address, normalized to lowercase
+ */
 email: string
+/**
+ * When the contact was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the contact was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Audience the contact belongs to
+ */
 audienceId: string
 properties?: unknown
+/**
+ * Marketing opt-out flag for this audience
+ */
 unsubscribed: boolean
 }
 
@@ -75154,105 +75811,297 @@ export interface MailDomainAllowedListInput {
 
 }
 
+/**
+ * Apex domains this product may register sending domains under
+ */
 export type MailDomainAllowedListOutput = {
-mode: string
+/**
+ * Who operates DNS under this apex: managed if the platform publishes the records, external if you do
+ */
+mode: ("external" | "managed")
+/**
+ * The apex domain itself, e.g. "example.com"
+ */
 domain: string
+/**
+ * Governance domain id — pass it to the governance console, not to mail_domain_get
+ */
 domainId: string
+/**
+ * How many extensions currently send under this apex
+ */
 extensionCount: number
 }[]
 
 export interface MailDomainCreateInput {
 /**
- * The sending domain to register, e.g. "example.com"
+ * The sending domain to register, e.g. "example.com"; it must sit under an apex this product is allowed to use (see mail_domain_allowed_list)
  */
 name: string
 /**
- * AWS region for the SES identity (data residency); immutable after create
+ * AWS region for the SES identity, which fixes data residency (default "eu-north-1"); immutable once the domain is created
  */
 region?: string
 }
 
 export interface MailDomainCreateOutput {
+/**
+ * Sending domain id
+ */
 id: string
-tls: string
+/**
+ * TLS policy for delivery: opportunistic falls back to plaintext if the recipient offers no TLS, enforced fails the send instead
+ */
+tls: ("opportunistic" | "enforced")
+/**
+ * Governed apex this domain sits under; null if it is not governed
+ */
 apex: (string | null)
-mode: (string | null)
+/**
+ * Who operates DNS: managed if the platform publishes the records for you, external if you publish them yourself; null if the domain is not governed
+ */
+mode: (("external" | "managed") | null)
+/**
+ * The sending domain itself, e.g. "example.com"
+ */
 name: string
+/**
+ * True only when the domain is verified AND its governance binding is active — the condition for sending from it
+ */
 active: boolean
+/**
+ * AWS region hosting the SES identity, which fixes data residency; set at create time and immutable
+ */
 region: string
-status: string
+/**
+ * SES verification state: not_started before the first check, pending while DNS propagates, verified once sending is allowed, failed or temporary_failure when SES could not verify
+ */
+status: ("not_started" | "pending" | "verified" | "failed" | "temporary_failure")
+/**
+ * DNS records to publish for this domain, each with its last-seen resolution status
+ */
 records: {
+/**
+ * Fully-qualified host the record is published at
+ */
 name: string
-type: string
+/**
+ * DNS record type to publish
+ */
+type: ("CNAME" | "TXT" | "MX")
+/**
+ * Value the record must resolve to
+ */
 value: string
-purpose: string
+/**
+ * What the record is for: dkim signs outgoing mail, spf authorises the sender, return-path-mx routes bounces back, dmarc states the policy
+ */
+purpose: ("dkim" | "spf" | "return-path-mx" | "dmarc")
+/**
+ * MX priority; present only on MX records
+ */
 priority?: number
-required: boolean
+/**
+ * True if the domain cannot verify without this record; false if it is optional
+ */
+required: boolean
+/**
+ * True if the record was found in DNS at the last check; absent when no check has run
+ */
 resolved?: boolean
 }[]
+/**
+ * When the domain was registered (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the domain record was last changed (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * When the domain became verified (ISO 8601 UTC); null while it is not
+ */
 verifiedAt: (string | null)
+/**
+ * Human-readable steps still outstanding before this domain can send
+ */
 instructions: string[]
+/**
+ * True if a 1x1 pixel is injected into outgoing mail to record opens
+ */
 openTracking: boolean
-bindingStatus: string
+/**
+ * Governance binding state: pending while it is being granted, active once the domain may be used, failed if it could not be granted
+ */
+bindingStatus: ("pending" | "active" | "failed")
+/**
+ * True if links are rewritten through the tracking host to record clicks
+ */
 clickTracking: boolean
+/**
+ * Host used as the bounce (Return-Path) address, so bounces come back to this product
+ */
 customReturnPath: string
+/**
+ * Host serving the click redirect and the open pixel; null if tracking is off
+ */
 trackingSubdomain: (string | null)
+/**
+ * Id of the governance domain this one is registered under; null if it is not governed
+ */
 governanceDomainId: (string | null)
+/**
+ * Id of the binding between this product and the governance domain; null if unbound
+ */
 governanceBindingId: (string | null)
+/**
+ * When verification was first requested (ISO 8601 UTC)
+ */
 verificationStartedAt: string
+/**
+ * When DNS and SES were last checked (ISO 8601 UTC); null if no check has run yet
+ */
 lastVerificationCheckAt: (string | null)
 }
 
 export interface MailDomainDeleteInput {
 /**
- * Domain id to delete
+ * Sending domain to delete, along with its SES identity
  */
 id: string
 }
 
 export interface MailDomainDeleteOutput {
+/**
+ * True once the domain and its SES identity are gone
+ */
 deleted: boolean
 }
 
 export interface MailDomainGetInput {
 /**
- * Domain id
+ * Sending domain id
  */
 id: string
 }
 
 export interface MailDomainGetOutput {
+/**
+ * Sending domain id
+ */
 id: string
-tls: string
+/**
+ * TLS policy for delivery: opportunistic falls back to plaintext if the recipient offers no TLS, enforced fails the send instead
+ */
+tls: ("opportunistic" | "enforced")
+/**
+ * Governed apex this domain sits under; null if it is not governed
+ */
 apex: (string | null)
-mode: (string | null)
+/**
+ * Who operates DNS: managed if the platform publishes the records for you, external if you publish them yourself; null if the domain is not governed
+ */
+mode: (("external" | "managed") | null)
+/**
+ * The sending domain itself, e.g. "example.com"
+ */
 name: string
+/**
+ * True only when the domain is verified AND its governance binding is active — the condition for sending from it
+ */
 active: boolean
+/**
+ * AWS region hosting the SES identity, which fixes data residency; set at create time and immutable
+ */
 region: string
-status: string
+/**
+ * SES verification state: not_started before the first check, pending while DNS propagates, verified once sending is allowed, failed or temporary_failure when SES could not verify
+ */
+status: ("not_started" | "pending" | "verified" | "failed" | "temporary_failure")
+/**
+ * DNS records to publish for this domain, each with its last-seen resolution status
+ */
 records: {
+/**
+ * Fully-qualified host the record is published at
+ */
 name: string
-type: string
+/**
+ * DNS record type to publish
+ */
+type: ("CNAME" | "TXT" | "MX")
+/**
+ * Value the record must resolve to
+ */
 value: string
-purpose: string
+/**
+ * What the record is for: dkim signs outgoing mail, spf authorises the sender, return-path-mx routes bounces back, dmarc states the policy
+ */
+purpose: ("dkim" | "spf" | "return-path-mx" | "dmarc")
+/**
+ * MX priority; present only on MX records
+ */
 priority?: number
+/**
+ * True if the domain cannot verify without this record; false if it is optional
+ */
 required: boolean
+/**
+ * True if the record was found in DNS at the last check; absent when no check has run
+ */
 resolved?: boolean
 }[]
+/**
+ * When the domain was registered (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the domain record was last changed (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * When the domain became verified (ISO 8601 UTC); null while it is not
+ */
 verifiedAt: (string | null)
+/**
+ * Human-readable steps still outstanding before this domain can send
+ */
 instructions: string[]
+/**
+ * True if a 1x1 pixel is injected into outgoing mail to record opens
+ */
 openTracking: boolean
-bindingStatus: string
+/**
+ * Governance binding state: pending while it is being granted, active once the domain may be used, failed if it could not be granted
+ */
+bindingStatus: ("pending" | "active" | "failed")
+/**
+ * True if links are rewritten through the tracking host to record clicks
+ */
 clickTracking: boolean
+/**
+ * Host used as the bounce (Return-Path) address, so bounces come back to this product
+ */
 customReturnPath: string
+/**
+ * Host serving the click redirect and the open pixel; null if tracking is off
+ */
 trackingSubdomain: (string | null)
+/**
+ * Id of the governance domain this one is registered under; null if it is not governed
+ */
 governanceDomainId: (string | null)
+/**
+ * Id of the binding between this product and the governance domain; null if unbound
+ */
 governanceBindingId: (string | null)
+/**
+ * When verification was first requested (ISO 8601 UTC)
+ */
 verificationStartedAt: string
+/**
+ * When DNS and SES were last checked (ISO 8601 UTC); null if no check has run yet
+ */
 lastVerificationCheckAt: (string | null)
 }
 
@@ -75260,170 +76109,485 @@ export interface MailDomainListInput {
 
 }
 
+/**
+ * Sending domains registered for the current product
+ */
 export type MailDomainListOutput = {
+/**
+ * Sending domain id
+ */
 id: string
-tls: string
+/**
+ * TLS policy for delivery: opportunistic falls back to plaintext if the recipient offers no TLS, enforced fails the send instead
+ */
+tls: ("opportunistic" | "enforced")
+/**
+ * Governed apex this domain sits under; null if it is not governed
+ */
 apex: (string | null)
-mode: (string | null)
+/**
+ * Who operates DNS: managed if the platform publishes the records for you, external if you publish them yourself; null if the domain is not governed
+ */
+mode: (("external" | "managed") | null)
+/**
+ * The sending domain itself, e.g. "example.com"
+ */
 name: string
+/**
+ * True only when the domain is verified AND its governance binding is active — the condition for sending from it
+ */
 active: boolean
+/**
+ * AWS region hosting the SES identity, which fixes data residency; set at create time and immutable
+ */
 region: string
-status: string
+/**
+ * SES verification state: not_started before the first check, pending while DNS propagates, verified once sending is allowed, failed or temporary_failure when SES could not verify
+ */
+status: ("not_started" | "pending" | "verified" | "failed" | "temporary_failure")
+/**
+ * DNS records to publish for this domain, each with its last-seen resolution status
+ */
 records: {
+/**
+ * Fully-qualified host the record is published at
+ */
 name: string
-type: string
+/**
+ * DNS record type to publish
+ */
+type: ("CNAME" | "TXT" | "MX")
+/**
+ * Value the record must resolve to
+ */
 value: string
-purpose: string
+/**
+ * What the record is for: dkim signs outgoing mail, spf authorises the sender, return-path-mx routes bounces back, dmarc states the policy
+ */
+purpose: ("dkim" | "spf" | "return-path-mx" | "dmarc")
+/**
+ * MX priority; present only on MX records
+ */
 priority?: number
+/**
+ * True if the domain cannot verify without this record; false if it is optional
+ */
 required: boolean
+/**
+ * True if the record was found in DNS at the last check; absent when no check has run
+ */
 resolved?: boolean
 }[]
+/**
+ * When the domain was registered (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the domain record was last changed (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * When the domain became verified (ISO 8601 UTC); null while it is not
+ */
 verifiedAt: (string | null)
+/**
+ * Human-readable steps still outstanding before this domain can send
+ */
 instructions: string[]
+/**
+ * True if a 1x1 pixel is injected into outgoing mail to record opens
+ */
 openTracking: boolean
-bindingStatus: string
+/**
+ * Governance binding state: pending while it is being granted, active once the domain may be used, failed if it could not be granted
+ */
+bindingStatus: ("pending" | "active" | "failed")
+/**
+ * True if links are rewritten through the tracking host to record clicks
+ */
 clickTracking: boolean
+/**
+ * Host used as the bounce (Return-Path) address, so bounces come back to this product
+ */
 customReturnPath: string
+/**
+ * Host serving the click redirect and the open pixel; null if tracking is off
+ */
 trackingSubdomain: (string | null)
+/**
+ * Id of the governance domain this one is registered under; null if it is not governed
+ */
 governanceDomainId: (string | null)
+/**
+ * Id of the binding between this product and the governance domain; null if unbound
+ */
 governanceBindingId: (string | null)
+/**
+ * When verification was first requested (ISO 8601 UTC)
+ */
 verificationStartedAt: string
+/**
+ * When DNS and SES were last checked (ISO 8601 UTC); null if no check has run yet
+ */
 lastVerificationCheckAt: (string | null)
 }[]
 
 export interface MailDomainUpdateInput {
 /**
- * Domain id
+ * Sending domain id
  */
 id: string
 /**
- * TLS policy: opportunistic (default) or enforced
+ * TLS policy: opportunistic (default) falls back to plaintext, enforced fails the send instead; omit to leave it unchanged
  */
 tls?: ("opportunistic" | "enforced")
 /**
- * Enable open tracking (1×1 pixel); off by default
+ * Record opens by injecting a 1x1 pixel (off by default); omit to leave it unchanged
  */
 openTracking?: boolean
 /**
- * Enable click tracking (link rewrite); off by default
+ * Record clicks by rewriting links through the tracking host (off by default); omit to leave it unchanged
  */
 clickTracking?: boolean
 /**
- * Host used for the click-redirect and open-pixel
+ * Host to serve the click redirect and open pixel from, or null to clear it; omit to leave it unchanged
  */
 trackingSubdomain?: (string | null)
 }
 
 export interface MailDomainUpdateOutput {
+/**
+ * Sending domain id
+ */
 id: string
-tls: string
+/**
+ * TLS policy for delivery: opportunistic falls back to plaintext if the recipient offers no TLS, enforced fails the send instead
+ */
+tls: ("opportunistic" | "enforced")
+/**
+ * Governed apex this domain sits under; null if it is not governed
+ */
 apex: (string | null)
-mode: (string | null)
+/**
+ * Who operates DNS: managed if the platform publishes the records for you, external if you publish them yourself; null if the domain is not governed
+ */
+mode: (("external" | "managed") | null)
+/**
+ * The sending domain itself, e.g. "example.com"
+ */
 name: string
+/**
+ * True only when the domain is verified AND its governance binding is active — the condition for sending from it
+ */
 active: boolean
+/**
+ * AWS region hosting the SES identity, which fixes data residency; set at create time and immutable
+ */
 region: string
-status: string
+/**
+ * SES verification state: not_started before the first check, pending while DNS propagates, verified once sending is allowed, failed or temporary_failure when SES could not verify
+ */
+status: ("not_started" | "pending" | "verified" | "failed" | "temporary_failure")
+/**
+ * DNS records to publish for this domain, each with its last-seen resolution status
+ */
 records: {
+/**
+ * Fully-qualified host the record is published at
+ */
 name: string
-type: string
+/**
+ * DNS record type to publish
+ */
+type: ("CNAME" | "TXT" | "MX")
+/**
+ * Value the record must resolve to
+ */
 value: string
-purpose: string
+/**
+ * What the record is for: dkim signs outgoing mail, spf authorises the sender, return-path-mx routes bounces back, dmarc states the policy
+ */
+purpose: ("dkim" | "spf" | "return-path-mx" | "dmarc")
+/**
+ * MX priority; present only on MX records
+ */
 priority?: number
+/**
+ * True if the domain cannot verify without this record; false if it is optional
+ */
 required: boolean
+/**
+ * True if the record was found in DNS at the last check; absent when no check has run
+ */
 resolved?: boolean
 }[]
+/**
+ * When the domain was registered (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the domain record was last changed (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * When the domain became verified (ISO 8601 UTC); null while it is not
+ */
 verifiedAt: (string | null)
+/**
+ * Human-readable steps still outstanding before this domain can send
+ */
 instructions: string[]
+/**
+ * True if a 1x1 pixel is injected into outgoing mail to record opens
+ */
 openTracking: boolean
-bindingStatus: string
+/**
+ * Governance binding state: pending while it is being granted, active once the domain may be used, failed if it could not be granted
+ */
+bindingStatus: ("pending" | "active" | "failed")
+/**
+ * True if links are rewritten through the tracking host to record clicks
+ */
 clickTracking: boolean
+/**
+ * Host used as the bounce (Return-Path) address, so bounces come back to this product
+ */
 customReturnPath: string
+/**
+ * Host serving the click redirect and the open pixel; null if tracking is off
+ */
 trackingSubdomain: (string | null)
+/**
+ * Id of the governance domain this one is registered under; null if it is not governed
+ */
 governanceDomainId: (string | null)
+/**
+ * Id of the binding between this product and the governance domain; null if unbound
+ */
 governanceBindingId: (string | null)
+/**
+ * When verification was first requested (ISO 8601 UTC)
+ */
 verificationStartedAt: string
+/**
+ * When DNS and SES were last checked (ISO 8601 UTC); null if no check has run yet
+ */
 lastVerificationCheckAt: (string | null)
 }
 
 export interface MailDomainVerifyInput {
 /**
- * Domain id to re-check now
+ * Sending domain to re-check against DNS and SES right now, instead of waiting for the next scheduled check
  */
 id: string
 }
 
 export interface MailDomainVerifyOutput {
+/**
+ * Sending domain id
+ */
 id: string
-tls: string
+/**
+ * TLS policy for delivery: opportunistic falls back to plaintext if the recipient offers no TLS, enforced fails the send instead
+ */
+tls: ("opportunistic" | "enforced")
+/**
+ * Governed apex this domain sits under; null if it is not governed
+ */
 apex: (string | null)
-mode: (string | null)
+/**
+ * Who operates DNS: managed if the platform publishes the records for you, external if you publish them yourself; null if the domain is not governed
+ */
+mode: (("external" | "managed") | null)
+/**
+ * The sending domain itself, e.g. "example.com"
+ */
 name: string
+/**
+ * True only when the domain is verified AND its governance binding is active — the condition for sending from it
+ */
 active: boolean
+/**
+ * AWS region hosting the SES identity, which fixes data residency; set at create time and immutable
+ */
 region: string
-status: string
+/**
+ * SES verification state: not_started before the first check, pending while DNS propagates, verified once sending is allowed, failed or temporary_failure when SES could not verify
+ */
+status: ("not_started" | "pending" | "verified" | "failed" | "temporary_failure")
+/**
+ * DNS records to publish for this domain, each with its last-seen resolution status
+ */
 records: {
+/**
+ * Fully-qualified host the record is published at
+ */
 name: string
-type: string
+/**
+ * DNS record type to publish
+ */
+type: ("CNAME" | "TXT" | "MX")
+/**
+ * Value the record must resolve to
+ */
 value: string
-purpose: string
+/**
+ * What the record is for: dkim signs outgoing mail, spf authorises the sender, return-path-mx routes bounces back, dmarc states the policy
+ */
+purpose: ("dkim" | "spf" | "return-path-mx" | "dmarc")
+/**
+ * MX priority; present only on MX records
+ */
 priority?: number
+/**
+ * True if the domain cannot verify without this record; false if it is optional
+ */
 required: boolean
+/**
+ * True if the record was found in DNS at the last check; absent when no check has run
+ */
 resolved?: boolean
 }[]
+/**
+ * When the domain was registered (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the domain record was last changed (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * When the domain became verified (ISO 8601 UTC); null while it is not
+ */
 verifiedAt: (string | null)
+/**
+ * Human-readable steps still outstanding before this domain can send
+ */
 instructions: string[]
+/**
+ * True if a 1x1 pixel is injected into outgoing mail to record opens
+ */
 openTracking: boolean
-bindingStatus: string
+/**
+ * Governance binding state: pending while it is being granted, active once the domain may be used, failed if it could not be granted
+ */
+bindingStatus: ("pending" | "active" | "failed")
+/**
+ * True if links are rewritten through the tracking host to record clicks
+ */
 clickTracking: boolean
+/**
+ * Host used as the bounce (Return-Path) address, so bounces come back to this product
+ */
 customReturnPath: string
+/**
+ * Host serving the click redirect and the open pixel; null if tracking is off
+ */
 trackingSubdomain: (string | null)
+/**
+ * Id of the governance domain this one is registered under; null if it is not governed
+ */
 governanceDomainId: (string | null)
+/**
+ * Id of the binding between this product and the governance domain; null if unbound
+ */
 governanceBindingId: (string | null)
+/**
+ * When verification was first requested (ISO 8601 UTC)
+ */
 verificationStartedAt: string
+/**
+ * When DNS and SES were last checked (ISO 8601 UTC); null if no check has run yet
+ */
 lastVerificationCheckAt: (string | null)
 }
 
 export interface MailEmailCancelInput {
 /**
- * Email id
+ * Email id — as returned by mail_email_send
  */
 id: string
 }
 
 export interface MailEmailCancelOutput {
+/**
+ * Id of the canceled email
+ */
 id: string
+/**
+ * The email’s state after the call — always "canceled"
+ */
 status: "canceled"
 }
 
 export interface MailEmailGetInput {
 /**
- * Email id
+ * Email id — as returned by mail_email_send
  */
 id: string
 }
 
 export interface MailEmailGetOutput {
+/**
+ * Cc recipients; empty when there were none
+ */
 cc: string[]
+/**
+ * Email id
+ */
 id: string
+/**
+ * Primary recipients
+ */
 to: string[]
+/**
+ * Bcc recipients; empty when there were none. Never appeared in the message headers.
+ */
 bcc: string[]
+/**
+ * Sender the message was sent as
+ */
 from: string
+/**
+ * Where the email stands: scheduled, queued, sent, failed, canceled, delivered, bounced, complained, suppressed or blocked
+ */
 status: ("scheduled" | "queued" | "sent" | "failed" | "canceled" | "delivered" | "bounced" | "complained" | "suppressed" | "blocked")
+/**
+ * Subject line as sent, after any template rendering
+ */
 subject: string
+/**
+ * ISO-8601 instant the email was accepted
+ */
 created_at: string
+/**
+ * The latest lifecycle event, the reason `status` reads as it does
+ */
 last_event: {
+/**
+ * The most recent lifecycle event — `email.` followed by the status it moved to
+ */
 type: ("email.scheduled" | "email.queued" | "email.sent" | "email.failed" | "email.canceled" | "email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.blocked")
+/**
+ * ISO-8601 instant of that event; null when no event has been recorded yet
+ */
 created_at: (string | null)
 }
+/**
+ * Template the email was rendered from; null for an inline send
+ */
 template_id: (string | null)
+/**
+ * ISO-8601 instant the email is scheduled for; null when it was sent immediately
+ */
 scheduled_at: (string | null)
+/**
+ * Name of that template; null for an inline send
+ */
 template_name: (string | null)
+/**
+ * The sending provider’s own id, for correlating with its logs; null until the email leaves
+ */
 provider_message_id: (string | null)
 }
 
@@ -75441,38 +76605,41 @@ to?: (string | string[])
  */
 bcc?: (string | string[])
 /**
- * Sender, e.g. "Name <you@your-domain.com>"
+ * Sender on a verified domain, e.g. "Name <you@your-domain.com>"
  */
 from: string
 /**
- * HTML body
+ * HTML body. Inline sends only — forbidden with a template.
  */
 html?: string
 /**
- * Metadata tags
+ * Metadata tags attached to the message as `X-Tag-<name>` headers
  */
 tags?: {
 /**
- * Tag name
+ * Tag name — printable US-ASCII without a colon; becomes the `X-Tag-<name>` header
  */
 name: string
 /**
- * Tag value
+ * Tag value; must not contain CR or LF
  */
 value: string
 }[]
 /**
- * Plain-text body; auto-derived from html if omitted
+ * Plain-text body; auto-derived from html if omitted. Inline sends only.
  */
 text?: string
 /**
- * Custom headers map
+ * Custom MIME headers, keyed by header name
  */
 headers?: {
+/**
+ * Header value; must not contain CR or LF
+ */
 [k: string]: string
 }
 /**
- * Email subject (required for inline sends)
+ * Subject line, capped at the RFC-5322 line limit. Required for inline sends, forbidden with a template.
  */
 subject?: string
 /**
@@ -75488,25 +76655,28 @@ template?: {
  */
 id: string
 /**
- * Values for the template variables
+ * Values for the template variables. Defaults to {}.
  */
 variables?: {
 [k: string]: (string | number | boolean)
 }
 }
 /**
- * ISO-8601 instant to send at; future, within 30 days. Omit to send now.
+ * ISO-8601 instant to send at; must be in the future and within 30 days. Omit to send now.
  */
 scheduled_at?: string
 }
 
 export interface MailEmailSendOutput {
+/**
+ * Id of the accepted email — pass it to mail_email_get to follow delivery
+ */
 id: string
 }
 
 export interface MailEmailSendBatchInput {
 /**
- * Up to 100 emails to send, each shaped like a single send
+ * Up to 100 emails to send; `scheduled_at` is not allowed on a batch item
  */
 emails: {
 /**
@@ -75522,38 +76692,41 @@ to?: (string | string[])
  */
 bcc?: (string | string[])
 /**
- * Sender, e.g. "Name <you@your-domain.com>"
+ * Sender on a verified domain, e.g. "Name <you@your-domain.com>"
  */
 from: string
 /**
- * HTML body
+ * HTML body. Inline sends only — forbidden with a template.
  */
 html?: string
 /**
- * Metadata tags
+ * Metadata tags attached to the message as `X-Tag-<name>` headers
  */
 tags?: {
 /**
- * Tag name
+ * Tag name — printable US-ASCII without a colon; becomes the `X-Tag-<name>` header
  */
 name: string
 /**
- * Tag value
+ * Tag value; must not contain CR or LF
  */
 value: string
 }[]
 /**
- * Plain-text body; auto-derived from html if omitted
+ * Plain-text body; auto-derived from html if omitted. Inline sends only.
  */
 text?: string
 /**
- * Custom headers map
+ * Custom MIME headers, keyed by header name
  */
 headers?: {
+/**
+ * Header value; must not contain CR or LF
+ */
 [k: string]: string
 }
 /**
- * Email subject (required for inline sends)
+ * Subject line, capped at the RFC-5322 line limit. Required for inline sends, forbidden with a template.
  */
 subject?: string
 /**
@@ -75569,35 +76742,44 @@ template?: {
  */
 id: string
 /**
- * Values for the template variables
+ * Values for the template variables. Defaults to {}.
  */
 variables?: {
 [k: string]: (string | number | boolean)
 }
 }
 /**
- * ISO-8601 instant to send at; future, within 30 days. Omit to send now.
+ * ISO-8601 instant to send at; must be in the future and within 30 days. Omit to send now.
  */
 scheduled_at?: string
 }[]
 }
 
+/**
+ * One entry per submitted email, in the order they were submitted
+ */
 export type MailEmailSendBatchOutput = {
+/**
+ * Id of the accepted email
+ */
 id: string
 }[]
 
 export interface MailEmailUpdateInput {
 /**
- * Email id
+ * Email id — as returned by mail_email_send
  */
 id: string
 /**
- * New ISO-8601 instant; future, within 30 days
+ * New ISO-8601 instant to send at; must be in the future and within 30 days
  */
 scheduled_at: string
 }
 
 export interface MailEmailUpdateOutput {
+/**
+ * Id of the accepted email — pass it to mail_email_get to follow delivery
+ */
 id: string
 }
 
@@ -75606,116 +76788,272 @@ export interface MailReputationGetInput {
 }
 
 export interface MailReputationGetOutput {
+/**
+ * True when sending is currently throttled because a rate crossed its threshold
+ */
 gated: boolean
+/**
+ * Emails sent in the window — the denominator of both rates
+ */
 volume: number
+/**
+ * Spam complaints in the window
+ */
 complaints: number
+/**
+ * The configured limits the rates above are compared against
+ */
 thresholds: {
+/**
+ * Emails needed in the window before either rate is acted on — below it the sample is too small to judge
+ */
 min_volume: number
+/**
+ * Ratio 0-1 at or above which sending is gated
+ */
 complaint_rate: number
+/**
+ * Ratio 0-1 at or above which sending is gated
+ */
 hard_bounce_rate: number
 }
+/**
+ * Length in days of the rolling window the rates below are measured over
+ */
 window_days: number
+/**
+ * Hard bounces in the window
+ */
 hard_bounces: number
+/**
+ * Complaints divided by volume, as a ratio 0-1 (0.001 = 0.1%)
+ */
 complaint_rate: number
-tripped_metric: (string | null)
+/**
+ * Which rate crossed its threshold, or null when nothing did
+ */
+tripped_metric: (("hard_bounce" | "complaint") | null)
+/**
+ * Hard bounces divided by volume, as a ratio 0-1 (0.05 = 5%)
+ */
 hard_bounce_rate: number
 }
 
 export interface MailStatsGetInput {
+/**
+ * Rolling window the aggregation covers, ending now. Defaults to 30d.
+ */
 period?: ("7d" | "30d" | "90d")
 }
 
 export interface MailStatsGetOutput {
+/**
+ * The absolute instants the period resolved to
+ */
 range: {
+/**
+ * Exclusive end of the window (ISO-8601 instant, UTC)
+ */
 to: string
+/**
+ * Inclusive start of the window (ISO-8601 instant, UTC)
+ */
 from: string
 }
+/**
+ * Percent change of each total against the immediately preceding window of the same length
+ */
 deltas: {
+/**
+ * Change in sent against the previous window of the same length, in percent (-100 = halved to nothing, 25 = a quarter more); null when the previous window was empty
+ */
 sent: (number | null)
+/**
+ * Change in bounced against the previous window, in percent; null when the previous window was empty
+ */
 bounced: (number | null)
+/**
+ * Change in delivered against the previous window, in percent; null when the previous window was empty
+ */
 delivered: (number | null)
+/**
+ * Change in complained against the previous window, in percent; null when the previous window was empty
+ */
 complained: (number | null)
 }
-period: string
+/**
+ * The window these numbers cover — the echo of the requested period
+ */
+period: ("7d" | "30d" | "90d")
+/**
+ * Counts over the window
+ */
 totals: {
+/**
+ * Emails accepted for delivery in the window
+ */
 sent: number
+/**
+ * Emails that bounced, hard or soft
+ */
 bounced: number
+/**
+ * Emails the receiving server accepted
+ */
 delivered: number
+/**
+ * Emails a recipient marked as spam
+ */
 complained: number
 }
+/**
+ * One bucket per UTC day in the window, oldest first
+ */
 volume: {
+/**
+ * The UTC day this bucket covers, as YYYY-MM-DD
+ */
 date: string
+/**
+ * Emails accepted for delivery on this day
+ */
 sent: number
+/**
+ * Emails bounced on this day
+ */
 bounced: number
+/**
+ * Emails delivered on this day
+ */
 delivered: number
 }[]
+/**
+ * The three rates senders are judged on, as percentages of sent
+ */
 deliverability: {
+/**
+ * Bounced as a percentage of sent (0-100)
+ */
 bouncedPct: number
+/**
+ * Delivered as a percentage of sent (0-100)
+ */
 deliveredPct: number
+/**
+ * Complaints as a percentage of sent (0-100)
+ */
 complainedPct: number
 }
 }
 
 export interface MailSuppressionAddInput {
 /**
- * Optional free-text note
+ * Optional free-text note explaining why the address was suppressed
  */
 note?: string
 /**
- * Email address to suppress
+ * Email address to suppress, e.g. "user@example.com"; matched case-insensitively
  */
 address: string
 }
 
 export interface MailSuppressionAddOutput {
+/**
+ * Suppression entry id
+ */
 id: string
+/**
+ * Free-text note recorded when the entry was added by hand; null otherwise
+ */
 note: (string | null)
-reason: string
+/**
+ * Why the address is suppressed: hard_bounce and complaint come from SES feedback, unsubscribe from the recipient, manual from mail_suppression_add
+ */
+reason: ("hard_bounce" | "complaint" | "manual" | "unsubscribe")
+/**
+ * The suppressed recipient address, lowercased and trimmed
+ */
 address: string
+/**
+ * When the address was suppressed (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * Id of the email event that caused the suppression; null for a manual entry
+ */
 source_event_id: (string | null)
 }
 
 export interface MailSuppressionListInput {
 /**
- * Case-insensitive substring match on address
+ * Case-insensitive substring match on the address; omit for no address filter
  */
 q?: string
 /**
- * Max items per page (1–100, default 50)
+ * Max entries per page, 1-100 (default 50)
  */
 limit?: number
 /**
- * Opaque pagination cursor from a prior page
+ * Opaque pagination cursor from a prior page's next_cursor; omit for the first page
  */
 cursor?: string
 /**
- * Filter by reason
+ * Only return entries suppressed for this reason; omit for every reason
  */
 reason?: ("hard_bounce" | "complaint" | "manual" | "unsubscribe")
 }
 
 export interface MailSuppressionListOutput {
+/**
+ * This page of suppression entries, newest first
+ */
 items: {
+/**
+ * Suppression entry id
+ */
 id: string
+/**
+ * Free-text note recorded when the entry was added by hand; null otherwise
+ */
 note: (string | null)
-reason: string
+/**
+ * Why the address is suppressed: hard_bounce and complaint come from SES feedback, unsubscribe from the recipient, manual from mail_suppression_add
+ */
+reason: ("hard_bounce" | "complaint" | "manual" | "unsubscribe")
+/**
+ * The suppressed recipient address, lowercased and trimmed
+ */
 address: string
+/**
+ * When the address was suppressed (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * Id of the email event that caused the suppression; null for a manual entry
+ */
 source_event_id: (string | null)
 }[]
+/**
+ * Opaque cursor to pass back as `cursor` for the next page; null on the last page
+ */
 next_cursor: (string | null)
 }
 
 export interface MailSuppressionRemoveInput {
 /**
- * Email address to remove from the suppression list
+ * Email address to remove from the suppression list; matched case-insensitively
  */
 address: string
 }
 
 export interface MailSuppressionRemoveOutput {
+/**
+ * The address the removal was attempted for, as normalized
+ */
 address: string
+/**
+ * True if an entry was removed; false if the address was not suppressed (the call is idempotent)
+ */
 removed: boolean
 }
 
@@ -79315,18 +80653,57 @@ optional?: boolean
 }
 
 export interface MailTemplateCreateOutput {
+/**
+ * Template id
+ */
 id: string
+/**
+ * HTML body; may contain {{ variable }} placeholders
+ */
 html: string
+/**
+ * Human label for the template
+ */
 name: string
+/**
+ * Plaintext body; null when none was supplied
+ */
 text: (string | null)
-status: string
+/**
+ * Lifecycle status: a draft is editable, a published template is not
+ */
+status: ("draft" | "published")
+/**
+ * Email subject; may contain {{ variable }} placeholders
+ */
 subject: string
+/**
+ * When the template was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the template was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Declared variables of this template (at most 20)
+ */
 variables: {
+/**
+ * Placeholder identifier used as {{ name }}
+ */
 name: string
-type: string
+/**
+ * Declared type (metadata; rendered as string in v1)
+ */
+type: ("string" | "number" | "boolean")
+/**
+ * Value used when none is supplied
+ */
 fallback?: string
+/**
+ * If true, an absent value renders as empty string
+ */
 optional: boolean
 }[]
 }
@@ -79339,6 +80716,9 @@ id: string
 }
 
 export interface MailTemplateDeleteOutput {
+/**
+ * True once the template is gone
+ */
 deleted: boolean
 }
 
@@ -79350,22 +80730,70 @@ id: string
 }
 
 export interface MailTemplateGetOutput {
+/**
+ * Template id
+ */
 id: string
+/**
+ * HTML body; may contain {{ variable }} placeholders
+ */
 html: string
+/**
+ * Human label for the template
+ */
 name: string
+/**
+ * Plaintext body; null when none was supplied
+ */
 text: (string | null)
+/**
+ * Send-usage rollup for this template
+ */
 usage: {
+/**
+ * How many emails were sent from this template
+ */
 email_count: number
+/**
+ * When the template was last sent from (ISO 8601 UTC); null if never
+ */
 last_sent_at: (string | null)
 }
-status: string
+/**
+ * Lifecycle status: a draft is editable, a published template is not
+ */
+status: ("draft" | "published")
+/**
+ * Email subject; may contain {{ variable }} placeholders
+ */
 subject: string
+/**
+ * When the template was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the template was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Declared variables of this template (at most 20)
+ */
 variables: {
+/**
+ * Placeholder identifier used as {{ name }}
+ */
 name: string
-type: string
+/**
+ * Declared type (metadata; rendered as string in v1)
+ */
+type: ("string" | "number" | "boolean")
+/**
+ * Value used when none is supplied
+ */
 fallback?: string
+/**
+ * If true, an absent value renders as empty string
+ */
 optional: boolean
 }[]
 }
@@ -79375,18 +80803,57 @@ export interface MailTemplateListInput {
 }
 
 export type MailTemplateListOutput = {
+/**
+ * Template id
+ */
 id: string
+/**
+ * HTML body; may contain {{ variable }} placeholders
+ */
 html: string
+/**
+ * Human label for the template
+ */
 name: string
+/**
+ * Plaintext body; null when none was supplied
+ */
 text: (string | null)
-status: string
+/**
+ * Lifecycle status: a draft is editable, a published template is not
+ */
+status: ("draft" | "published")
+/**
+ * Email subject; may contain {{ variable }} placeholders
+ */
 subject: string
+/**
+ * When the template was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the template was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Declared variables of this template (at most 20)
+ */
 variables: {
+/**
+ * Placeholder identifier used as {{ name }}
+ */
 name: string
-type: string
+/**
+ * Declared type (metadata; rendered as string in v1)
+ */
+type: ("string" | "number" | "boolean")
+/**
+ * Value used when none is supplied
+ */
 fallback?: string
+/**
+ * If true, an absent value renders as empty string
+ */
 optional: boolean
 }[]
 }[]
@@ -79399,18 +80866,57 @@ id: string
 }
 
 export interface MailTemplatePublishOutput {
+/**
+ * Template id
+ */
 id: string
+/**
+ * HTML body; may contain {{ variable }} placeholders
+ */
 html: string
+/**
+ * Human label for the template
+ */
 name: string
+/**
+ * Plaintext body; null when none was supplied
+ */
 text: (string | null)
-status: string
+/**
+ * Lifecycle status: a draft is editable, a published template is not
+ */
+status: ("draft" | "published")
+/**
+ * Email subject; may contain {{ variable }} placeholders
+ */
 subject: string
+/**
+ * When the template was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the template was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Declared variables of this template (at most 20)
+ */
 variables: {
+/**
+ * Placeholder identifier used as {{ name }}
+ */
 name: string
-type: string
+/**
+ * Declared type (metadata; rendered as string in v1)
+ */
+type: ("string" | "number" | "boolean")
+/**
+ * Value used when none is supplied
+ */
 fallback?: string
+/**
+ * If true, an absent value renders as empty string
+ */
 optional: boolean
 }[]
 }
@@ -79420,11 +80926,25 @@ export interface MailTemplateUpdateInput {
  * Template id
  */
 id: string
+/**
+ * New HTML body; unchanged when omitted
+ */
 html?: string
+/**
+ * New human label; unchanged when omitted
+ */
 name?: string
+/**
+ * New plaintext body; null clears it and it is re-derived from html. Unchanged when omitted
+ */
 text?: (string | null)
+/**
+ * New email subject; may contain {{ variable }} placeholders. Unchanged when omitted
+ */
 subject?: string
 /**
+ * Replacement list of declared variables ([{name,type,optional,fallback}], <=20). Unchanged when omitted
+ * 
  * @maxItems 20
  */
 variables?: []|[{
@@ -83001,18 +84521,57 @@ optional?: boolean
 }
 
 export interface MailTemplateUpdateOutput {
+/**
+ * Template id
+ */
 id: string
+/**
+ * HTML body; may contain {{ variable }} placeholders
+ */
 html: string
+/**
+ * Human label for the template
+ */
 name: string
+/**
+ * Plaintext body; null when none was supplied
+ */
 text: (string | null)
-status: string
+/**
+ * Lifecycle status: a draft is editable, a published template is not
+ */
+status: ("draft" | "published")
+/**
+ * Email subject; may contain {{ variable }} placeholders
+ */
 subject: string
+/**
+ * When the template was created (ISO 8601 UTC)
+ */
 createdAt: string
+/**
+ * When the template was last modified (ISO 8601 UTC)
+ */
 updatedAt: string
+/**
+ * Declared variables of this template (at most 20)
+ */
 variables: {
+/**
+ * Placeholder identifier used as {{ name }}
+ */
 name: string
-type: string
+/**
+ * Declared type (metadata; rendered as string in v1)
+ */
+type: ("string" | "number" | "boolean")
+/**
+ * Value used when none is supplied
+ */
 fallback?: string
+/**
+ * If true, an absent value renders as empty string
+ */
 optional: boolean
 }[]
 }
@@ -83022,37 +84581,88 @@ export interface MailUsageGetInput {
 }
 
 export interface MailUsageGetOutput {
+/**
+ * Email sending usage against the free-tier limits
+ */
 emails: {
-day: MailUsageGetOutputDay
-month: MailUsageGetOutputDay
+/**
+ * Sending allowance today (UTC)
+ */
+day: {
+/**
+ * Emails accepted for delivery so far today (UTC)
+ */
+used: number
+/**
+ * Free-tier allowance today (UTC)
+ */
+limit: number
+/**
+ * Allowance left today (UTC) — limit minus used, never below zero
+ */
+remaining: number
+}
+/**
+ * Sending allowance this month (UTC)
+ */
+month: {
+/**
+ * Emails accepted for delivery so far this month (UTC)
+ */
+used: number
+/**
+ * Free-tier allowance this month (UTC)
+ */
+limit: number
+/**
+ * Allowance left this month (UTC) — limit minus used, never below zero
+ */
+remaining: number
+}
+/**
+ * True when a further send would be refused right now because a limit or the hard cap is reached
+ */
 blocked: boolean
+/**
+ * Monthly ceiling that cannot be exceeded even with an allowance left elsewhere
+ */
 hard_cap: number
 }
+/**
+ * The two windows the counters below are scoped to
+ */
 period: {
+/**
+ * The UTC day the daily counters cover, as YYYY-MM-DD
+ */
 day: string
+/**
+ * The UTC month the monthly counters cover, as YYYY-MM
+ */
 month: string
 }
+/**
+ * Point-in-time contact storage — a stock, not a per-period flow
+ */
 contacts: {
+/**
+ * Contacts stored for the product at this instant
+ */
 count: number
 }
 }
-export interface MailUsageGetOutputDay {
-used: number
-limit: number
-remaining: number
-}
 
 export interface MailWebhookCreateInput {
 /**
- * HTTPS URL that signed events are POSTed to
+ * HTTPS URL that signed events are POSTed to; plain http is rejected
  */
 url: string
 /**
- * Optional human label
+ * Optional human label for the endpoint, e.g. "billing service"
  */
 description?: string
 /**
- * Event types to deliver. One or more of: email.delivered, email.bounced, email.complained, email.suppressed, email.opened, email.clicked
+ * Event types to deliver; at least one. One or more of: email.delivered, email.bounced, email.complained, email.suppressed, email.opened, email.clicked
  * 
  * @minItems 1
  */
@@ -83060,50 +84670,116 @@ enabled_events: [("email.delivered" | "email.bounced" | "email.complained" | "em
 }
 
 export interface MailWebhookCreateOutput {
+/**
+ * Webhook endpoint id
+ */
 id: string
+/**
+ * HTTPS URL that signed events are POSTed to
+ */
 url: string
+/**
+ * Signing secret for verifying the delivery signature. Returned only when the endpoint is created and never retrievable again — store it now
+ */
 secret: string
+/**
+ * False if delivery is switched off — the endpoint is kept but nothing is sent to it
+ */
 enabled: boolean
+/**
+ * When the endpoint was registered (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * When the endpoint was last changed (ISO 8601 UTC)
+ */
 updated_at: string
+/**
+ * Human label for the endpoint; null if none was given
+ */
 description: (string | null)
-enabled_events: string[]
+/**
+ * Event types this endpoint receives; anything else is not delivered to it
+ */
+enabled_events: ("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked")[]
 }
 
 export interface MailWebhookDeleteInput {
 /**
- * Webhook endpoint id
+ * Webhook endpoint id; deleting it also discards its delivery history
  */
 id: string
 }
 
 export interface MailWebhookDeleteOutput {
+/**
+ * Id of the endpoint that was deleted
+ */
 id: string
+/**
+ * True once the endpoint and its delivery history are gone
+ */
 deleted: boolean
 }
 
 export interface MailWebhookDeliveriesListInput {
 /**
- * Webhook endpoint id
+ * Webhook endpoint whose delivery attempts to list
  */
 id: string
 /**
- * Max items (1-100, default 50)
+ * Max delivery attempts to return, 1-100 (default 50)
  */
 limit?: number
 }
 
+/**
+ * Recent delivery attempts for the endpoint, newest first
+ */
 export type MailWebhookDeliveriesListOutput = {
+/**
+ * Delivery attempt id
+ */
 id: string
-status: string
+/**
+ * Delivery state: pending while attempts remain, succeeded once the endpoint answered 2xx, failed once retries are exhausted
+ */
+status: ("pending" | "succeeded" | "failed")
+/**
+ * How many times delivery has been attempted so far
+ */
 attempts: number
+/**
+ * Id of the email event that was delivered
+ */
 event_id: string
+/**
+ * When the delivery was queued (ISO 8601 UTC)
+ */
 created_at: string
-event_type: string
+/**
+ * Type of the delivered event
+ */
+event_type: ("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked")
+/**
+ * Error from the last failed attempt; null if the last attempt succeeded or none has run
+ */
 last_error: (string | null)
+/**
+ * When the delivery record was last updated (ISO 8601 UTC)
+ */
 updated_at: string
+/**
+ * Id of the webhook endpoint the event was delivered to
+ */
 endpoint_id: string
+/**
+ * When delivery was last attempted (ISO 8601 UTC); null before the first attempt
+ */
 last_attempt_at: (string | null)
+/**
+ * HTTP status the endpoint returned on the last attempt; null if it could not be reached
+ */
 response_status: (number | null)
 }[]
 
@@ -83115,27 +84791,72 @@ id: string
 }
 
 export interface MailWebhookGetOutput {
+/**
+ * Webhook endpoint id
+ */
 id: string
+/**
+ * HTTPS URL that signed events are POSTed to
+ */
 url: string
+/**
+ * False if delivery is switched off — the endpoint is kept but nothing is sent to it
+ */
 enabled: boolean
+/**
+ * When the endpoint was registered (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * When the endpoint was last changed (ISO 8601 UTC)
+ */
 updated_at: string
+/**
+ * Human label for the endpoint; null if none was given
+ */
 description: (string | null)
-enabled_events: string[]
+/**
+ * Event types this endpoint receives; anything else is not delivered to it
+ */
+enabled_events: ("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked")[]
 }
 
 export interface MailWebhookListInput {
 
 }
 
+/**
+ * Webhook endpoints for the current product, signing secrets omitted
+ */
 export type MailWebhookListOutput = {
+/**
+ * Webhook endpoint id
+ */
 id: string
+/**
+ * HTTPS URL that signed events are POSTed to
+ */
 url: string
+/**
+ * False if delivery is switched off — the endpoint is kept but nothing is sent to it
+ */
 enabled: boolean
+/**
+ * When the endpoint was registered (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * When the endpoint was last changed (ISO 8601 UTC)
+ */
 updated_at: string
+/**
+ * Human label for the endpoint; null if none was given
+ */
 description: (string | null)
-enabled_events: string[]
+/**
+ * Event types this endpoint receives; anything else is not delivered to it
+ */
+enabled_events: ("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked")[]
 }[]
 
 export interface MailWebhookUpdateInput {
@@ -83144,19 +84865,19 @@ export interface MailWebhookUpdateInput {
  */
 id: string
 /**
- * HTTPS URL that signed events are POSTed to
+ * New HTTPS delivery URL; omit to leave it unchanged
  */
 url?: string
 /**
- * Enable (true) or disable (false) delivery
+ * Switch delivery on (true) or off (false); omit to leave it unchanged
  */
 enabled?: boolean
 /**
- * Optional human label
+ * New human label, or null to clear it; omit to leave it unchanged
  */
 description?: (string | null)
 /**
- * Event types to deliver. One or more of: email.delivered, email.bounced, email.complained, email.suppressed, email.opened, email.clicked
+ * Replace the delivered event types; omit to leave them unchanged
  * 
  * @minItems 1
  */
@@ -83164,13 +84885,34 @@ enabled_events?: [("email.delivered" | "email.bounced" | "email.complained" | "e
 }
 
 export interface MailWebhookUpdateOutput {
+/**
+ * Webhook endpoint id
+ */
 id: string
+/**
+ * HTTPS URL that signed events are POSTed to
+ */
 url: string
+/**
+ * False if delivery is switched off — the endpoint is kept but nothing is sent to it
+ */
 enabled: boolean
+/**
+ * When the endpoint was registered (ISO 8601 UTC)
+ */
 created_at: string
+/**
+ * When the endpoint was last changed (ISO 8601 UTC)
+ */
 updated_at: string
+/**
+ * Human label for the endpoint; null if none was given
+ */
 description: (string | null)
-enabled_events: string[]
+/**
+ * Event types this endpoint receives; anything else is not delivered to it
+ */
+enabled_events: ("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked")[]
 }
 
 export interface ObserveAlertsCreateInput {