telnyx 7.22.0 → 7.24.0

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

@@ -178,6 +178,28 @@ export class EmailDomains extends APIResource {
   retrieveHealth(id: string, options?: RequestOptions): APIPromise<EmailDomainRetrieveHealthResponse> {
     return this._client.get(path`/email_domains/${id}/health`, options);
   }
+
+  /**
+   * Generates a new DKIM key for the domain, activates it, and retires the previous
+   * key. The response includes the updated DKIM DNS records the customer must
+   * publish. Selectors are fixed, so rotation replaces the TXT value at the existing
+   * `<selector>._domainkey.<domain>` host rather than adding a second record —
+   * `old_selector_retained` is false and the new TXT value must be published
+   * promptly, since signing switches to the new key immediately and the old TXT
+   * value will no longer match. The previous key is retired to a `retiring` state
+   * (retained, not revoked) so it can be revoked after the DNS propagation grace
+   * period.
+   *
+   * @example
+   * ```ts
+   * const response = await client.emailDomains.rotateDkim(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  rotateDkim(domainID: string, options?: RequestOptions): APIPromise<EmailDomainRotateDkimResponse> {
+    return this._client.post(path`/email_domains/${domainID}/rotate_dkim`, options);
+  }
 }
 
 export type EmailDomainsDefaultFlatPagination = DefaultFlatPagination<EmailDomain>;
@@ -401,6 +423,103 @@ export namespace EmailDomainRetrieveHealthResponse {
   }
 }
 
+export interface EmailDomainRotateDkimResponse {
+  /**
+   * Result of rotating a domain's DKIM key. The new key is active and signing
+   * switches to it immediately; the previous key is retired to a `retiring` state
+   * (retained, not revoked) so it can be revoked after the DNS propagation grace
+   * period. Selectors are fixed, so the DKIM DNS record's TXT value is replaced in
+   * place at the shared `<selector>._domainkey.<domain>` host —
+   * `old_selector_retained` is false and the returned dns_records carry the new
+   * value the customer must publish promptly.
+   */
+  data: EmailDomainRotateDkimResponse.Data;
+}
+
+export namespace EmailDomainRotateDkimResponse {
+  /**
+   * Result of rotating a domain's DKIM key. The new key is active and signing
+   * switches to it immediately; the previous key is retired to a `retiring` state
+   * (retained, not revoked) so it can be revoked after the DNS propagation grace
+   * period. Selectors are fixed, so the DKIM DNS record's TXT value is replaced in
+   * place at the shared `<selector>._domainkey.<domain>` host —
+   * `old_selector_retained` is false and the returned dns_records carry the new
+   * value the customer must publish promptly.
+   */
+  export interface Data {
+    /**
+     * The new active DKIM key.
+     */
+    dkim: Data.Dkim;
+
+    /**
+     * The DKIM DNS records the customer must publish, carrying the new key's TXT value
+     * with verification reset to pending.
+     */
+    dns_records: Array<EmailDomainsAPI.DNSRecord>;
+
+    domain: string;
+
+    domain_id: string;
+
+    /**
+     * False for this service: one selector is fixed per domain, so rotation replaces
+     * the TXT value at the existing \_domainkey host. There is no dual-selector
+     * overlap; publish the replacement TXT promptly because signing switches
+     * immediately.
+     */
+    old_selector_retained: boolean;
+
+    /**
+     * The retired previous key, or null when the domain had no active key before
+     * rotation. Retained in a `retiring` state so it can be revoked after the DNS
+     * propagation grace period.
+     */
+    previous_dkim_key: Data.PreviousDkimKey | null;
+
+    record_type: 'email_domain_dkim_rotation';
+  }
+
+  export namespace Data {
+    /**
+     * The new active DKIM key.
+     */
+    export interface Dkim {
+      id: string;
+
+      algorithm: 'rsa-sha256';
+
+      key_length: 2048;
+
+      selector: string;
+
+      status: 'active';
+
+      /**
+       * Monotonically increasing per-domain key version.
+       */
+      version: number;
+
+      activated_at?: string | null;
+    }
+
+    /**
+     * The retired previous key, or null when the domain had no active key before
+     * rotation. Retained in a `retiring` state so it can be revoked after the DNS
+     * propagation grace period.
+     */
+    export interface PreviousDkimKey {
+      id: string;
+
+      selector: string;
+
+      status: 'retiring' | 'revoked';
+
+      version: number;
+    }
+  }
+}
+
 export interface EmailDomainListParams extends DefaultFlatPaginationParams {
   /**
    * Partial match on domain name (case-insensitive)
@@ -506,6 +625,7 @@ export declare namespace EmailDomains {
     type EmailDomainVerification as EmailDomainVerification,
     type EmailDomainRetrieveDNSRecordsResponse as EmailDomainRetrieveDNSRecordsResponse,
     type EmailDomainRetrieveHealthResponse as EmailDomainRetrieveHealthResponse,
+    type EmailDomainRotateDkimResponse as EmailDomainRotateDkimResponse,
     type EmailDomainsDefaultFlatPagination as EmailDomainsDefaultFlatPagination,
     type EmailDomainListParams as EmailDomainListParams,
     type EmailDomainCreateParams as EmailDomainCreateParams,

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

@@ -12,6 +12,7 @@ export {
   type EmailDomainVerification,
   type EmailDomainRetrieveDNSRecordsResponse,
   type EmailDomainRetrieveHealthResponse,
+  type EmailDomainRotateDkimResponse,
   type EmailDomainListParams,
   type EmailDomainCreateParams,
   type EmailDomainDeleteParams,

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

@@ -165,9 +165,11 @@ export interface EmailWebhook {
 }
 
 /**
- * Event types a webhook may subscribe to. The union of email._ events (published
- * by email-api) and email_domain._ lifecycle events (published by this service).
- * An event not listed here can never be subscribed to and is silently dropped.
+ * Event types accepted by domain webhook subscriptions. Allowlists match the
+ * legacy event_type, not canonical_event_type. Of the 22 accepted types,
+ * email.sending is stored but intentionally not published. Cancellation,
+ * daily-limit failures, and system failures publish after commit when a matching
+ * domain webhook is configured.
  */
 export type EmailWebhookEvent =
   | 'email.scheduled'
@@ -184,11 +186,14 @@ export type EmailWebhookEvent =
   | 'email.clicked'
   | 'email.unsubscribed'
   | 'email.received'
+  | 'email.cancelled'
+  | 'email.daily_limit_exceeded'
   | 'email_domain.created'
   | 'email_domain.verified'
   | 'email_domain.degraded'
   | 'email_domain.suspended'
-  | 'email_domain.deleted';
+  | 'email_domain.deleted'
+  | 'email_domain.dkim_rotated';
 
 export interface EmailWebhookResponse {
   data: EmailWebhook;

package/src/resources/email-events.ts

@@ -2,9 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import * as EmailEventsAPI from './email-events';
-import * as DraftsAPI from './email-inboxes/drafts';
 import { APIPromise } from '../core/api-promise';
-import { EmailCursorPagination, type EmailCursorPaginationParams, PagePromise } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 
 /**
@@ -13,16 +11,26 @@ import { RequestOptions } from '../internal/request-options';
 export class EmailEvents extends APIResource {
   /**
    * Lists account-level email events sorted oldest first by
-   * `occurred_at asc, id asc`.
+   * `occurred_at asc, id asc`. Each row contains a legacy email.-prefixed event_type
+   * and an additive canonical_event_type. Gateway rejection renders email.failed
+   * with canonical email.gw_reject; ambiguous injection timeout renders
+   * email.injection_timeout in both; MTA expiration renders email.bounced with
+   * canonical email.expired. Message-scoped queued, sending, sandbox, cancelled, and
+   * daily_limit_exceeded rows fan out per durable recipient with stable derived IDs
+   * matching webhook delivery. Scheduled is the cardinality exception: account
+   * polling retains one message-scoped scheduled row with its stored event ID, while
+   * scheduled webhook publication fans out per recipient with derived IDs; reconcile
+   * scheduled events by message ID, event type, and occurrence time rather than
+   * event UUID. Recipient-scoped stored rows retain their stored UUIDs across
+   * polling and webhook delivery. Legacy names are derived from stored rows; an
+   * AdminBounce row stored as failed renders email.failed in polling while its
+   * webhook retains email.bounced, both with canonical email.failed.
    */
   list(
     query: EmailEventListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<EmailEventListResponsesEmailCursorPagination, EmailEventListResponse> {
-    return this._client.getAPIList('/email_events', EmailCursorPagination<EmailEventListResponse>, {
-      query,
-      ...options,
-    });
+  ): APIPromise<EmailEventListResponse> {
+    return this._client.get('/email_events', { query, ...options });
   }
 
   /**
@@ -37,8 +45,14 @@ export class EmailEvents extends APIResource {
   }
 }
 
-export type EmailEventListResponsesEmailCursorPagination = EmailCursorPagination<EmailEventListResponse>;
-
+/**
+ * Bare stored event names returned by message history. In addition to the normal
+ * send and delivery lifecycle, polling can expose suppression, scan, and
+ * quarantine lifecycle rows. Sharp canonical names gw_reject, injection_timeout,
+ * and expired distinguish gateway rejection, ambiguous injection timeout, and MTA
+ * expiration. The failed and bounced names remain valid for system/admin failures
+ * and hard bounces respectively. Existing stored rows retain their original names.
+ */
 export type EmailEventType =
   | 'queued'
   | 'deferred'
@@ -51,11 +65,29 @@ export type EmailEventType =
   | 'delivered'
   | 'bounced'
   | 'complained'
+  | 'suppressed'
   | 'rejected'
   | 'opened'
   | 'clicked'
   | 'unsubscribed'
-  | 'daily_limit_exceeded';
+  | 'daily_limit_exceeded'
+  | 'scan_deferred'
+  | 'quarantined'
+  | 'quarantine_released'
+  | 'quarantine_release_dispatched'
+  | 'quarantine_rejected'
+  | 'quarantine_expired'
+  | 'gw_reject'
+  | 'injection_timeout'
+  | 'expired';
+
+export interface EmailWebhookRecipient {
+  email: string;
+
+  kind?: 'to' | 'cc' | 'bcc';
+
+  name?: string | null;
+}
 
 export interface TimeRange {
   from: string | null;
@@ -64,38 +96,168 @@ export interface TimeRange {
 }
 
 export interface EmailEventListResponse {
-  id: string;
+  data: Array<EmailEventListResponse.Data>;
 
-  email_id: string;
+  meta: EmailEventListResponse.Meta;
+}
 
-  occurred_at: string;
+export namespace EmailEventListResponse {
+  /**
+   * An account-polling event. The envelope is webhook-shaped, but polling preserves
+   * stored-event cardinality: queued, sending, sandbox, cancelled, and
+   * daily_limit_exceeded message events fan out per recipient; scheduled remains one
+   * message-scoped row. Payload fields vary among recipient-scoped, message-scoped,
+   * and minimal fallback rows.
+   */
+  export interface Data {
+    /**
+     * Event UUID.
+     */
+    id: string;
 
-  record_type: 'email_event';
+    /**
+     * Additive canonical outcome name, prefixed with `email.`. Gateway rejection is
+     * `email.gw_reject`, ambiguous injection timeout is `email.injection_timeout`, and
+     * MTA expiration is `email.expired`. Unchanged outcomes retain their names.
+     * Existing stored rows are translated only when recorded payload evidence proves
+     * the outcome; a legacy failed row is not guessed or sharpened.
+     */
+    canonical_event_type: string;
 
-  type: EmailEventType;
+    /**
+     * Legacy customer-visible event name, prefixed with `email.`. Gateway rejections
+     * render `email.failed`; MTA expirations render `email.bounced`. Webhook
+     * subscription allowlists match the legacy name.
+     */
+    event_type: string;
 
-  /**
-   * Summary of the associated email message. Present when the email_message preload
-   * is available.
-   */
-  email?: EmailEventListResponse.Email;
+    occurred_at: string;
 
-  payload?: { [key: string]: unknown };
-}
+    /**
+     * Payload returned by GET /email_events. Every row includes id, status, and
+     * occurred_at. Recipient-scoped rows also include recipient_id, from, subject, and
+     * exactly one object-valued to, cc, or bcc field. Legacy or message-scoped rows
+     * can omit recipient_id and use object-valued or string-valued to/cc fields,
+     * including an empty string when no address exists; bcc is redacted. If the
+     * related message or recipient cannot be loaded, the minimal fallback can omit
+     * from, subject, and recipient fields. Additional persisted public evidence can be
+     * present.
+     */
+    payload: Data.Payload;
 
-export namespace EmailEventListResponse {
-  /**
-   * Summary of the associated email message. Present when the email_message preload
-   * is available.
-   */
-  export interface Email {
-    cc: Array<DraftsAPI.EmailAddress>;
+    /**
+     * Durable email recipient UUID. Present for recipient-scoped events, including
+     * each queued, sending, sandbox, cancelled, and daily_limit_exceeded fan-out
+     * event.
+     */
+    recipient_id?: string;
+  }
+
+  export namespace Data {
+    /**
+     * Payload returned by GET /email_events. Every row includes id, status, and
+     * occurred_at. Recipient-scoped rows also include recipient_id, from, subject, and
+     * exactly one object-valued to, cc, or bcc field. Legacy or message-scoped rows
+     * can omit recipient_id and use object-valued or string-valued to/cc fields,
+     * including an empty string when no address exists; bcc is redacted. If the
+     * related message or recipient cannot be loaded, the minimal fallback can omit
+     * from, subject, and recipient fields. Additional persisted public evidence can be
+     * present.
+     */
+    export interface Payload {
+      /**
+       * Email message UUID.
+       */
+      id: string;
+
+      occurred_at: string;
 
-    from: DraftsAPI.EmailAddress;
+      /**
+       * Stored event outcome slug, not the authoritative recipient status. Account
+       * polling returns the stored name, including suppression, scan, and quarantine
+       * lifecycle names. Webhooks retain legacy payload names: gateway rejections use
+       * failed and MTA expirations use bounced. New sharp stored rows can expose
+       * gw_reject, injection_timeout, or expired. Use the envelope canonical_event_type
+       * to identify the outcome across surfaces.
+       */
+      status:
+        | 'queued'
+        | 'deferred'
+        | 'scheduled'
+        | 'cancelled'
+        | 'sandbox'
+        | 'sending'
+        | 'sent'
+        | 'failed'
+        | 'delivered'
+        | 'bounced'
+        | 'complained'
+        | 'suppressed'
+        | 'rejected'
+        | 'opened'
+        | 'clicked'
+        | 'unsubscribed'
+        | 'daily_limit_exceeded'
+        | 'scan_deferred'
+        | 'quarantined'
+        | 'quarantine_released'
+        | 'quarantine_release_dispatched'
+        | 'quarantine_rejected'
+        | 'quarantine_expired'
+        | 'gw_reject'
+        | 'injection_timeout'
+        | 'expired';
+
+      bcc?: EmailEventsAPI.EmailWebhookRecipient | 'redacted';
 
-    subject: string;
+      /**
+       * Legacy message-scoped address, or an empty string when absent.
+       */
+      cc?: EmailEventsAPI.EmailWebhookRecipient | string;
 
-    to: Array<DraftsAPI.EmailAddress>;
+      /**
+       * Sender projection in account event polling. The display name is explicitly null
+       * when the message has no sender name.
+       */
+      from?: Payload.From;
+
+      /**
+       * Durable email recipient UUID. Present for recipient-scoped events.
+       */
+      recipient_id?: string;
+
+      subject?: string;
+
+      /**
+       * Legacy message-scoped address, or an empty string when absent.
+       */
+      to?: EmailEventsAPI.EmailWebhookRecipient | string;
+
+      [k: string]: unknown;
+    }
+
+    export namespace Payload {
+      /**
+       * Sender projection in account event polling. The display name is explicitly null
+       * when the message has no sender name.
+       */
+      export interface From {
+        email: string;
+
+        name: string | null;
+      }
+    }
+  }
+
+  export interface Meta {
+    page_size: number;
+
+    time_range: EmailEventsAPI.TimeRange;
+
+    /**
+     * Cursor for the next page, when more results are available.
+     */
+    page_cursor?: string;
   }
 }
 
@@ -194,7 +356,7 @@ export namespace EmailEventRetrieveStatsResponse {
   }
 }
 
-export interface EmailEventListParams extends EmailCursorPaginationParams {
+export interface EmailEventListParams {
   /**
    * Filter events for a specific email message UUID. Invalid UUID values are
    * silently ignored (no filter applied).
@@ -205,6 +367,17 @@ export interface EmailEventListParams extends EmailCursorPaginationParams {
    * Comma-separated list of event types to include. Also accepts repeated query
    * parameters (e.g. event_type=delivered&event_type=bounced). Unknown values return
    * no matches.
+   *
+   * Dual-name compatibility: values are accepted bare or `email.`-prefixed. A legacy
+   * value keeps matching the rows it matched pre-rename — no widening: `failed` also
+   * matches the rows that now store the canonical names of the outcomes it covered
+   * (`gw_reject`, `injection_timeout`, `expired`); `bounced` matches stored
+   * `bounced` rows only (recipient-scoped Expirations stored `failed` pre-rename and
+   * never matched `bounced`, so `expired` is deliberately not a `bounced`
+   * expansion). A canonical value matches its own rows plus legacy rows whose
+   * recorded payload evidence proves that outcome (`expired` also surfaces legacy
+   * `bounced` rows with `bounce_category: transient`). The additive
+   * `canonical_event_type` field in each response row names the canonical outcome.
    */
   event_type?: string | Array<string>;
 
@@ -213,6 +386,18 @@ export interface EmailEventListParams extends EmailCursorPaginationParams {
    */
   from?: string;
 
+  /**
+   * Number of results to return. Defaults to 25; maximum is 100. Invalid values are
+   * clamped to the valid range.
+   */
+  page_size?: number;
+
+  /**
+   * Opaque URL-safe Base64 cursor returned by a previous event list response. The
+   * legacy `page[after]` and flat `page_cursor` forms are also accepted.
+   */
+  'page[cursor]'?: string;
+
   /**
    * Inclusive ISO 8601 end timestamp. When `from` is provided without `to`, defaults
    * to `from + 30 days`.
@@ -236,10 +421,10 @@ export interface EmailEventRetrieveStatsParams {
 export declare namespace EmailEvents {
   export {
     type EmailEventType as EmailEventType,
+    type EmailWebhookRecipient as EmailWebhookRecipient,
     type TimeRange as TimeRange,
     type EmailEventListResponse as EmailEventListResponse,
     type EmailEventRetrieveStatsResponse as EmailEventRetrieveStatsResponse,
-    type EmailEventListResponsesEmailCursorPagination as EmailEventListResponsesEmailCursorPagination,
     type EmailEventListParams as EmailEventListParams,
     type EmailEventRetrieveStatsParams as EmailEventRetrieveStatsParams,
   };

package/src/resources/email-inboxes/drafts.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as EmailEventsAPI from '../email-events';
 import * as EmailMessagesAPI from '../email-messages/email-messages';
 import { APIPromise } from '../../core/api-promise';
 import {
@@ -354,10 +355,15 @@ export interface EmailMessage {
 
   created_at: string;
 
-  events: Array<EmailMessagesAPI.MessageEvent>;
+  events: Array<EmailMessage.Event>;
 
   from: EmailAddress;
 
+  /**
+   * Customer-supplied metadata stored with the message.
+   */
+  metadata: { [key: string]: unknown };
+
   record_type: 'email_message';
 
   reply_to: string | null;
@@ -386,6 +392,11 @@ export interface EmailMessage {
 
   subject: string;
 
+  /**
+   * Customer-supplied tags stored with the message.
+   */
+  tags: Array<string>;
+
   template_id: string | null;
 
   template_variables: { [key: string]: unknown };
@@ -460,6 +471,26 @@ export namespace EmailMessage {
      */
     url: string | null;
   }
+
+  /**
+   * An event embedded in a message response. The dedicated per-message events
+   * endpoint additionally returns event_type and canonical_event_type.
+   */
+  export interface Event {
+    occurred_at: string;
+
+    /**
+     * Bare stored event names returned by message history. In addition to the normal
+     * send and delivery lifecycle, polling can expose suppression, scan, and
+     * quarantine lifecycle rows. Sharp canonical names gw_reject, injection_timeout,
+     * and expired distinguish gateway rejection, ambiguous injection timeout, and MTA
+     * expiration. The failed and bounced names remain valid for system/admin failures
+     * and hard bounces respectively. Existing stored rows retain their original names.
+     */
+    type: EmailEventsAPI.EmailEventType;
+
+    payload?: { [key: string]: unknown };
+  }
 }
 
 export interface EmailMessageResponse {