telnyx 7.11.0 → 7.13.0

package/src/resources/email-unsubscribe-groups/email-unsubscribe-groups.ts

@@ -0,0 +1,171 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SuppressionsAPI from './suppressions';
+import {
+  SuppressionCreateParams,
+  SuppressionDeleteParams,
+  SuppressionListParams,
+  Suppressions,
+} from './suppressions';
+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';
+
+/**
+ * Named groups and group-scoped suppressions.
+ */
+export class EmailUnsubscribeGroups extends APIResource {
+  suppressions: SuppressionsAPI.Suppressions = new SuppressionsAPI.Suppressions(this._client);
+
+  /**
+   * Offset pagination only (`page[number]` default 1, `page[size]` default 25, max
+   * 100). No `sort`/`filter`/cursor — ordering fixed `desc created_at, desc id`.
+   * Uses the shared `QueryParser.parse_offset/1` — a malformed `page` (e.g. flat
+   * `?page=1` instead of `?page[number]=1`) returns `400` (code `10015`), consistent
+   * with `GET /v2/email_blocks`. `meta` includes `total_pages`.
+   */
+  list(
+    query: EmailUnsubscribeGroupListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<UnsubscribeGroupsDefaultFlatPagination, UnsubscribeGroup> {
+    return this._client.getAPIList('/email_unsubscribe_groups', DefaultFlatPagination<UnsubscribeGroup>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Create an unsubscribe group
+   */
+  create(
+    body: EmailUnsubscribeGroupCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<UnsubscribeGroupResponse> {
+    return this._client.post('/email_unsubscribe_groups', { body, ...options });
+  }
+
+  /**
+   * If the group has 0 active suppressions, hard-deletes the row. With `force=true`,
+   * soft-deletes all active suppressions first (status → `removed`, `group_id`
+   * cleared, `removed` audit event per block) in a single transaction, then
+   * hard-deletes the group. Without `force` and active suppressions present → `409`.
+   * Audit trail is preserved. `force` only accepts the string `"true"` or boolean
+   * `true`; all other values are false.
+   */
+  delete(
+    id: string,
+    params: EmailUnsubscribeGroupDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { force } = params ?? {};
+    return this._client.delete(path`/email_unsubscribe_groups/${id}`, {
+      query: { force },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Retrieve an unsubscribe group
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<UnsubscribeGroupResponse> {
+    return this._client.get(path`/email_unsubscribe_groups/${id}`, options);
+  }
+
+  /**
+   * Partial update (only `name` / `description`). `PUT` is not routed.
+   */
+  update(
+    id: string,
+    body: EmailUnsubscribeGroupUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<UnsubscribeGroupResponse> {
+    return this._client.patch(path`/email_unsubscribe_groups/${id}`, { body, ...options });
+  }
+}
+
+export type UnsubscribeGroupsDefaultFlatPagination = DefaultFlatPagination<UnsubscribeGroup>;
+
+/**
+ * Group list `meta` (consistent with `GET /v2/email_blocks`).
+ */
+export interface GroupListMeta {
+  page_number: number;
+
+  page_size: number;
+
+  total_pages: number;
+
+  total_results: number;
+}
+
+export interface UnsubscribeGroup {
+  id: string;
+
+  created_at: string;
+
+  /**
+   * Always present (not omit-nullable); `null` when unset.
+   */
+  description: string | null;
+
+  name: string;
+
+  /**
+   * View-only.
+   */
+  record_type: 'email_unsubscribe_group';
+
+  updated_at: string;
+}
+
+export interface UnsubscribeGroupResponse {
+  data: UnsubscribeGroup;
+}
+
+export interface EmailUnsubscribeGroupListParams extends DefaultFlatPaginationParams {}
+
+export interface EmailUnsubscribeGroupCreateParams {
+  name: string;
+
+  description?: string | null;
+}
+
+export interface EmailUnsubscribeGroupDeleteParams {
+  /**
+   * Force-delete a group with active suppressions. Only `"true"` (string) or `true`
+   * (bool) are truthy; all other values are false.
+   */
+  force?: 'true' | 'false' | boolean;
+}
+
+export interface EmailUnsubscribeGroupUpdateParams {
+  description?: string | null;
+
+  name?: string;
+}
+
+EmailUnsubscribeGroups.Suppressions = Suppressions;
+
+export declare namespace EmailUnsubscribeGroups {
+  export {
+    type GroupListMeta as GroupListMeta,
+    type UnsubscribeGroup as UnsubscribeGroup,
+    type UnsubscribeGroupResponse as UnsubscribeGroupResponse,
+    type UnsubscribeGroupsDefaultFlatPagination as UnsubscribeGroupsDefaultFlatPagination,
+    type EmailUnsubscribeGroupListParams as EmailUnsubscribeGroupListParams,
+    type EmailUnsubscribeGroupCreateParams as EmailUnsubscribeGroupCreateParams,
+    type EmailUnsubscribeGroupDeleteParams as EmailUnsubscribeGroupDeleteParams,
+    type EmailUnsubscribeGroupUpdateParams as EmailUnsubscribeGroupUpdateParams,
+  };
+
+  export {
+    Suppressions as Suppressions,
+    type SuppressionListParams as SuppressionListParams,
+    type SuppressionCreateParams as SuppressionCreateParams,
+    type SuppressionDeleteParams as SuppressionDeleteParams,
+  };
+}

package/src/resources/email-unsubscribe-groups/index.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  EmailUnsubscribeGroups,
+  type GroupListMeta,
+  type UnsubscribeGroup,
+  type UnsubscribeGroupResponse,
+  type EmailUnsubscribeGroupListParams,
+  type EmailUnsubscribeGroupCreateParams,
+  type EmailUnsubscribeGroupDeleteParams,
+  type EmailUnsubscribeGroupUpdateParams,
+  type UnsubscribeGroupsDefaultFlatPagination,
+} from './email-unsubscribe-groups';
+export {
+  Suppressions,
+  type SuppressionListParams,
+  type SuppressionCreateParams,
+  type SuppressionDeleteParams,
+} from './suppressions';

package/src/resources/email-unsubscribe-groups/suppressions.ts

@@ -0,0 +1,90 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as EmailBlocksAPI from '../email-blocks/email-blocks';
+import { EmailBlocksDefaultFlatPagination } from '../email-blocks/email-blocks';
+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';
+
+/**
+ * Named groups and group-scoped suppressions.
+ */
+export class Suppressions extends APIResource {
+  /**
+   * Account + group scoped. Offset pagination only (`page[number]` default 1,
+   * `page[size]` default 25, max 100). No `sort`/`filter`/ cursor — ordering fixed
+   * `desc created_at, desc id`. Uses the shared `QueryParser.parse_offset/1` — a
+   * malformed `page` returns `400` (code `10015`), consistent with
+   * `GET /v2/email_blocks`. `meta` includes `total_pages`. Rows reuse the standard
+   * suppression shape (`group_id` set to this group).
+   */
+  list(
+    id: string,
+    query: SuppressionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EmailBlocksDefaultFlatPagination, EmailBlocksAPI.EmailBlock> {
+    return this._client.getAPIList(
+      path`/email_unsubscribe_groups/${id}/suppressions`,
+      DefaultFlatPagination<EmailBlocksAPI.EmailBlock>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Creates a suppression with `reason: unsubscribe`, `source: manual`,
+   * `group_id: <this group>`. All other body fields are ignored; only `to` is read.
+   * Idempotent (same dedupe key → `200`, no new event).
+   */
+  create(
+    id: string,
+    body: SuppressionCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailBlocksAPI.EmailBlockResponse> {
+    return this._client.post(path`/email_unsubscribe_groups/${id}/suppressions`, { body, ...options });
+  }
+
+  /**
+   * Soft-deletes all active blocks for (account, group, normalized email) — one
+   * `removed` audit event per block (`actor: manual`). The `email` path segment is
+   * normalized (trim + lower-case) before matching. Idempotent on already-removed
+   * rows (returns `404` since they're no longer `active`).
+   *
+   * Two distinct `404` cases: a missing/cross-account **group** returns
+   * `10001 "The requested unsubscribe group was not found"`; a group that exists but
+   * has **no active suppression** for that email returns
+   * `10001 "The requested group suppression was not found"`.
+   */
+  delete(email: string, params: SuppressionDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { id } = params;
+    return this._client.delete(path`/email_unsubscribe_groups/${id}/suppressions/${email}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface SuppressionListParams extends DefaultFlatPaginationParams {}
+
+export interface SuppressionCreateParams {
+  to: string;
+}
+
+export interface SuppressionDeleteParams {
+  /**
+   * Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+   */
+  id: string;
+}
+
+export declare namespace Suppressions {
+  export {
+    type SuppressionListParams as SuppressionListParams,
+    type SuppressionCreateParams as SuppressionCreateParams,
+    type SuppressionDeleteParams as SuppressionDeleteParams,
+  };
+}
+
+export { type EmailBlocksDefaultFlatPagination };

package/src/resources/email-unsubscribe-groups.ts

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

package/src/resources/email-validations/batch.ts

@@ -0,0 +1,187 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as BatchAPI from './batch';
+import * as EmailValidationsAPI from './email-validations';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Validate email addresses synchronously or in asynchronous batches.
+ */
+export class Batch extends APIResource {
+  /**
+   * Creates an asynchronous batch validation job for up to 1,000 email addresses.
+   *
+   * @example
+   * ```ts
+   * const batch = await client.emailValidations.batch.create({
+   *   emails: ['user@example.com', 'admin@example.org'],
+   *   webhook_url:
+   *     'https://example.com/webhooks/email-validation',
+   * });
+   * ```
+   */
+  create(params: BatchCreateParams, options?: RequestOptions): APIPromise<BatchCreateResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/email_validations/batch', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves the current status and, once completed, validation results for a batch
+   * job.
+   *
+   * @example
+   * ```ts
+   * const batch = await client.emailValidations.batch.retrieve(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<BatchRetrieveResponse> {
+    return this._client.get(path`/email_validations/batch/${id}`, options);
+  }
+}
+
+export type EmailValidationBatchStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+export interface BatchCreateResponse {
+  /**
+   * Shape returned by the create endpoint. Includes duplicates_removed.
+   */
+  data: BatchCreateResponse.Data;
+}
+
+export namespace BatchCreateResponse {
+  /**
+   * Shape returned by the create endpoint. Includes duplicates_removed.
+   */
+  export interface Data {
+    id: string;
+
+    duplicates_removed: number;
+
+    record_type: 'email_validation_batch';
+
+    status: BatchAPI.EmailValidationBatchStatus;
+
+    total: number;
+
+    webhook_url?: string;
+  }
+}
+
+export interface BatchRetrieveResponse {
+  /**
+   * Shape returned by the GET endpoint. Does not include duplicates_removed.
+   */
+  data: BatchRetrieveResponse.Data;
+}
+
+export namespace BatchRetrieveResponse {
+  /**
+   * Shape returned by the GET endpoint. Does not include duplicates_removed.
+   */
+  export interface Data {
+    id: string;
+
+    record_type: 'email_validation_batch';
+
+    status: BatchAPI.EmailValidationBatchStatus;
+
+    total: number;
+
+    completed_at?: string;
+
+    /**
+     * Map keyed by original email address. Present only when the batch is completed.
+     */
+    results?: { [key: string]: Data.Results };
+
+    webhook_url?: string;
+  }
+
+  export namespace Data {
+    export interface Results {
+      checks: Results.Checks;
+
+      email: string;
+
+      risk_score: number;
+
+      valid: boolean;
+
+      /**
+       * Suggested correction for typo. Omitted when nil.
+       */
+      did_you_mean?: string;
+    }
+
+    export namespace Results {
+      export interface Checks {
+        disposable: EmailValidationsAPI.EmailValidationCheck;
+
+        mx: EmailValidationsAPI.EmailValidationCheck;
+
+        role_based: EmailValidationsAPI.EmailValidationCheck;
+
+        syntax: EmailValidationsAPI.EmailValidationCheck;
+
+        typo: Checks.Typo;
+      }
+
+      export namespace Checks {
+        export interface Typo extends EmailValidationsAPI.EmailValidationCheck {
+          /**
+           * Suggested correction for common typos. Omitted when nil.
+           */
+          suggestion?: string;
+        }
+      }
+    }
+  }
+}
+
+export interface BatchCreateParams {
+  /**
+   * Body param
+   */
+  emails: Array<string>;
+
+  /**
+   * Body param: URL for batch completion webhook. Empty string is treated as
+   * omitted. SSRF-protected; private/reserved IPs and internal hostnames are
+   * rejected.
+   */
+  webhook_url?: string;
+
+  /**
+   * Header param: Optional opaque, unquoted key for safely retrying the same logical
+   * request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+   * Generate a unique UUID v4 for each operation and reuse it only when retrying
+   * that operation with the same request. Invalid headers—including duplicate,
+   * empty, malformed, or overlong values—return 400 with error code 10015. A request
+   * already in progress with the same key returns 409; reusing the key with a
+   * different request returns 422. Only successful responses are replayed, for up to
+   * 24 hours. Do not include sensitive data in the key.
+   */
+  'Idempotency-Key'?: string;
+}
+
+export declare namespace Batch {
+  export {
+    type EmailValidationBatchStatus as EmailValidationBatchStatus,
+    type BatchCreateResponse as BatchCreateResponse,
+    type BatchRetrieveResponse as BatchRetrieveResponse,
+    type BatchCreateParams as BatchCreateParams,
+  };
+}

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

@@ -0,0 +1,141 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as EmailValidationsAPI from './email-validations';
+import * as BatchAPI from './batch';
+import {
+  Batch,
+  BatchCreateParams,
+  BatchCreateResponse,
+  BatchRetrieveResponse,
+  EmailValidationBatchStatus,
+} from './batch';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Validate email addresses synchronously or in asynchronous batches.
+ */
+export class EmailValidations extends APIResource {
+  batch: BatchAPI.Batch = new BatchAPI.Batch(this._client);
+
+  /**
+   * Validates a single email address and returns deliverability checks.
+   *
+   * @example
+   * ```ts
+   * const emailValidation =
+   *   await client.emailValidations.create({
+   *     email: 'user@example.com',
+   *   });
+   * ```
+   */
+  create(
+    params: EmailValidationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailValidationCreateResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/email_validations', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface EmailValidationCheck {
+  pass: boolean;
+
+  /**
+   * Human-readable check detail. Omitted when nil.
+   */
+  details?: string;
+}
+
+export interface EmailValidationCreateResponse {
+  data: EmailValidationCreateResponse.Data;
+}
+
+export namespace EmailValidationCreateResponse {
+  export interface Data {
+    checks: Data.Checks;
+
+    email: string;
+
+    record_type: 'email_validation';
+
+    risk_score: number;
+
+    valid: boolean;
+
+    /**
+     * Suggested correction for typo. Omitted when nil.
+     */
+    did_you_mean?: string;
+  }
+
+  export namespace Data {
+    export interface Checks {
+      disposable: EmailValidationsAPI.EmailValidationCheck;
+
+      mx: EmailValidationsAPI.EmailValidationCheck;
+
+      role_based: EmailValidationsAPI.EmailValidationCheck;
+
+      syntax: EmailValidationsAPI.EmailValidationCheck;
+
+      typo: Checks.Typo;
+    }
+
+    export namespace Checks {
+      export interface Typo extends EmailValidationsAPI.EmailValidationCheck {
+        /**
+         * Suggested correction for common typos. Omitted when nil.
+         */
+        suggestion?: string;
+      }
+    }
+  }
+}
+
+export interface EmailValidationCreateParams {
+  /**
+   * Body param: Email address to validate. Any non-empty string is accepted; invalid
+   * syntax returns valid=false rather than a request error.
+   */
+  email: string;
+
+  /**
+   * Header param: Optional opaque, unquoted key for safely retrying the same logical
+   * request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+   * Generate a unique UUID v4 for each operation and reuse it only when retrying
+   * that operation with the same request. Invalid headers—including duplicate,
+   * empty, malformed, or overlong values—return 400 with error code 10015. A request
+   * already in progress with the same key returns 409; reusing the key with a
+   * different request returns 422. Only successful responses are replayed, for up to
+   * 24 hours. Do not include sensitive data in the key.
+   */
+  'Idempotency-Key'?: string;
+}
+
+EmailValidations.Batch = Batch;
+
+export declare namespace EmailValidations {
+  export {
+    type EmailValidationCheck as EmailValidationCheck,
+    type EmailValidationCreateResponse as EmailValidationCreateResponse,
+    type EmailValidationCreateParams as EmailValidationCreateParams,
+  };
+
+  export {
+    Batch as Batch,
+    type EmailValidationBatchStatus as EmailValidationBatchStatus,
+    type BatchCreateResponse as BatchCreateResponse,
+    type BatchRetrieveResponse as BatchRetrieveResponse,
+    type BatchCreateParams as BatchCreateParams,
+  };
+}

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

@@ -0,0 +1,15 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Batch,
+  type EmailValidationBatchStatus,
+  type BatchCreateResponse,
+  type BatchRetrieveResponse,
+  type BatchCreateParams,
+} from './batch';
+export {
+  EmailValidations,
+  type EmailValidationCheck,
+  type EmailValidationCreateResponse,
+  type EmailValidationCreateParams,
+} from './email-validations';

package/src/resources/email-validations.ts

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