@lessly/sdk-app 82.0.0 → 83.0.0

package/dist/_types/gen/types.gen.d.ts

@@ -80186,45 +80186,93 @@ export interface DeploymentVolumeResizeOutput {
 }
 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;
 }
 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;
 }[];
 export interface MailAudienceCreateInput {
@@ -80234,9 +80282,21 @@ export interface MailAudienceCreateInput {
     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;
 }
 export interface MailAudienceDeleteInput {
@@ -80246,6 +80306,9 @@ export interface MailAudienceDeleteInput {
     id: string;
 }
 export interface MailAudienceDeleteOutput {
+    /**
+     * True once the audience and its contacts are gone
+     */
     deleted: boolean;
 }
 export interface MailAudienceGetInput {
@@ -80255,17 +80318,41 @@ export interface MailAudienceGetInput {
     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;
 }
 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;
 }[];
 export interface MailAudienceUpdateInput {
@@ -80279,219 +80366,708 @@ export interface MailAudienceUpdateInput {
     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;
 }
 export interface MailContactCreateInput {
@@ -80515,12 +81091,30 @@ export interface MailContactCreateInput {
     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;
 }
 export interface MailContactDeleteInput {
@@ -80534,6 +81128,9 @@ export interface MailContactDeleteInput {
     audience_id: string;
 }
 export interface MailContactDeleteOutput {
+    /**
+     * True once the contact is gone
+     */
     deleted: boolean;
 }
 export interface MailContactGetInput {
@@ -80547,12 +81144,30 @@ export interface MailContactGetInput {
     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;
 }
 export interface MailContactListInput {
@@ -80561,7 +81176,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;
     /**
@@ -80574,15 +81189,39 @@ export interface MailContactListInput {
     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);
 }
 export interface MailContactUpdateInput {
@@ -80606,269 +81245,794 @@ export interface MailContactUpdateInput {
     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;
 }
 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;
+        /**
+         * 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);
 }
 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);
 }
 export interface MailEmailSendInput {
@@ -80885,38 +82049,41 @@ export interface MailEmailSendInput {
      */
     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;
     /**
@@ -80932,23 +82099,26 @@ export interface MailEmailSendInput {
          */
         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: {
         /**
@@ -80964,38 +82134,41 @@ export interface MailEmailSendBatchInput {
          */
         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;
         /**
@@ -81011,139 +82184,304 @@ export interface MailEmailSendBatchInput {
              */
             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;
 }
 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;
 }
 export interface MailTemplateCreateInput {
@@ -84971,18 +86309,57 @@ export interface MailTemplateCreateInput {
     ];
 }
 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;
     }[];
 }
@@ -84993,6 +86370,9 @@ export interface MailTemplateDeleteInput {
     id: string;
 }
 export interface MailTemplateDeleteOutput {
+    /**
+     * True once the template is gone
+     */
     deleted: boolean;
 }
 export interface MailTemplateGetInput {
@@ -85002,40 +86382,127 @@ export interface MailTemplateGetInput {
     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;
     }[];
 }
 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;
     }[];
 }[];
@@ -85046,18 +86513,57 @@ export interface MailTemplatePublishInput {
     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;
     }[];
 }
@@ -85066,11 +86572,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?: [] | [
@@ -88876,100 +90396,256 @@ export interface MailTemplateUpdateInput {
     ];
 }
 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;
     }[];
 }
 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
      */
     enabled_events: [("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked"), ...(("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked"))[]];
 }
 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);
 }[];
 export interface MailWebhookGetInput {
@@ -88979,24 +90655,69 @@ export interface MailWebhookGetInput {
     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 {
     /**
@@ -89004,32 +90725,53 @@ 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
      */
     enabled_events?: [("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked"), ...(("email.delivered" | "email.bounced" | "email.complained" | "email.suppressed" | "email.opened" | "email.clicked"))[]];
 }
 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 {
     /**