@gpt-platform/client 0.11.0 → 0.11.2

package/dist/namespaces/email.d.ts

@@ -1,89 +1,213 @@
 import type { EmailOutboundEmail, EmailMarketingSenderProfile, EmailTrackingEvent, EmailUnsubscriber, EmailRecipient, EmailInclusion, EmailInboundAddress, EmailInboundEmail } from "../_internal/types.gen";
-/** Daily send quota record for a workspace. */
-export interface EmailSendLimit {
-    id: string;
-    date: string;
-    workspace_id: string;
-    limit_with_unsubscribe: number;
-    limit_without_unsubscribe: number;
-    sent_with_unsubscribe: number;
-    sent_without_unsubscribe: number;
-    remaining_with_unsubscribe?: number;
-    remaining_without_unsubscribe?: number;
-    inserted_at: string;
-    updated_at: string;
+/** Context reference type — links an email to a domain entity for history tracking. */
+export type ContextRefType = "custom" | "deal" | "session" | "ticket";
+/** Inclusion content category. */
+export type InclusionType = "chart" | "custom" | "goal" | "metric" | "resource" | "supplement";
+/** Recipient role on an outbound email. */
+export type RecipientType = "to" | "cc" | "bcc";
+/** Inbound email routing target. */
+export type InboundRoutingTarget = "extraction" | "agent" | "invoices" | "crm";
+/**
+ * A file attachment on an outbound email.
+ *
+ * Upload the file to platform storage first, then reference its
+ * `storage_key` here. Maximum 10 attachments per email.
+ */
+export interface EmailAttachment {
+    /** Platform storage key returned by the upload API. */
+    storage_key: string;
+    /** Display filename shown to the recipient (e.g. `"report.pdf"`). */
+    filename: string;
+    /** MIME type (e.g. `"application/pdf"`, `"image/png"`). */
+    content_type: string;
 }
-/** Attributes accepted when creating an outbound email draft. */
-export type CreateOutboundEmailAttributes = {
-    workspace_id: string;
+/**
+ * Attributes accepted when creating an outbound email draft.
+ *
+ * `workspace_id` is resolved from the authenticated actor's workspace
+ * context — do not pass it explicitly.
+ */
+export interface CreateOutboundEmailAttributes {
+    /** Email subject line. Required. */
     subject: string;
+    /** HTML body content. */
     body_html?: string;
+    /** Plain-text body (fallback for non-HTML clients). */
     body_text?: string;
+    /** Sender profile to use. Falls back to workspace default if omitted. */
     sender_profile_id?: string;
+    /** CRM contact reference for tracking. */
     contact_ref_id?: string;
+    /** ID of the linked domain entity (deal, session, ticket). */
     context_ref_id?: string;
-    context_ref_type?: "custom" | "deal" | "session" | "ticket";
+    /** Type of the linked domain entity. */
+    context_ref_type?: ContextRefType;
+    /** Append a CAN-SPAM unsubscribe link to the email footer. */
     include_unsubscribe_link?: boolean;
-    attachments?: Array<Record<string, unknown>>;
-    [key: string]: unknown;
-};
-/** Attributes accepted when updating an outbound email (PATCH semantics). */
-export type UpdateOutboundEmailAttributes = {
+    /** File attachments (max 10). Upload files first, then reference storage keys. */
+    attachments?: EmailAttachment[];
+}
+/**
+ * Attributes accepted when updating an outbound email (PATCH semantics).
+ *
+ * Only emails in `draft` status can be updated.
+ */
+export interface UpdateOutboundEmailAttributes {
+    /** Updated subject line. */
     subject?: string;
+    /** Updated HTML body. */
     body_html?: string;
+    /** Updated plain-text body. */
     body_text?: string;
-    [key: string]: unknown;
-};
-/** Attributes accepted when creating a sender profile. */
-export type CreateEmailSenderProfileAttributes = {
-    workspace_id: string;
+    /** Change the sender profile. */
+    sender_profile_id?: string;
+    /** Toggle unsubscribe link. */
+    include_unsubscribe_link?: boolean;
+    /** Replace the attachment list. */
+    attachments?: EmailAttachment[];
+}
+/**
+ * Attributes accepted when creating a sender profile.
+ *
+ * `workspace_id` is resolved from the authenticated actor's workspace
+ * context — do not pass it explicitly.
+ */
+export interface CreateSenderProfileAttributes {
+    /** Sender email address. Must be unique per workspace. */
     email: string;
+    /** Display name shown in the From header. */
     name: string;
+    /** Physical mailing address (CAN-SPAM compliance). */
     address?: string;
+    /** Company name for the email footer. */
     company?: string;
+    /** Set as the workspace default sender profile on creation. */
     is_default?: boolean;
+    /** Contact phone number. */
     phone?: string;
+    /** HTML signature block appended to outgoing emails. */
     signature?: string;
-    [key: string]: unknown;
-};
-/** Attributes accepted when updating a sender profile (PATCH semantics). */
-export type UpdateEmailSenderProfileAttributes = {
+}
+/**
+ * Attributes accepted when updating a sender profile (PATCH semantics).
+ */
+export interface UpdateSenderProfileAttributes {
+    /** Updated display name. */
     name?: string;
+    /** Updated mailing address. */
     address?: string;
+    /** Updated company name. */
     company?: string;
+    /** DKIM selector override (advanced — leave blank unless you manage DNS manually). */
     dkim_selector?: string;
+    /** Change default status. */
     is_default?: boolean;
+    /** Updated phone number. */
     phone?: string;
+    /** Updated HTML signature. */
     signature?: string;
-    [key: string]: unknown;
-};
+}
+/** Attributes accepted when adding a recipient to an outbound email. */
+export interface CreateRecipientAttributes {
+    /** ID of the outbound email to attach this recipient to. */
+    outbound_email_id: string;
+    /** Recipient email address. */
+    email: string;
+    /** Recipient display name. */
+    name?: string;
+    /** Role: primary (`to`), carbon copy (`cc`), or blind copy (`bcc`). Defaults to `to`. */
+    recipient_type?: RecipientType;
+}
+/** Attributes accepted when attaching a structured data inclusion to a draft email. */
+export interface CreateInclusionAttributes {
+    /** ID of the outbound email to attach this inclusion to. */
+    outbound_email_id: string;
+    /** Content category (goal, metric, chart, etc.). */
+    inclusion_type: InclusionType;
+    /** Platform object ID referenced by this inclusion. */
+    ref_id?: string;
+    /** Display title rendered in the email body. */
+    title?: string;
+    /** Structured payload (shape depends on `inclusion_type`). */
+    data?: Record<string, unknown>;
+    /** Ordering position within the email body (0-indexed). */
+    position?: number;
+}
+/** Attributes accepted when updating an inclusion (PATCH semantics). */
+export interface UpdateInclusionAttributes {
+    /** Updated display title. */
+    title?: string;
+    /** Pre-rendered HTML for this inclusion block. */
+    rendered_html?: string;
+    /** Updated structured payload. */
+    data?: Record<string, unknown>;
+    /** Updated ordering position. */
+    position?: number;
+}
+/**
+ * Attributes accepted when creating an inbound address.
+ *
+ * Unlike outbound resources, `workspace_id` is an explicit argument here.
+ */
+export interface CreateInboundAddressAttributes {
+    /** Workspace to create the address in. */
+    workspace_id: string;
+    /** Human-readable label for this address. */
+    name: string;
+    /** Where received emails are routed for processing. */
+    routing_target: InboundRoutingTarget;
+    /** Routing-target-specific configuration. */
+    handler_config?: Record<string, unknown>;
+    /** Maximum attachment size in MB (1–100, default 25). */
+    max_attachment_size_mb?: number;
+    /** Restrict accepted MIME types. `null` allows all types. */
+    allowed_mime_types?: string[] | null;
+    /** Maximum emails accepted per day (1–10,000, default 100). */
+    daily_receive_limit?: number;
+}
 /** Attributes accepted when updating an inbound address (PATCH semantics). */
-export type UpdateInboundAddressAttributes = {
-    label?: string;
+export interface UpdateInboundAddressAttributes {
+    /** Updated human-readable label. */
+    name?: string;
+    /** Change the routing target. */
+    routing_target?: InboundRoutingTarget;
+    /** Updated routing configuration. */
     handler_config?: Record<string, unknown>;
-    [key: string]: unknown;
-};
-/** @public Parameters for AI email composition. */
+    /** Updated max attachment size in MB. */
+    max_attachment_size_mb?: number;
+    /** Updated MIME type restrictions. */
+    allowed_mime_types?: string[] | null;
+    /** Updated daily receive limit. */
+    daily_receive_limit?: number;
+}
+/**
+ * Parameters for AI-assisted email composition.
+ *
+ * The platform LLM generates a personalised subject and HTML body from your
+ * prompt and any structured context you provide. The result is saved as a
+ * draft for review before sending.
+ *
+ * `workspace_id` is resolved from the authenticated actor — do not pass it.
+ */
 export interface ComposeWithAiAttributes {
     /** Email addresses of primary recipients. */
     to: string[];
-    /** AI drafting instructions (e.g., "Write a warm follow-up after our nutrition session"). */
+    /** AI drafting instructions (e.g. "Write a warm follow-up after our nutrition session"). */
     prompt: string;
-    /** Workspace context for multi-tenancy routing. */
-    workspace_id: string;
     /** Structured context data passed to the AI (session notes, goals, health metrics, etc.). */
     context?: Record<string, unknown>;
     /** Sender profile ID — uses workspace default if omitted. */
     sender_profile_id?: string;
-    /** Optional CRM contact reference. */
+    /** CRM contact reference. */
     contact_ref_id?: string;
-    /** Attach a context object (deal, session, ticket) to the email for history tracking. */
-    context_ref_type?: "session" | "deal" | "ticket" | "custom";
+    /** Link the composed email to a domain entity. */
+    context_ref_type?: ContextRefType;
+    /** ID of the linked domain entity. */
     context_ref_id?: string;
     /** Include a CAN-SPAM unsubscribe link in the email footer. */
     include_unsubscribe_link?: boolean;
 }
-/** @public Result of a stateless MJML compilation. */
+/** Result of a stateless MJML compilation. */
 export interface MjmlCompileResult {
     /** Compiled HTML output. Empty string if errors present. */
     html: string;
@@ -92,7 +216,7 @@ export interface MjmlCompileResult {
     /** MJML parser errors. */
     errors: string[];
 }
-/** @public A single entry in a template's variable schema. */
+/** A single entry in a template's variable schema. */
 export interface TemplateVariableSchema {
     /** Variable name (matches {{variable}} syntax in MJML). */
     name: string;
@@ -101,7 +225,7 @@ export interface TemplateVariableSchema {
     /** Default value shown in builder UI when no override is provided. */
     default: string;
 }
-/** @public Immutable snapshot of a template at a specific publish point. */
+/** Immutable snapshot of a template at a specific publish point. */
 export interface TemplateVersion {
     id: string;
     template_id: string;
@@ -126,9 +250,27 @@ import { RequestBuilder } from "../request-builder";
  * ```typescript
  * const client = new GptClient({ apiKey: 'sk_app_...' });
  *
- * // AI-draft a post-session follow-up for a patient
- * const email = await client.email.outboundEmails.composeWithAi({
- *   workspace_id: 'ws_abc123',
+ * // Create a draft
+ * const draft = await client.email.outboundEmails.create({
+ *   subject: 'Your weekly nutrition update',
+ *   body_html: '<p>Hello!</p>',
+ *   sender_profile_id: 'sp_abc123',
+ * });
+ *
+ * // Add recipients
+ * await client.email.recipients.create({
+ *   outbound_email_id: draft.id,
+ *   email: 'patient@example.com',
+ *   name: 'Jane Doe',
+ * });
+ *
+ * // Send
+ * await client.email.outboundEmails.send(draft.id);
+ * ```
+ *
+ * @example AI-assisted composition
+ * ```typescript
+ * const draft = await client.email.outboundEmails.composeWithAi({
  *   to: ['patient@example.com'],
  *   prompt: 'Write a warm follow-up after a nutrition session',
  *   context: {
@@ -139,7 +281,7 @@ import { RequestBuilder } from "../request-builder";
  * });
  *
  * // Review the draft, then send
- * await client.email.outboundEmails.send(email.id);
+ * await client.email.outboundEmails.send(draft.id);
  * ```
  */
 export declare function createEmailNamespace(rb: RequestBuilder): {
@@ -147,51 +289,55 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
      * Outbound Emails — individual email composition and delivery.
      */
     outboundEmails: {
-        /** Get a single outbound email by ID. */
+        /**
+         * Get a single outbound email by ID.
+         *
+         * @param id - The unique identifier of the outbound email.
+         * @param options - Optional request-level overrides.
+         * @returns The requested {@link EmailOutboundEmail}.
+         */
         get: (id: string, options?: RequestOptions) => Promise<EmailOutboundEmail>;
         /**
          * Create a new outbound email draft.
          *
-         * Creates a draft in `draft` status for review before sending. Populate
-         * all required fields (recipients, subject, body) then call `send()` to
-         * trigger immediate delivery or `schedule()` for future delivery.
+         * Creates a draft in `draft` status. Add recipients via
+         * `client.email.recipients.create()`, then call `send()` for immediate
+         * delivery or `schedule()` for future delivery.
+         *
+         * Workspace is resolved from the authenticated actor — do not pass
+         * `workspace_id`.
          *
-         * @param attributes - Key/value map of email attributes. Common fields:
-         *   `workspace_id`, `subject`, `body_html`, `body_text`, `sender_profile_id`.
+         * @param attributes - Email draft attributes. Only `subject` is required.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to the newly created {@link EmailOutboundEmail} draft.
+         * @returns The newly created {@link EmailOutboundEmail} draft.
          *
          * @example
          * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
          * const draft = await client.email.outboundEmails.create({
-         *   workspace_id: 'ws_abc123',
          *   subject: 'Your weekly update',
          *   body_html: '<p>Hello!</p>',
          *   sender_profile_id: 'sp_noreply',
          * });
-         * await client.email.outboundEmails.send(draft.id);
          * ```
          */
         create: (attributes: CreateOutboundEmailAttributes, options?: RequestOptions) => Promise<EmailOutboundEmail>;
         /**
-         * AI-draft an email from a prompt and structured context map.
+         * AI-draft an email from a prompt and structured context.
          *
          * The platform LLM generates a personalised subject and body from your
          * prompt and any context data you provide (session notes, goals, health
-         * metrics, etc.). The email is saved as a draft for your review before
-         * you call `send()`.
+         * metrics, etc.). The email is saved as a draft — review it, then call
+         * `send()`.
          *
-         * @param attributes - See {@link ComposeWithAiAttributes} for all fields.
-         *   Required: `to`, `prompt`, `workspace_id`.
+         * @param attributes - AI composition parameters. `to` and `prompt` are required.
+         * @param options - Optional request-level overrides.
+         * @returns The AI-generated {@link EmailOutboundEmail} draft.
          *
          * @example
          * ```typescript
          * const draft = await client.email.outboundEmails.composeWithAi({
          *   to: ['alice@example.com'],
          *   prompt: 'Write a warm post-session follow-up for a nutrition client',
-         *   workspace_id: 'ws_abc123',
          *   context: { session_notes: 'Discussed protein goals...', protein_target: 120 },
          *   sender_profile_id: 'sp_xyz',
          *   include_unsubscribe_link: true,
@@ -201,23 +347,20 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
          */
         composeWithAi: (attributes: ComposeWithAiAttributes, options?: RequestOptions) => Promise<EmailOutboundEmail>;
         /**
-         * Update a draft outbound email's attributes.
+         * Update a draft outbound email (PATCH semantics).
          *
-         * Only the fields present in `attributes` are changed (PATCH semantics).
-         * An email can only be updated while in `draft` or `scheduled` status.
+         * Only emails in `draft` status can be updated.
          *
-         * @param id - The unique identifier of the outbound email to update.
-         * @param attributes - Key/value map of attributes to change (e.g.
-         *   `subject`, `body_html`, `body_text`, `sender_profile_id`).
+         * @param id - The outbound email ID.
+         * @param attributes - Fields to update.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to the updated {@link EmailOutboundEmail}.
+         * @returns The updated {@link EmailOutboundEmail}.
          *
          * @example
          * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
          * const updated = await client.email.outboundEmails.update('oe_abc123', {
          *   subject: 'Updated subject line',
+         *   body_html: '<p>Revised content</p>',
          * });
          * ```
          */
@@ -225,47 +368,73 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
         /**
          * Delete a draft outbound email.
          *
-         * Only emails in `draft` status can be deleted. Emails in `sent` or
-         * `failed` status are immutable — archive them via your application logic.
+         * Only emails in `draft` status can be deleted. Sent emails are immutable.
          *
-         * @param id - The unique identifier of the outbound email to delete.
+         * @param id - The outbound email ID.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to `true` on successful deletion.
-         *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
-         * await client.email.outboundEmails.delete('oe_abc123');
-         * ```
+         * @returns `true` on successful deletion.
          */
         delete: (id: string, options?: RequestOptions) => Promise<true>;
         /**
-         * Send a draft email immediately via the workspace's connected Gmail or Outlook.
+         * Send a draft email immediately via the workspace's connected account.
          *
-         * Delivery is asynchronous — returns the email in `ready` status.
-         * Poll for `sent` status or subscribe to the `OutboundEmailSent` WebSocket event.
+         * Transitions the email to `ready` status. Delivery is asynchronous —
+         * poll for `sent` status or subscribe to the `OutboundEmailSent`
+         * WebSocket event.
          *
-         * @param id - ID of the OutboundEmail to send
+         * Requires a `sender_profile_id` to be set on the email and at least
+         * one recipient.
+         *
+         * @param id - The outbound email ID.
+         * @param options - Optional request-level overrides.
+         * @returns The email in `ready` status.
          */
         send: (id: string, options?: RequestOptions) => Promise<EmailOutboundEmail>;
         /**
          * Schedule a draft for future delivery.
          *
-         * @param id - ID of the OutboundEmail
-         * @param attributes.scheduled_for - ISO 8601 datetime string
+         * @param id - The outbound email ID.
+         * @param attributes - Must include `scheduled_for` as an ISO 8601 datetime.
+         * @param options - Optional request-level overrides.
+         * @returns The email in `scheduled` status.
+         *
+         * @example
+         * ```typescript
+         * await client.email.outboundEmails.schedule('oe_abc123', {
+         *   scheduled_for: '2026-04-01T09:00:00Z',
+         * });
+         * ```
          */
         schedule: (id: string, attributes: {
             scheduled_for: string;
         }, options?: RequestOptions) => Promise<EmailOutboundEmail>;
-        /** Cancel a previously scheduled email (returns it to draft status). */
+        /**
+         * Cancel a previously scheduled email (returns it to `draft` status).
+         *
+         * @param id - The outbound email ID.
+         * @param options - Optional request-level overrides.
+         * @returns The email back in `draft` status.
+         */
         cancelSchedule: (id: string, options?: RequestOptions) => Promise<EmailOutboundEmail>;
-        /** List all outbound emails in a workspace. */
+        /**
+         * List all outbound emails in a workspace.
+         *
+         * @param workspaceId - The workspace ID.
+         * @param options - Pagination (`page`, `pageSize`) and request-level overrides.
+         * @returns An array of {@link EmailOutboundEmail} records.
+         */
         listByWorkspace: (workspaceId: string, options?: {
             page?: number;
             pageSize?: number;
         } & RequestOptions) => Promise<EmailOutboundEmail[]>;
-        /** Get all emails sent to a specific contact within a workspace. */
+        /**
+         * List emails sent to a specific contact within a workspace.
+         *
+         * @param workspaceId - The workspace ID.
+         * @param contactRefId - The CRM contact reference ID.
+         * @param options - Pagination and request-level overrides.
+         * @returns An array of {@link EmailOutboundEmail} records for the contact.
+         */
         listByContact: (workspaceId: string, contactRefId: string, options?: {
             page?: number;
             pageSize?: number;
@@ -273,29 +442,34 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
     };
     /**
      * Sender Profiles — verified from-address identities for outgoing email.
+     *
+     * A sender profile defines the `From` name and email address used when
+     * sending. Before a profile can be used, its domain must be verified via
+     * DNS records (SPF, DKIM, DMARC). Call `validateDns()` after publishing
+     * DNS records.
      */
     senderProfiles: {
-        /** Get a sender profile by ID. */
+        /**
+         * Get a sender profile by ID.
+         *
+         * @param id - The sender profile ID.
+         * @param options - Optional request-level overrides.
+         * @returns The requested {@link EmailMarketingSenderProfile}.
+         */
         get: (id: string, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
         /**
-         * Create a new sender profile (from-address identity).
+         * Create a new sender profile.
          *
-         * A sender profile defines the `From` name and email address used when
-         * sending emails. Before a profile can be used, its domain must be
-         * verified via DNS records (SPF, DKIM, DMARC). Call `validateDns()` to
-         * trigger verification after publishing DNS records.
+         * Workspace is resolved from the authenticated actor — do not pass
+         * `workspace_id`.
          *
-         * @param attributes - Key/value map of profile attributes. Required:
-         *   `workspace_id`, `email`, `name`. Optional: `address`, `company`, `phone`, `signature`.
+         * @param attributes - Profile attributes. `email` and `name` are required.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to the newly created {@link EmailMarketingSenderProfile}.
+         * @returns The newly created {@link EmailMarketingSenderProfile}.
          *
          * @example
          * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
          * const profile = await client.email.senderProfiles.create({
-         *   workspace_id: 'ws_abc123',
          *   email: 'hello@acme.com',
          *   name: 'Acme Team',
          * });
@@ -303,228 +477,313 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
          * await client.email.senderProfiles.validateDns(profile.id);
          * ```
          */
-        create: (attributes: CreateEmailSenderProfileAttributes, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
+        create: (attributes: CreateSenderProfileAttributes, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
         /**
-         * Update a sender profile's attributes.
+         * Update a sender profile (PATCH semantics).
          *
-         * Only the fields present in `attributes` are changed (PATCH semantics).
-         * After updating domain-related fields, re-verify DNS
-         * with `validateDns()` to confirm deliverability is not impacted.
+         * After changing domain-related fields, re-verify DNS with
+         * `validateDns()`.
          *
-         * @param id - The unique identifier of the sender profile to update.
-         * @param attributes - Key/value map of attributes to change (e.g.
-         *   `name`, `company`, `signature`).
+         * @param id - The sender profile ID.
+         * @param attributes - Fields to update.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to the updated {@link EmailMarketingSenderProfile}.
-         *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
-         * const profile = await client.email.senderProfiles.update('sp_abc123', {
-         *   name: 'Acme Support',
-         * });
-         * ```
+         * @returns The updated {@link EmailMarketingSenderProfile}.
          */
-        update: (id: string, attributes: UpdateEmailSenderProfileAttributes, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
+        update: (id: string, attributes: UpdateSenderProfileAttributes, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
         /**
          * Delete a sender profile.
          *
-         * Deleting a sender profile that is in use by active campaigns or drafts
-         * will require those campaigns to select a new profile before sending.
+         * Emails and campaigns referencing this profile will need a replacement
+         * before sending.
          *
-         * @param id - The unique identifier of the sender profile to delete.
+         * @param id - The sender profile ID.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to `true` on successful deletion.
+         * @returns `true` on successful deletion.
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Trigger DNS validation (verifies SPF/DKIM/DMARC records).
          *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * Validation runs asynchronously via a background worker. Poll the
+         * profile's `spf_valid`, `dkim_valid`, and `dmarc_valid` fields for
+         * results.
          *
-         * await client.email.senderProfiles.delete('sp_abc123');
-         * ```
+         * @param id - The sender profile ID.
+         * @param options - Optional request-level overrides.
+         * @returns The sender profile (DNS status may still be pending).
          */
-        delete: (id: string, options?: RequestOptions) => Promise<true>;
-        /** Trigger DNS validation for a sender profile (verifies SPF/DKIM). */
         validateDns: (id: string, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
         /**
          * Set a sender profile as the workspace default.
          *
-         * The default sender profile is used automatically when no
-         * `sender_profile_id` is specified on an outbound email or campaign.
-         * Only one profile can be the default per workspace at a time —
+         * The default profile is used automatically when no `sender_profile_id`
+         * is specified on an outbound email. Only one default per workspace —
          * calling this replaces any previous default.
          *
-         * @param id - The unique identifier of the sender profile to set as default.
+         * @param id - The sender profile ID.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to the updated {@link EmailMarketingSenderProfile}
-         *   with `is_default` set to `true`.
-         *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
-         * await client.email.senderProfiles.setDefault('sp_abc123');
-         * console.log('Default sender profile updated');
-         * ```
+         * @returns The profile with `is_default` set to `true`.
          */
         setDefault: (id: string, options?: RequestOptions) => Promise<EmailMarketingSenderProfile>;
-        /** List all sender profiles for a workspace. */
+        /**
+         * List all sender profiles in a workspace.
+         *
+         * @param workspaceId - The workspace ID.
+         * @param options - Pagination and request-level overrides.
+         * @returns An array of {@link EmailMarketingSenderProfile} records.
+         */
         listByWorkspace: (workspaceId: string, options?: {
             page?: number;
             pageSize?: number;
         } & RequestOptions) => Promise<EmailMarketingSenderProfile[]>;
     };
     /**
-     * Recipients — to/cc/bcc recipients on an outbound email.
+     * Recipients — to/cc/bcc addresses on an outbound email.
+     *
+     * Add recipients after creating a draft. At least one `to` recipient is
+     * required before sending.
      */
     recipients: {
-        /** Get a recipient by ID. */
+        /**
+         * Get a recipient by ID.
+         *
+         * @param id - The recipient record ID.
+         * @param options - Optional request-level overrides.
+         * @returns The requested {@link EmailRecipient}.
+         */
         get: (id: string, options?: RequestOptions) => Promise<EmailRecipient>;
-        /** Add a recipient to an outbound email. */
-        create: (attributes: {
-            outbound_email_id: string;
-            email: string;
-            name?: string;
-            recipient_type?: "to" | "cc" | "bcc";
-        }, options?: RequestOptions) => Promise<EmailRecipient>;
-        /** Remove a recipient from an outbound email. */
+        /**
+         * Add a recipient to an outbound email.
+         *
+         * @param attributes - Recipient details. `outbound_email_id` and `email` are required.
+         * @param options - Optional request-level overrides.
+         * @returns The newly created {@link EmailRecipient}.
+         *
+         * @example
+         * ```typescript
+         * await client.email.recipients.create({
+         *   outbound_email_id: draft.id,
+         *   email: 'jane@example.com',
+         *   name: 'Jane Doe',
+         *   recipient_type: 'to',
+         * });
+         * ```
+         */
+        create: (attributes: CreateRecipientAttributes, options?: RequestOptions) => Promise<EmailRecipient>;
+        /**
+         * Remove a recipient from an outbound email.
+         *
+         * @param id - The recipient record ID.
+         * @param options - Optional request-level overrides.
+         * @returns `true` on successful deletion.
+         */
         delete: (id: string, options?: RequestOptions) => Promise<true>;
-        /** List all recipients for an outbound email. */
+        /**
+         * List all recipients for an outbound email.
+         *
+         * @param outboundEmailId - The outbound email ID.
+         * @param options - Optional request-level overrides.
+         * @returns An array of {@link EmailRecipient} records.
+         */
         listByEmail: (outboundEmailId: string, options?: RequestOptions) => Promise<EmailRecipient[]>;
     };
     /**
-     * Inclusions — structured data attachments (goals, charts, metrics) embedded in email bodies.
+     * Inclusions — structured data (goals, charts, metrics) embedded in email bodies.
+     *
+     * Attach platform objects to a draft email. Inclusions are rendered into
+     * the email body before sending.
      */
     inclusions: {
-        /** Get an inclusion by ID. */
+        /**
+         * Get an inclusion by ID.
+         *
+         * @param id - The inclusion ID.
+         * @param options - Optional request-level overrides.
+         * @returns The requested {@link EmailInclusion}.
+         */
         get: (id: string, options?: RequestOptions) => Promise<EmailInclusion>;
-        /** Attach a structured data inclusion to a draft email. */
-        create: (attributes: {
-            outbound_email_id: string;
-            inclusion_type: "goal" | "metric" | "chart" | "resource" | "supplement" | "custom";
-            ref_id?: string;
-            title?: string;
-            data?: Record<string, unknown>;
-            position?: number;
-        }, options?: RequestOptions) => Promise<EmailInclusion>;
-        /** Update an inclusion's display data or position. */
-        update: (id: string, attributes: {
-            title?: string;
-            rendered_html?: string;
-            data?: Record<string, unknown>;
-            position?: number;
-        }, options?: RequestOptions) => Promise<EmailInclusion>;
-        /** Remove an inclusion from a draft email. */
+        /**
+         * Attach a structured data inclusion to a draft email.
+         *
+         * @param attributes - Inclusion details. `outbound_email_id` and `inclusion_type` are required.
+         * @param options - Optional request-level overrides.
+         * @returns The newly created {@link EmailInclusion}.
+         *
+         * @example
+         * ```typescript
+         * await client.email.inclusions.create({
+         *   outbound_email_id: draft.id,
+         *   inclusion_type: 'goal',
+         *   title: 'Weekly protein target',
+         *   data: { target: 120, unit: 'grams', status: 'active' },
+         * });
+         * ```
+         */
+        create: (attributes: CreateInclusionAttributes, options?: RequestOptions) => Promise<EmailInclusion>;
+        /**
+         * Update an inclusion (PATCH semantics).
+         *
+         * @param id - The inclusion ID.
+         * @param attributes - Fields to update.
+         * @param options - Optional request-level overrides.
+         * @returns The updated {@link EmailInclusion}.
+         */
+        update: (id: string, attributes: UpdateInclusionAttributes, options?: RequestOptions) => Promise<EmailInclusion>;
+        /**
+         * Remove an inclusion from a draft email.
+         *
+         * @param id - The inclusion ID.
+         * @param options - Optional request-level overrides.
+         * @returns `true` on successful deletion.
+         */
         delete: (id: string, options?: RequestOptions) => Promise<true>;
-        /** List all inclusions attached to an outbound email. */
+        /**
+         * List all inclusions attached to an outbound email.
+         *
+         * @param outboundEmailId - The outbound email ID.
+         * @param options - Optional request-level overrides.
+         * @returns An array of {@link EmailInclusion} records.
+         */
         listByEmail: (outboundEmailId: string, options?: RequestOptions) => Promise<EmailInclusion[]>;
     };
     /**
      * Tracking Events — open/click/bounce event history. Read-only.
      */
     trackingEvents: {
-        /** Get a tracking event by ID. */
+        /**
+         * Get a tracking event by ID.
+         *
+         * @param id - The tracking event ID.
+         * @param options - Optional request-level overrides.
+         * @returns The requested {@link EmailTrackingEvent}.
+         */
         get: (id: string, options?: RequestOptions) => Promise<EmailTrackingEvent>;
-        /** List all tracking events for a workspace. */
+        /**
+         * List all tracking events in a workspace.
+         *
+         * @param workspaceId - The workspace ID.
+         * @param options - Pagination and request-level overrides.
+         * @returns An array of {@link EmailTrackingEvent} records.
+         */
         listByWorkspace: (workspaceId: string, options?: {
             page?: number;
             pageSize?: number;
         } & RequestOptions) => Promise<EmailTrackingEvent[]>;
     };
     /**
-     * Unsubscribers — CAN-SPAM global unsubscribe registry.
+     * Unsubscribers — CAN-SPAM global unsubscribe registry. Read-only.
      */
     unsubscribers: {
-        /** Get an unsubscribe record by ID. */
-        get: (id: string, options?: RequestOptions) => Promise<EmailUnsubscriber>;
-        /** List all unsubscribers for a workspace. */
-        listByWorkspace: (workspaceId: string, options?: {
-            page?: number;
-            pageSize?: number;
-        } & RequestOptions) => Promise<EmailUnsubscriber[]>;
-    };
-    /**
-     * Send Limits — daily send quota records for outbound email.
-     *
-     * Each workspace has a send limit record per calendar day that tracks
-     * how many emails (with and without unsubscribe links) have been sent.
-     * Use these records to display usage dashboards or enforce ISV-side
-     * throttling before hitting platform hard limits.
-     */
-    sendLimits: {
         /**
-         * Get the send limit record for today in a workspace.
+         * Get an unsubscribe record by ID.
          *
-         * @param workspaceId - The ID of the workspace to query.
+         * @param id - The unsubscriber record ID.
          * @param options - Optional request-level overrides.
-         * @returns A promise that resolves to today's {@link EmailSendLimit} record.
-         *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
-         * const limit = await client.email.sendLimits.get('ws_abc123');
-         * console.log(limit.attributes.sent_with_unsubscribe, limit.attributes.limit_with_unsubscribe);
-         * ```
+         * @returns The requested {@link EmailUnsubscriber}.
          */
-        get: (workspaceId: string, options?: RequestOptions) => Promise<EmailSendLimit>;
+        get: (id: string, options?: RequestOptions) => Promise<EmailUnsubscriber>;
         /**
-         * List send limit records for a workspace (historical).
-         *
-         * Returns one record per day that emails were sent. Records are ordered
-         * by date descending. Use for displaying usage history or charting
-         * daily send volume over time.
+         * List all unsubscribers in a workspace.
          *
-         * @param workspaceId - The ID of the workspace to query.
-         * @param options - Optional pagination controls (`page`, `pageSize`) and
-         *   request-level overrides.
-         * @returns A promise that resolves to an array of {@link EmailSendLimit} records.
-         *
-         * @example
-         * ```typescript
-         * const client = new GptClient({ apiKey: 'sk_app_...' });
-         *
-         * const history = await client.email.sendLimits.listByWorkspace('ws_abc123', { pageSize: 30 });
-         * console.log(`Last 30 days of send history: ${history.length} records`);
-         * ```
+         * @param workspaceId - The workspace ID.
+         * @param options - Pagination and request-level overrides.
+         * @returns An array of {@link EmailUnsubscriber} records.
          */
         listByWorkspace: (workspaceId: string, options?: {
             page?: number;
             pageSize?: number;
-        } & RequestOptions) => Promise<EmailSendLimit[]>;
+        } & RequestOptions) => Promise<EmailUnsubscriber[]>;
     };
     /**
      * Inbound Addresses — workspace-scoped email addresses that receive inbound mail.
      *
-     * Any sender can email `{token}@inbound.gpt.app`. Configure a routing target
-     * (`:extraction`, `:agent`, `:invoices`, `:crm`) to process received emails automatically.
+     * Any sender can email `{token}@inbound.gpt.app`. Configure a routing
+     * target (`:extraction`, `:agent`, `:invoices`, `:crm`) to process
+     * received emails automatically.
      */
     inbound: {
         addresses: {
-            /** Get an inbound address by ID. */
+            /**
+             * Get an inbound address by ID.
+             *
+             * @param id - The inbound address ID.
+             * @param options - Optional request-level overrides.
+             * @returns The requested {@link EmailInboundAddress}.
+             */
             get: (id: string, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** Create a new inbound address. */
-            create: (attributes: {
-                workspace_id: string;
-                name: string;
-                routing_target: "extraction" | "agent" | "invoices" | "crm";
-                handler_config?: Record<string, unknown>;
-                max_attachment_size_mb?: number;
-                allowed_mime_types?: string[] | null;
-                daily_receive_limit?: number;
-            }, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** Update an inbound address. */
+            /**
+             * Create a new inbound address.
+             *
+             * Unlike outbound resources, `workspace_id` is an explicit required
+             * parameter here.
+             *
+             * @param attributes - Address configuration. `workspace_id`, `name`, and
+             *   `routing_target` are required.
+             * @param options - Optional request-level overrides.
+             * @returns The newly created {@link EmailInboundAddress}.
+             *
+             * @example
+             * ```typescript
+             * const addr = await client.email.inbound.addresses.create({
+             *   workspace_id: 'ws_abc123',
+             *   name: 'Invoice intake',
+             *   routing_target: 'invoices',
+             * });
+             * console.log(`Send invoices to: ${addr.token}@inbound.gpt.app`);
+             * ```
+             */
+            create: (attributes: CreateInboundAddressAttributes, options?: RequestOptions) => Promise<EmailInboundAddress>;
+            /**
+             * Update an inbound address (PATCH semantics).
+             *
+             * @param id - The inbound address ID.
+             * @param attributes - Fields to update.
+             * @param options - Optional request-level overrides.
+             * @returns The updated {@link EmailInboundAddress}.
+             */
             update: (id: string, attributes: UpdateInboundAddressAttributes, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** Delete an inbound address. */
+            /**
+             * Delete an inbound address.
+             *
+             * @param id - The inbound address ID.
+             * @param options - Optional request-level overrides.
+             * @returns `true` on successful deletion.
+             */
             delete: (id: string, options?: RequestOptions) => Promise<true>;
-            /** Rotate the inbound address token (invalidates old token). */
+            /**
+             * Rotate the inbound address token (invalidates the old token).
+             *
+             * After rotation, the old `{token}@inbound.gpt.app` address stops
+             * accepting email. Update any senders with the new token.
+             *
+             * @param id - The inbound address ID.
+             * @param options - Optional request-level overrides.
+             * @returns The address with the new token.
+             */
             rotateToken: (id: string, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** Disable an inbound address (stops accepting email). */
+            /**
+             * Disable an inbound address (stops accepting email).
+             *
+             * @param id - The inbound address ID.
+             * @param options - Optional request-level overrides.
+             * @returns The address with `is_active` set to `false`.
+             */
             disable: (id: string, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** Re-enable a disabled inbound address. */
+            /**
+             * Re-enable a disabled inbound address.
+             *
+             * @param id - The inbound address ID.
+             * @param options - Optional request-level overrides.
+             * @returns The address with `is_active` set to `true`.
+             */
             enable: (id: string, options?: RequestOptions) => Promise<EmailInboundAddress>;
-            /** List all inbound addresses in a workspace. */
+            /**
+             * List all inbound addresses in a workspace.
+             *
+             * @param workspaceId - The workspace ID.
+             * @param options - Pagination and request-level overrides.
+             * @returns An array of {@link EmailInboundAddress} records.
+             */
             listByWorkspace: (workspaceId: string, options?: {
                 page?: number;
                 pageSize?: number;
@@ -532,14 +791,32 @@ export declare function createEmailNamespace(rb: RequestBuilder): {
         };
         /** Received — read-only log of received inbound emails. */
         received: {
-            /** Get a received inbound email by ID. */
+            /**
+             * Get a received inbound email by ID.
+             *
+             * @param id - The inbound email ID.
+             * @param options - Optional request-level overrides.
+             * @returns The requested {@link EmailInboundEmail}.
+             */
             get: (id: string, options?: RequestOptions) => Promise<EmailInboundEmail>;
-            /** List received emails by inbound address. */
+            /**
+             * List received emails by inbound address.
+             *
+             * @param addressId - The inbound address ID.
+             * @param options - Pagination and request-level overrides.
+             * @returns An array of {@link EmailInboundEmail} records.
+             */
             listByAddress: (addressId: string, options?: {
                 page?: number;
                 pageSize?: number;
             } & RequestOptions) => Promise<EmailInboundEmail[]>;
-            /** List all received emails in a workspace. */
+            /**
+             * List all received emails in a workspace.
+             *
+             * @param workspaceId - The workspace ID.
+             * @param options - Pagination and request-level overrides.
+             * @returns An array of {@link EmailInboundEmail} records.
+             */
             listByWorkspace: (workspaceId: string, options?: {
                 page?: number;
                 pageSize?: number;