telnyx 7.25.0 → 7.27.0

package/src/resources/credential-connections/credential-connections.ts

@@ -170,6 +170,17 @@ export interface CredentialConnection {
    */
   android_push_credential_id?: string | null;
 
+  /**
+   * Stores the connection preference for generating silent RTP toward the opposite
+   * call leg when comfort-noise packets (CN, payload type 13) are received during
+   * hold. Defaults to false and returns the saved value. Only JSON true and false
+   * are accepted; null and non-boolean values are rejected. This preference is
+   * independent of default_on_hold_comfort_noise_enabled and does not modify that
+   * setting. This API provisions the preference; call-processing behavior is
+   * implemented separately.
+   */
+  bridge_generate_comfort_noise_on_cn?: boolean;
+
   /**
    * Specifies if call cost webhooks should be sent for this connection.
    */
@@ -209,8 +220,8 @@ export interface CredentialConnection {
   encode_contact_header_enabled?: boolean;
 
   /**
-   * Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-   * TLS.
+   * Enable use of SRTP for encryption. Can only be set when the SIP signaling
+   * transport protocol is TLS.
    */
   encrypted_media?: EncryptedMedia | null;
 
@@ -467,8 +478,8 @@ export interface CredentialOutbound {
 export type DtmfType = 'RFC 2833' | 'Inband' | 'SIP INFO';
 
 /**
- * Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
- * TLS.
+ * Enable use of SRTP for encryption. Can only be set when the SIP signaling
+ * transport protocol is TLS.
  */
 export type EncryptedMedia = 'SRTP' | null;
 
@@ -589,6 +600,17 @@ export interface CredentialConnectionCreateParams {
    */
   android_push_credential_id?: string | null;
 
+  /**
+   * Stores the connection preference for generating silent RTP toward the opposite
+   * call leg when comfort-noise packets (CN, payload type 13) are received during
+   * hold. Optional; defaults to false when omitted on creation. Only JSON true and
+   * false are accepted; null and non-boolean values are rejected. This preference is
+   * independent of default_on_hold_comfort_noise_enabled and does not modify that
+   * setting. This API provisions the preference; call-processing behavior is
+   * implemented separately.
+   */
+  bridge_generate_comfort_noise_on_cn?: boolean;
+
   /**
    * Specifies if call cost webhooks should be sent for this connection.
    */
@@ -614,8 +636,8 @@ export interface CredentialConnectionCreateParams {
   encode_contact_header_enabled?: boolean;
 
   /**
-   * Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-   * TLS.
+   * Enable use of SRTP for encryption. Can only be set when the SIP signaling
+   * transport protocol is TLS.
    */
   encrypted_media?: EncryptedMedia | null;
 
@@ -719,6 +741,17 @@ export interface CredentialConnectionUpdateParams {
    */
   android_push_credential_id?: string | null;
 
+  /**
+   * Stores the connection preference for generating silent RTP toward the opposite
+   * call leg when comfort-noise packets (CN, payload type 13) are received during
+   * hold. Optional; omitting this field preserves the saved value. Only JSON true
+   * and false are accepted; null and non-boolean values are rejected. This
+   * preference is independent of default_on_hold_comfort_noise_enabled and does not
+   * modify that setting. This API provisions the preference; call-processing
+   * behavior is implemented separately.
+   */
+  bridge_generate_comfort_noise_on_cn?: boolean;
+
   /**
    * Specifies if call cost webhooks should be sent for this connection.
    */
@@ -756,8 +789,8 @@ export interface CredentialConnectionUpdateParams {
   encode_contact_header_enabled?: boolean;
 
   /**
-   * Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-   * TLS.
+   * Enable use of SRTP for encryption. Can only be set when the SIP signaling
+   * transport protocol is TLS.
    */
   encrypted_media?: EncryptedMedia | null;
 

package/src/resources/dial-metrics.ts

@@ -0,0 +1,185 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { CloudfsCursorPagination, type CloudfsCursorPaginationParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Call information
+ */
+export class DialMetrics extends APIResource {
+  /**
+   * Returns dials-per-second (DPS) metrics for your account's outbound dials made
+   * with the Call Control `Dial` command and TeXML, as time buckets with dial
+   * counts, accepted and rejected dials, average and peak DPS, and the DPS limit in
+   * force.
+   *
+   * The result has one record per region per bucket, ordered by `start_time` and
+   * then `region`, newest first unless `sort=start_time`. Regions are never summed:
+   * the DPS limit is enforced per region, so a cross-region total cannot be compared
+   * with it.
+   *
+   * Only buckets that saw dials are returned. Treat a missing bucket as zero dials.
+   *
+   * Only complete 5-second windows are counted, and a window is counted about 15
+   * seconds after it closes. The newest `granularity=second` record is therefore
+   * your live DPS, about 20 seconds old. Request the last minute or two with
+   * `sort=-start_time`; the first record of each `region` is that region's live rate
+   * (`page[limit]=1` would hide every region but one). If no recent record exists,
+   * the live rate is zero.
+   *
+   * Results are cursor paginated. Follow `meta.next`, or pass `meta.cursors.after`
+   * as `page[after]`, until `meta.next` is absent. No total count is returned.
+   *
+   * This endpoint is in development and can change before general availability.
+   */
+  list(
+    query: DialMetricListParams,
+    options?: RequestOptions,
+  ): PagePromise<DialMetricListResponsesCloudfsCursorPagination, DialMetricListResponse> {
+    return this._client.getAPIList('/dial_metrics', CloudfsCursorPagination<DialMetricListResponse>, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export type DialMetricListResponsesCloudfsCursorPagination = CloudfsCursorPagination<DialMetricListResponse>;
+
+/**
+ * Dial counts and rates for one region in one time bucket. One record per region
+ * per bucket.
+ */
+export interface DialMetricListResponse {
+  /**
+   * `dials.total` divided by the bucket duration in seconds, rounded to 4 decimal
+   * places. Counts every dial attempt, rejected ones included.
+   */
+  average_dps?: number;
+
+  /**
+   * Dial attempt counts in the bucket.
+   */
+  dials?: DialMetricListResponse.Dials;
+
+  /**
+   * DPS limit in force during the busiest 5-second window, so it compares directly
+   * with `peak_dps`. `null` means unlimited. Enforcement near the limit is
+   * approximate; `dials.rejected.dps_limit` is the authoritative signal that the
+   * limit was reached.
+   */
+  dps_limit?: number | null;
+
+  /**
+   * End of the bucket (exclusive), UTC. Five seconds, one minute or one hour after
+   * `start_time`, depending on `granularity`.
+   */
+  end_time?: string;
+
+  /**
+   * Dials per second, rounded to 4 decimal places, in the busiest 5-second window of
+   * the bucket, summed across all call-processing nodes of the region. Counts every
+   * dial attempt, rejected ones included, so `peak_dps` above `dps_limit` is
+   * expected when dials were rejected. For `granularity=second` it equals
+   * `average_dps`.
+   */
+  peak_dps?: number;
+
+  record_type?: 'dial_metric';
+
+  /**
+   * Region where the dials were handled. Current values are `us`, `eu`, `australia`,
+   * `middle_east`, `canada` and `india`. New values can be added, so clients must
+   * tolerate values not listed here. Buckets of different regions are separate
+   * records.
+   */
+  region?: string;
+
+  /**
+   * Start of the bucket (inclusive), UTC.
+   */
+  start_time?: string;
+}
+
+export namespace DialMetricListResponse {
+  /**
+   * Dial attempt counts in the bucket.
+   */
+  export interface Dials {
+    /**
+     * Dial attempts that were not rejected by a limit.
+     */
+    accepted?: number;
+
+    /**
+     * Dial attempts rejected by a limit.
+     */
+    rejected?: Dials.Rejected;
+
+    /**
+     * All dial attempts, rejected ones included: accepted plus every rejected count.
+     */
+    total?: number;
+  }
+
+  export namespace Dials {
+    /**
+     * Dial attempts rejected by a limit.
+     */
+    export interface Rejected {
+      /**
+       * Rejected by a daily limit.
+       */
+      daily_limit?: number;
+
+      /**
+       * Rejected by the dials-per-second limit.
+       */
+      dps_limit?: number;
+
+      /**
+       * Rejected by an hourly limit.
+       */
+      hourly_limit?: number;
+    }
+  }
+}
+
+export interface DialMetricListParams extends CloudfsCursorPaginationParams {
+  /**
+   * Exclusive end of the range, ISO 8601. Must be after `start_time`. Buckets that
+   * start before this time are returned.
+   */
+  end_time: string;
+
+  /**
+   * Bucket size. `second` returns 5-second buckets (the finest resolution) and is
+   * kept for the last 48 hours. `minute` and `hour` are kept for the last 30 days.
+   */
+  granularity: 'second' | 'minute' | 'hour';
+
+  /**
+   * Inclusive start of the range, ISO 8601 (for example `2026-09-29T12:00:00.000Z`).
+   * Buckets that start at or after this time are returned. A `start_time` older than
+   * the retention window of the chosen `granularity` is moved forward to the start
+   * of that window, and `meta.start_time` returns the start actually used.
+   */
+  start_time: string;
+
+  /**
+   * Sort order of the buckets by `start_time`. `-start_time` (default) returns the
+   * newest first, `start_time` the oldest first. `region` follows the same direction
+   * for buckets with the same `start_time`. To read the live rate, use
+   * `granularity=second` and `sort=-start_time`, then take the first record of each
+   * `region`.
+   */
+  sort?: '-start_time' | 'start_time';
+}
+
+export declare namespace DialMetrics {
+  export {
+    type DialMetricListResponse as DialMetricListResponse,
+    type DialMetricListResponsesCloudfsCursorPagination as DialMetricListResponsesCloudfsCursorPagination,
+    type DialMetricListParams as DialMetricListParams,
+  };
+}

package/src/resources/dir/dir.ts

@@ -248,8 +248,7 @@ export class DirResource extends APIResource {
    * existing registration stays live throughout the new vetting cycle.
    *
    * Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `400`
-   * if the DIR's business and financial references have not been submitted. Returns
-   * `409` if the DIR has an unresolved infringement claim.
+   * if the DIR has an unresolved infringement claim.
    *
    * @example
    * ```ts
@@ -533,6 +532,7 @@ export interface Document {
     | 'letter_of_authorization'
     | 'business_registration'
     | 'articles_of_incorporation'
+    | 'certificate_of_good_standing'
     | 'tax_document'
     | 'ein_letter'
     | 'trademark_registration'
@@ -542,6 +542,8 @@ export interface Document {
     | 'government_id'
     | 'utility_bill'
     | 'bank_statement'
+    | 'business_credit_report'
+    | 'bank_reference_letter'
     | 'other';
 
   /**
@@ -645,10 +647,12 @@ export namespace DirRetrieveBpoAuthorizationsResponse {
     record_type: 'bpo_authorization';
 
     /**
-     * Review state of this authorization. `pending` on create or when the Letter of
-     * Authorization is re-uploaded; an admin moves it to `approved` or `rejected`.
-     * Only an `approved` authorization adds the BPO to this DIR's authorized callers
-     * in the branded calling registry.
+     * Review state of this authorization. `pending` when the authorization is first
+     * added, or when you send a different `loa_document_id` for this BPO in
+     * `bpo_authorizations` (uploading a document alone changes nothing). Approving the
+     * DIR approves its pending authorizations; an admin can also approve or reject one
+     * on its own. Only an `approved` authorization adds the BPO to this DIR's
+     * authorized callers in the branded calling registry.
      */
     status: 'pending' | 'approved' | 'rejected';
 
@@ -842,8 +846,9 @@ export interface DirNewLoaParams {
   phone_numbers: Array<string>;
 
   /**
-   * Third-party reseller / partner managing the enterprise's phone numbers. Omit
-   * when the enterprise works directly with Telnyx.
+   * Third-party reseller / partner managing the enterprise's phone numbers on its
+   * behalf, such as a call center (BPO) acting for a client. Omit when the
+   * enterprise manages its own numbers.
    */
   agent?: LoaAPI.AgentInput;
 

package/src/resources/dir/phone-numbers.ts

@@ -232,12 +232,7 @@ export interface PhoneNumberRemoveParams {
   phone_numbers: Array<string>;
 }
 
-export interface PhoneNumberListParams extends DefaultFlatPaginationParams {
-  /**
-   * Filter by phone-number status.
-   */
-  status?: PhoneNumberBatchesAPI.DirPhoneNumberStatus;
-}
+export interface PhoneNumberListParams extends DefaultFlatPaginationParams {}
 
 export interface PhoneNumberAddParams {
   /**

package/src/resources/dir/references.ts

@@ -7,6 +7,8 @@ import { path } from '../../internal/utils/path';
 
 /**
  * Submit and manage the two business references and one financial reference that vouch for a DIR. References are contacted to confirm the business identity during vetting.
+ *
+ * References (two business references and one financial reference) are needed only if the documents uploaded with the DIR don't already prove the business is legitimate and financially stable. Any one of these is enough proof: audited or certified financial statements (uploaded as `other`, with a description), a commercial credit report (uploaded as `business_credit_report`), or references. Telnyx reviewers decide during vetting whether your documents are enough.
  */
 export class References extends APIResource {
   /**
@@ -33,21 +35,25 @@ export class References extends APIResource {
   /**
    * Submit the two business references and one financial reference for a DIR.
    *
-   * The DIR's authorizer email must be verified first (see the email-verification
-   * endpoint). Until it is, this returns `409` and no references are stored.
+   * References (two business references and one financial reference) are needed only
+   * if the documents uploaded with the DIR don't already prove the business is
+   * legitimate and financially stable. Any one of these is enough proof: audited or
+   * certified financial statements (uploaded as `other`, with a description), a
+   * commercial credit report (uploaded as `business_credit_report`), or references.
+   * Telnyx reviewers decide during vetting whether your documents are enough.
+   *
+   * References can't be changed while the DIR is `verified`. Update the DIR first,
+   * which returns it to draft.
    *
    * The request body carries exactly two business references plus one financial
    * reference. The first submission stores them and returns `201`. Resubmitting
    * returns `200`: identical values are simply confirmed and nothing is written,
    * while changed values replace those references.
    *
-   * Replacing a reference is allowed only while the DIR itself is still editable,
-   * the same window in which a single reference may be updated; once the DIR has
-   * been submitted for vetting this returns `400`. A replaced reference's pending
-   * verification call is cancelled and its dial-in code stops working, and the
-   * replacement contact is emailed fresh scheduling details. References whose
-   * details did not change keep their existing call, code, and the notice already
-   * sent to them.
+   * A replaced reference's pending verification call is cancelled and its dial-in
+   * code stops working, and the replacement contact is emailed fresh scheduling
+   * details. References whose details did not change keep their existing call, code,
+   * and the notice already sent to them.
    *
    * The response always echoes the stored references in the same shape as the GET.
    *

package/src/resources/dir/verify-email.ts

@@ -6,7 +6,7 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * Verify ownership of a DIR's authorizer email. A short code is emailed and confirmed; the email must be verified before references can be submitted.
+ * Verify ownership of a DIR's authorizer email. A short code is emailed and confirmed.
  */
 export class VerifyEmail extends APIResource {
   /**
@@ -26,11 +26,23 @@ export class VerifyEmail extends APIResource {
 
   /**
    * Email a 6-digit code to the DIR's authorizer email to confirm ownership of that
-   * address.
+   * address. The code goes to the authorizer, not to the caller. If the authorizer
+   * is someone else (for example a client's executive), that person has to share the
+   * code with whoever is completing setup.
    *
-   * The code expires in 15 minutes. Requesting a new code invalidates any previous
-   * one. Resends are rate limited (a short cooldown plus a daily cap). Submit the
-   * code to `POST /dir/{dir_id}/verify_email/confirm`.
+   * How long the code lasts: 15 minutes by default. 8 hours when the DIR has a call
+   * center (BPO) linked through `bpo_authorizations` whose authorization is pending
+   * review or approved (a rejected authorization does not count). Link the call
+   * center before you send the code: a code sent before the link keeps the 15-minute
+   * window, and a code sent after the link lasts 8 hours. The email states the
+   * window, and `expires_at` in the response always shows the exact expiry.
+   *
+   * To resend, call this endpoint again. Each send issues a fresh code and
+   * invalidates the previous one. Sends are limited to one every 60 seconds and 10
+   * per DIR per UTC day. A throttled send returns `429` with `retry_after_secs` and
+   * `sends_remaining_today` in the error `meta`.
+   *
+   * Submit the code to `POST /dir/{dir_id}/verify_email/confirm`.
    *
    * @example
    * ```ts

package/src/resources/email-domains/email-domains.ts

@@ -565,7 +565,7 @@ export interface EmailDomainListParams extends DefaultFlatPaginationParams {
   /**
    * Field to sort by. Prefix with `-` for descending order.
    */
-  sort?: 'created_at' | '-created_at' | 'domain' | '-domain';
+  sort?: 'created_at' | '-created_at' | 'domain' | '-domain' | 'updated_at' | '-updated_at';
 }
 
 export interface EmailDomainCreateParams {

package/src/resources/email-templates.ts

@@ -13,7 +13,11 @@ import { path } from '../internal/utils/path';
  */
 export class EmailTemplates extends APIResource {
   /**
-   * Lists templates sorted newest first by `created_at desc, id desc`.
+   * Lists templates sorted newest first by `created_at desc, id desc`. Optional
+   * filters match a case-insensitive literal name/subject query, stored body
+   * presence, and the `strict_variables` and `autoescape` settings. Filters
+   * intersect, remain scoped to the authenticated account, and apply before cursor
+   * pagination. Invalid filter names or values return 400.
    *
    * @example
    * ```ts
@@ -164,7 +168,11 @@ export class EmailTemplates extends APIResource {
 
 export type EmailTemplatesEmailCursorPagination = EmailCursorPagination<EmailTemplate>;
 
-export interface EmailTemplate {
+export interface EmailTemplate extends EmailTemplateCommon {
+  subject: string | null;
+}
+
+export interface EmailTemplateCommon {
   id: string;
 
   /**
@@ -189,8 +197,6 @@ export interface EmailTemplate {
    */
   strict_variables: boolean;
 
-  subject: string | null;
-
   text_body: string | null;
 
   updated_at: string;
@@ -199,15 +205,23 @@ export interface EmailTemplate {
    * Structured variable requirements, or `null` when the template uses only the
    * legacy `variables` array.
    */
-  variable_schema: { [key: string]: EmailTemplate.VariableSchema } | null;
+  variable_schema: { [key: string]: EmailTemplateCommon.VariableSchema } | null;
 
   /**
-   * Legacy unstructured variable names. This path remains supported unchanged.
+   * Persisted variable names. In `explicit` mode this array preserves the exact
+   * provided order, duplicates, and string contents; in `automatic` mode it is
+   * derived from the stored subject and bodies.
    */
   variables: Array<string>;
+
+  /**
+   * `automatic` when variable names are derived from template content; `explicit`
+   * when `variables` is the exact manually managed array.
+   */
+  variables_mode: 'automatic' | 'explicit';
 }
 
-export namespace EmailTemplate {
+export namespace EmailTemplateCommon {
   export interface VariableSchema {
     /**
      * Whether the variable must be supplied when strict variable validation is
@@ -260,7 +274,22 @@ export interface UpdateEmailTemplateRequest {
    */
   variable_schema?: { [key: string]: UpdateEmailTemplateRequest.VariableSchema } | null;
 
-  variables?: Array<string>;
+  /**
+   * Persisted variable names. In `automatic` mode a non-null array is rejected; in
+   * `explicit` mode this is the exact manual array and each item is limited to 255
+   * Unicode code points.
+   */
+  variables?: Array<string> | null;
+
+  /**
+   * Controls how `variables` is maintained. Setting `automatic` re-extracts
+   * immediately from the effective subject, HTML body, and text body and rejects a
+   * simultaneous non-null array. Setting `explicit` requires the exact non-null
+   * array, including valid `[]`. With the mode omitted, a non-null array selects
+   * explicit mode, null selects automatic mode, and omitting both fields preserves
+   * the current mode. Source-content changes re-extract only in automatic mode.
+   */
+  variables_mode?: 'automatic' | 'explicit';
 }
 
 export namespace UpdateEmailTemplateRequest {
@@ -281,8 +310,8 @@ export namespace UpdateEmailTemplateRequest {
 export interface EmailTemplateRenderResponse {
   /**
    * Template object with `subject`, `html_body`, and `text_body` replaced by their
-   * Liquid-rendered values. All other template fields (id, name, variables, etc.)
-   * remain unchanged.
+   * Liquid-rendered values. Rendered content is not limited by the stored
+   * template-field lengths. All other template fields remain unchanged.
    */
   data: EmailTemplateRenderResponse.Data;
 }
@@ -290,13 +319,44 @@ export interface EmailTemplateRenderResponse {
 export namespace EmailTemplateRenderResponse {
   /**
    * Template object with `subject`, `html_body`, and `text_body` replaced by their
-   * Liquid-rendered values. All other template fields (id, name, variables, etc.)
-   * remain unchanged.
+   * Liquid-rendered values. Rendered content is not limited by the stored
+   * template-field lengths. All other template fields remain unchanged.
    */
-  export interface Data extends EmailTemplatesAPI.EmailTemplate {}
+  export interface Data extends EmailTemplatesAPI.EmailTemplateCommon {
+    subject: string | null;
+  }
 }
 
-export interface EmailTemplateListParams extends EmailCursorPaginationParams {}
+export interface EmailTemplateListParams extends EmailCursorPaginationParams {
+  /**
+   * Exact match on the template's `autoescape` option. Only the exact query strings
+   * `true` and `false` are accepted; other values, including blank, return 400.
+   */
+  'filter[autoescape]'?: 'true' | 'false';
+
+  /**
+   * Matches templates by stored body presence. `html_and_text` requires both an HTML
+   * and text body; `html_only` requires HTML and no text body; `text_only` requires
+   * text and no HTML body; `no_body` requires neither. `null` and exactly `""` count
+   * as absent; whitespace-only strings count as content. An empty or unsupported
+   * value returns a 400 response.
+   */
+  'filter[content_type]'?: 'html_and_text' | 'html_only' | 'text_only' | 'no_body';
+
+  /**
+   * Case-insensitive literal substring match over the template `name` or stored
+   * `subject` only; bodies are never searched. `%`, `_`, and `\` are literal
+   * characters with no wildcard meaning. A blank value is treated as omitted.
+   */
+  'filter[query]'?: string;
+
+  /**
+   * Exact match on the template's `strict_variables` option. Only the exact query
+   * strings `true` and `false` are accepted; other values, including blank,
+   * return 400.
+   */
+  'filter[strict_variables]'?: 'true' | 'false';
+}
 
 export interface EmailTemplateCreateParams {
   /**
@@ -353,10 +413,21 @@ export interface EmailTemplateCreateParams {
   variable_schema?: { [key: string]: EmailTemplateCreateParams.VariableSchema } | null;
 
   /**
-   * Body param: Template variables. Auto-extracted from subject/body fields when
-   * absent.
+   * Body param: Persisted variable names. In `automatic` mode a non-null array is
+   * rejected; in `explicit` mode this is the exact manual array and each item is
+   * limited to 255 Unicode code points.
    */
-  variables?: Array<string>;
+  variables?: Array<string> | null;
+
+  /**
+   * Body param: Controls how `variables` is maintained. If both fields are omitted
+   * (or `variables` is null), the template uses `automatic` mode and extracts
+   * variable names from the effective subject, HTML body, and text body. A non-null
+   * `variables` array with no mode selects `explicit`. `automatic` rejects a
+   * simultaneous non-null array; `explicit` requires a non-null array, including
+   * valid `[]`, and preserves its exact order, duplicates, and string contents.
+   */
+  variables_mode?: 'automatic' | 'explicit';
 
   /**
    * Header param: Optional opaque, unquoted key for safely retrying the same logical
@@ -420,7 +491,22 @@ export interface EmailTemplateReplaceParams {
    */
   variable_schema?: { [key: string]: EmailTemplateReplaceParams.VariableSchema } | null;
 
-  variables?: Array<string>;
+  /**
+   * Persisted variable names. In `automatic` mode a non-null array is rejected; in
+   * `explicit` mode this is the exact manual array and each item is limited to 255
+   * Unicode code points.
+   */
+  variables?: Array<string> | null;
+
+  /**
+   * Controls how `variables` is maintained. Setting `automatic` re-extracts
+   * immediately from the effective subject, HTML body, and text body and rejects a
+   * simultaneous non-null array. Setting `explicit` requires the exact non-null
+   * array, including valid `[]`. With the mode omitted, a non-null array selects
+   * explicit mode, null selects automatic mode, and omitting both fields preserves
+   * the current mode. Source-content changes re-extract only in automatic mode.
+   */
+  variables_mode?: 'automatic' | 'explicit';
 }
 
 export namespace EmailTemplateReplaceParams {
@@ -472,7 +558,22 @@ export interface EmailTemplateUpdateParams {
    */
   variable_schema?: { [key: string]: EmailTemplateUpdateParams.VariableSchema } | null;
 
-  variables?: Array<string>;
+  /**
+   * Persisted variable names. In `automatic` mode a non-null array is rejected; in
+   * `explicit` mode this is the exact manual array and each item is limited to 255
+   * Unicode code points.
+   */
+  variables?: Array<string> | null;
+
+  /**
+   * Controls how `variables` is maintained. Setting `automatic` re-extracts
+   * immediately from the effective subject, HTML body, and text body and rejects a
+   * simultaneous non-null array. Setting `explicit` requires the exact non-null
+   * array, including valid `[]`. With the mode omitted, a non-null array selects
+   * explicit mode, null selects automatic mode, and omitting both fields preserves
+   * the current mode. Source-content changes re-extract only in automatic mode.
+   */
+  variables_mode?: 'automatic' | 'explicit';
 }
 
 export namespace EmailTemplateUpdateParams {
@@ -501,6 +602,7 @@ export interface EmailTemplateRenderParams {
 export declare namespace EmailTemplates {
   export {
     type EmailTemplate as EmailTemplate,
+    type EmailTemplateCommon as EmailTemplateCommon,
     type EmailTemplateResponse as EmailTemplateResponse,
     type UpdateEmailTemplateRequest as UpdateEmailTemplateRequest,
     type EmailTemplateRenderResponse as EmailTemplateRenderResponse,