telnyx 7.12.0 → 7.13.0

package/src/resources/dir/dir.ts

@@ -238,8 +238,9 @@ export class DirResource extends APIResource {
    * numbers flip back to `submitted`. When re-submitting from `verified`, the
    * existing registration stays live throughout the new vetting cycle.
    *
-   * Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `409`
-   * if the DIR has an unresolved infringement claim.
+   * 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.
    *
    * @example
    * ```ts

package/src/resources/dir/references.ts

@@ -12,10 +12,12 @@ export class References extends APIResource {
   /**
    * List the business and financial references submitted for a DIR.
    *
-   * Returns the two business references (slots 0 and 1) followed by the single
-   * financial reference. Each entry carries only the customer-supplied details
-   * (name, title, organization, relationship, phone, email, timezone). Returns an
-   * empty list when no references were submitted.
+   * Returns the two business references (slots 1 and 2) followed by the single
+   * financial reference. Each entry carries its `ref_type` and `slot`, which
+   * together address the reference when updating it, alongside the details supplied
+   * when it was submitted (name, title, organization, relationship, phone, email,
+   * timezone). No internal identifiers are exposed. Returns an empty list when no
+   * references were submitted.
    *
    * @example
    * ```ts
@@ -35,9 +37,29 @@ export class References extends APIResource {
    * endpoint). Until it is, this returns `409` and no references are stored.
    *
    * The request body carries exactly two business references plus one financial
-   * reference. On success the references are stored and the response echoes them in
-   * the same shape as the GET. Submitting again converges on the already-stored
-   * references rather than erroring.
+   * 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.
+   *
+   * The response always echoes the stored references in the same shape as the GET.
+   *
+   * Who qualifies: the two business references confirm the company's reputation and
+   * operations. Each should be a senior contact at an organization the business
+   * works with, such as a vendor, partner, or client: a C-suite executive (CEO, CFO,
+   * CTO, COO), an owner or founder as reflected in the company's corporate records,
+   * or a senior manager, director, or executive. The financial reference confirms
+   * the company pays its bills and should be a licensed certified public accountant
+   * (CPA) the company uses, a contact at a bank or financial institution that has a
+   * relationship with the company, or a reasonable alternative banking or financial
+   * reference.
    *
    * @example
    * ```ts
@@ -84,7 +106,7 @@ export class References extends APIResource {
    *
    * @example
    * ```ts
-   * const reference = await client.dir.references.update(0, {
+   * const reference = await client.dir.references.update(1, {
    *   dir_id: '16635d38-75a6-4481-82e8-69af60e05011',
    *   ref_type: 'business',
    * });
@@ -126,8 +148,10 @@ export interface Reference {
   ref_type: 'business' | 'financial';
 
   /**
-   * Position within the reference type. Business references occupy slots 0 and 1;
-   * the financial reference occupies slot 0.
+   * Position within the reference type, counting from 1. Business references occupy
+   * slots 1 and 2, in the order they were sent in the `business_references` array;
+   * the financial reference occupies slot 1. Use this value together with `ref_type`
+   * to address the reference when updating it.
    */
   slot: number;
 
@@ -215,7 +239,13 @@ export interface ReferenceUpdateResponse {
 
 export interface ReferenceCreateParams {
   /**
-   * Exactly two business references.
+   * Exactly two business references. Array order determines each one's slot: the
+   * first entry becomes slot 1 and the second becomes slot 2. Those slots are what
+   * you pass when updating a single reference later. Each should be a senior contact
+   * who can speak to your company's reputation and operations: a C-suite executive
+   * (CEO, CFO, CTO, COO), an owner or founder as reflected in your corporate
+   * records, or a senior manager, director, or executive at an organization you work
+   * with, such as a vendor, partner, or client.
    */
   business_references: Array<ReferenceInput>;
 

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

@@ -96,6 +96,18 @@ export namespace EmailVerificationStatusWrapped {
      * `unverified` when no verification is in progress.
      */
     status: 'sent' | 'verified' | 'unverified';
+
+    /**
+     * When the outstanding code stops being accepted. Null when no verification is in
+     * progress.
+     */
+    expires_at?: string | null;
+
+    /**
+     * How many more codes may be requested for this DIR today. Null when the daily cap
+     * does not apply.
+     */
+    sends_remaining_today?: number | null;
   }
 }
 

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

@@ -0,0 +1,358 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ImportAPI from './import';
+import { EmailBlockImportResponse, Import, ImportCreateParams } from './import';
+import { APIPromise } from '../../core/api-promise';
+import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Recipient suppression records (`/v2/email_blocks`).
+ */
+export class EmailBlocks extends APIResource {
+  import: ImportAPI.Import = new ImportAPI.Import(this._client);
+
+  /**
+   * Account-scoped list. Two mutually exclusive pagination modes:
+   *
+   * - **Offset**: `page[number]` (default 1) + `page[size]` (default 25, max 100).
+   *   `meta` contains `total_pages`.
+   * - **Cursor**: `page[after]` and/or `page[before]` (opaque `Base.url_encode64` of
+   *   `{"created_at","id"}`). Cannot combine with `page[number]`; `after`+`before`
+   *   together is an error. `meta` contains `next_cursor` / `previous_cursor`
+   *   (omitted when their flag is false).
+   *
+   * Sort defaults to `-created_at` (desc); only `created_at` is sortable. A `--`
+   * prefix is an error. `nil`/empty filter values are silently dropped.
+   */
+  list(
+    query: EmailBlockListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EmailBlocksDefaultFlatPagination, EmailBlock> {
+    return this._client.getAPIList('/email_blocks', DefaultFlatPagination<EmailBlock>, { query, ...options });
+  }
+
+  /**
+   * Creates a suppression with `reason: manual_block` and `source: manual`.
+   * Caller-supplied `reason` / `source` are **ignored**; `scope` is **derived**
+   * server-side from `domain_id` / `from` and is never trusted. Idempotent: if a
+   * matching row already exists (NULL-safe dedupe key: account_id, scope, to,
+   * reason, domain_id, from), returns the existing record with `200` (no new audit
+   * event).
+   *
+   * `bounce_category`, `dsn_code`, `meta`, and `group_id` are **not accepted** on
+   * the public surface. Use the unsubscribe-group suppression endpoint or the
+   * internal create surface for those.
+   */
+  create(body: EmailBlockCreateParams, options?: RequestOptions): APIPromise<EmailBlockResponse> {
+    return this._client.post('/email_blocks', { body, ...options });
+  }
+
+  /**
+   * Streams the account's suppressions as a chunked CSV (server-side cursor; never
+   * materialized). Content-type `text/csv`, header
+   * `Content-Disposition: attachment; filename="email_blocks_export.csv"`.
+   *
+   * Filters (`filter[reason]`, `filter[domain_id]`, `filter[created_after]`,
+   * `filter[created_before]`) are the only params that affect output. `sort` and
+   * `page[*]` are **parsed** (bad values still produce `400`) but **ignored** — rows
+   * stream `ORDER BY created_at ASC, id ASC` with no pagination.
+   *
+   * CSV columns:
+   * `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id`.
+   * The CSV carries the `group_id` column so group-scoped suppressions' group link
+   * survives the export (empty for account-scope rows).
+   */
+  retrieveExport(
+    query: EmailBlockRetrieveExportParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<string> {
+    return this._client.get('/email_blocks/export', {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/csv' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Soft-deletes (status → `removed`; tombstone retained). A `removed` audit event
+   * is appended unless the block was already `removed` (idempotent — returns the
+   * existing row with `200` and no new event). Mutates `updated_at`.
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<EmailBlockResponse> {
+    return this._client.delete(path`/email_blocks/${id}`, options);
+  }
+
+  /**
+   * Retrieve a suppression
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<EmailBlockResponse> {
+    return this._client.get(path`/email_blocks/${id}`, options);
+  }
+
+  /**
+   * Offset pagination only (`page[number]` default 1, `page[size]` default **50**,
+   * max 100). No `sort`, no `filter`, no cursor — ordering is fixed
+   * `desc occurred_at, desc id`. Verifies the block belongs to the account first
+   * (cross-account → 404).
+   */
+  retrieveEvents(
+    id: string,
+    query: EmailBlockRetrieveEventsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EmailBlockRetrieveEventsResponse> {
+    return this._client.get(path`/email_blocks/${id}/events`, { query, ...options });
+  }
+}
+
+export type EmailBlocksDefaultFlatPagination = DefaultFlatPagination<EmailBlock>;
+
+/**
+ * Suppression record. Schema fields hidden by the view: `account_id`,
+ * `bounce_category`, `dsn_code`, `meta`.
+ */
+export interface EmailBlock {
+  id: string;
+
+  created_at: string;
+
+  reason: 'hard_bounce' | 'spam_complaint' | 'unsubscribe' | 'invalid' | 'manual_block';
+
+  /**
+   * View-only discriminator.
+   */
+  record_type: 'email_block';
+
+  /**
+   * Derived server-side from `domain_id`/`from`; never trusted from the caller.
+   */
+  scope: 'account' | 'domain' | 'address';
+
+  source: 'feedback' | 'manual' | 'import' | 'system';
+
+  status: 'active' | 'expired' | 'removed';
+
+  /**
+   * Normalized recipient. (schema: to_address)
+   */
+  to: string;
+
+  updated_at: string;
+
+  /**
+   * `null` ⇒ account scope. Stored on the row; exposed here.
+   */
+  domain_id?: string | null;
+
+  expires_at?: string | null;
+
+  /**
+   * `null` ⇒ not address-scope. (schema: from_address)
+   */
+  from?: string | null;
+
+  /**
+   * `null` ⇒ global; set ⇒ group-scoped opt-out.
+   */
+  group_id?: string | null;
+}
+
+export interface EmailBlockResponse {
+  /**
+   * Suppression record. Schema fields hidden by the view: `account_id`,
+   * `bounce_category`, `dsn_code`, `meta`.
+   */
+  data: EmailBlock;
+}
+
+export interface OffsetMeta {
+  page_number: number;
+
+  page_size: number;
+
+  total_pages: number;
+
+  total_results: number;
+}
+
+export interface EmailBlockRetrieveEventsResponse {
+  data: Array<EmailBlockRetrieveEventsResponse.Data>;
+
+  meta: OffsetMeta;
+}
+
+export namespace EmailBlockRetrieveEventsResponse {
+  export interface Data {
+    id: string;
+
+    /**
+     * Free-text (`user_id`/`org_id`/`api_key`/`dev_bypass`/`system`/`manual`).
+     */
+    actor: string;
+
+    event_type: 'created' | 'removed' | 'expired' | 'override_used';
+
+    occurred_at: string;
+
+    /**
+     * Free-text snapshot of the block's reason at event time.
+     */
+    reason: string;
+
+    /**
+     * View-only.
+     */
+    record_type: 'email_block_event';
+
+    /**
+     * Free-text snapshot of the block's source at event time.
+     */
+    source: string;
+
+    /**
+     * `null` when the schema field is nil (the context usually sets it to `{}`).
+     */
+    meta?: { [key: string]: unknown } | null;
+  }
+}
+
+/**
+ * CSV with header row
+ * `id,to,from,reason,source,scope,status,domain_id,created_at,updated_at,expires_at,group_id`.
+ */
+export type EmailBlockRetrieveExportResponse = string;
+
+export interface EmailBlockListParams extends DefaultFlatPaginationParams {
+  /**
+   * `created_at > value` (ISO 8601).
+   */
+  'filter[created_after]'?: string;
+
+  /**
+   * `created_at < value` (ISO 8601).
+   */
+  'filter[created_before]'?: string;
+
+  /**
+   * Exact-match filter on domain_id (UUID).
+   */
+  'filter[domain_id]'?: string;
+
+  /**
+   * Exact-match filter on reason.
+   */
+  'filter[reason]'?: 'hard_bounce' | 'spam_complaint' | 'unsubscribe' | 'invalid' | 'manual_block';
+
+  /**
+   * Opaque cursor (`Base.url_encode64` of `{"created_at","id"}`). Cursor mode;
+   * mutually exclusive with `page[number]` and `page[before]`.
+   */
+  'page[after]'?: string;
+
+  /**
+   * Opaque cursor (see `page[after]`). Mutually exclusive with `page[after]` and
+   * `page[number]`.
+   */
+  'page[before]'?: string;
+
+  /**
+   * Sort field. Leading `-` = desc; only `created_at` is sortable. Default
+   * `-created_at`. `--` is an error.
+   */
+  sort?: 'created_at' | '-created_at';
+}
+
+export interface EmailBlockCreateParams {
+  /**
+   * Recipient address (normalized: trim + lower-case).
+   */
+  to: string;
+
+  /**
+   * `null` ⇒ account scope.
+   */
+  domain_id?: string | null;
+
+  expires_at?: string | null;
+
+  /**
+   * Sender address (normalized). `null` ⇒ account/domain scope.
+   */
+  from?: string | null;
+}
+
+export interface EmailBlockRetrieveExportParams {
+  /**
+   * `created_at > value` (ISO 8601).
+   */
+  'filter[created_after]'?: string;
+
+  /**
+   * `created_at < value` (ISO 8601).
+   */
+  'filter[created_before]'?: string;
+
+  /**
+   * Exact-match filter on domain_id (UUID).
+   */
+  'filter[domain_id]'?: string;
+
+  /**
+   * Exact-match filter on reason.
+   */
+  'filter[reason]'?: 'hard_bounce' | 'spam_complaint' | 'unsubscribe' | 'invalid' | 'manual_block';
+
+  /**
+   * Offset page number (≥1, default 1).
+   */
+  'page[number]'?: number;
+
+  /**
+   * Page size (1–100, default 25).
+   */
+  'page[size]'?: number;
+
+  /**
+   * Sort field. Leading `-` = desc; only `created_at` is sortable. Default
+   * `-created_at`. `--` is an error.
+   */
+  sort?: 'created_at' | '-created_at';
+}
+
+export interface EmailBlockRetrieveEventsParams {
+  /**
+   * Offset page number (≥1, default 1).
+   */
+  'page[number]'?: number;
+
+  /**
+   * Page size (default 50, max 100).
+   */
+  'page[size]'?: number;
+}
+
+EmailBlocks.Import = Import;
+
+export declare namespace EmailBlocks {
+  export {
+    type EmailBlock as EmailBlock,
+    type EmailBlockResponse as EmailBlockResponse,
+    type OffsetMeta as OffsetMeta,
+    type EmailBlockRetrieveEventsResponse as EmailBlockRetrieveEventsResponse,
+    type EmailBlockRetrieveExportResponse as EmailBlockRetrieveExportResponse,
+    type EmailBlocksDefaultFlatPagination as EmailBlocksDefaultFlatPagination,
+    type EmailBlockListParams as EmailBlockListParams,
+    type EmailBlockCreateParams as EmailBlockCreateParams,
+    type EmailBlockRetrieveExportParams as EmailBlockRetrieveExportParams,
+    type EmailBlockRetrieveEventsParams as EmailBlockRetrieveEventsParams,
+  };
+
+  export {
+    Import as Import,
+    type EmailBlockImportResponse as EmailBlockImportResponse,
+    type ImportCreateParams as ImportCreateParams,
+  };
+}

package/src/resources/email-blocks/import.ts

@@ -0,0 +1,143 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Async CSV import of competitor suppression lists.
+ */
+export class Import extends APIResource {
+  /**
+   * Accepts `multipart/form-data` with a `file` field (the CSV) and an optional
+   * `block_ttl_days` (integer >0, default 30). Validates:
+   *
+   * - content ≤ 25 MiB, else `413`
+   * - row count ≤ 250 000, else `413`
+   * - header-only / all-blank / undetectable provider → `400` Returns `202` with the
+   *   import record (status `pending`); an Oban worker (`EmailBlockImportWorker`,
+   *   max_attempts 3) transitions `pending → processing → completed | failed`.
+   *   `block_ttl_days` applies only to imported `manual_block` rows; other reasons
+   *   get `expires_at: nil`. Provider is auto-detected from the CSV header
+   *   (`sendgrid` / `mailgun` / `ses` / `generic`).
+   */
+  create(body: ImportCreateParams, options?: RequestOptions): APIPromise<EmailBlockImportResponse> {
+    return this._client.post(
+      '/email_blocks/import',
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+
+  /**
+   * Account-scoped fetch (cross-account → 404; malformed UUID → 404). Nullable
+   * fields are omitted until terminal: `provider`/`completed_at` when nil;
+   * `processed_rows`/`created_count`/`existing_count`/ `skipped_count`/`error_count`
+   * only when `status == completed`; `errors` only when non-empty; `failure_reason`
+   * only on terminal failure.
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<EmailBlockImportResponse> {
+    return this._client.get(path`/email_blocks/import/${id}`, options);
+  }
+}
+
+export interface EmailBlockImportResponse {
+  /**
+   * Import job. Schema fields hidden: `account_id`, `csv_content`, `block_ttl_days`.
+   * Nullable fields use the omit-nullable pattern.
+   */
+  data: EmailBlockImportResponse.Data;
+}
+
+export namespace EmailBlockImportResponse {
+  /**
+   * Import job. Schema fields hidden: `account_id`, `csv_content`, `block_ttl_days`.
+   * Nullable fields use the omit-nullable pattern.
+   */
+  export interface Data {
+    id: string;
+
+    created_at: string;
+
+    /**
+     * View-only.
+     */
+    record_type: 'email_block_import';
+
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+
+    /**
+     * Data-row count at upload.
+     */
+    total: number;
+
+    updated_at: string;
+
+    /**
+     * Omitted until terminal success.
+     */
+    completed_at?: string;
+
+    /**
+     * Only when `status == completed`.
+     */
+    created_count?: number;
+
+    /**
+     * Only when `status == completed`.
+     */
+    error_count?: number;
+
+    /**
+     * `{row_number: reason}`; only rendered when non-empty.
+     */
+    errors?: { [key: string]: string };
+
+    /**
+     * Only when `status == completed`.
+     */
+    existing_count?: number;
+
+    /**
+     * Only on terminal failure.
+     */
+    failure_reason?: string;
+
+    /**
+     * Only when `status == completed`.
+     */
+    processed_rows?: number;
+
+    /**
+     * Omitted when nil.
+     */
+    provider?: 'sendgrid' | 'mailgun' | 'ses' | 'generic';
+
+    /**
+     * Only when `status == completed`.
+     */
+    skipped_count?: number;
+  }
+}
+
+export interface ImportCreateParams {
+  /**
+   * The CSV file (Plug.Upload). Missing/non-upload → 400.
+   */
+  file: Uploadable;
+
+  /**
+   * TTL for imported `manual_block` rows; other reasons get `expires_at: null`.
+   * Invalid/missing → falls back to 30.
+   */
+  block_ttl_days?: number;
+}
+
+export declare namespace Import {
+  export {
+    type EmailBlockImportResponse as EmailBlockImportResponse,
+    type ImportCreateParams as ImportCreateParams,
+  };
+}

package/src/resources/email-blocks/index.ts

@@ -0,0 +1,16 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  EmailBlocks,
+  type EmailBlock,
+  type EmailBlockResponse,
+  type OffsetMeta,
+  type EmailBlockRetrieveEventsResponse,
+  type EmailBlockRetrieveExportResponse,
+  type EmailBlockListParams,
+  type EmailBlockCreateParams,
+  type EmailBlockRetrieveExportParams,
+  type EmailBlockRetrieveEventsParams,
+  type EmailBlocksDefaultFlatPagination,
+} from './email-blocks';
+export { Import, type EmailBlockImportResponse, type ImportCreateParams } from './import';

package/src/resources/email-blocks.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './email-blocks/index';