telnyx 7.22.0 → 7.24.0

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

@@ -50,9 +50,9 @@ export class EmailMessages extends APIResource {
   }
 
   /**
-   * Lists messages sorted newest first by `created_at desc, id desc`. No filters
-   * other than cursor pagination are implemented. The legacy `/v2/emails` GET route
-   * is a backward-compatible alias for this operation.
+   * Lists messages sorted newest first by `created_at desc, id desc`. Tags and
+   * metadata filters compose with cursor pagination. The legacy `/v2/emails` GET
+   * route is a backward-compatible alias for this operation.
    *
    * @example
    * ```ts
@@ -109,9 +109,14 @@ export class EmailMessages extends APIResource {
   }
 
   /**
-   * Creates up to 1,000 email messages in a single request. Each message is
-   * validated and sent independently; per-message failures do not affect other
-   * messages in the batch. All responses use 207 Multi-Status.
+   * Creates up to 1,000 email messages in a single request. Request-wide admission
+   * checks run first and can reject the whole batch before message creation. After
+   * those checks pass, each message is validated and sent independently; item-level
+   * failures do not affect other messages, and the processed batch returns 207
+   * Multi-Status. Per-message failures include validation errors; when a template
+   * has `strict_variables` enabled, a missing required variable produces a per-item
+   * `unprocessable_entity` error naming that variable while the other messages
+   * continue.
    *
    * @example
    * ```ts
@@ -150,6 +155,15 @@ export class EmailMessages extends APIResource {
    * `occurred_at asc, id asc`. The legacy `/v2/emails/{id}/events` GET route is a
    * backward-compatible alias.
    *
+   * For compatibility, each event carries the legacy customer-visible `event_type`
+   * (`email.`-prefixed), the additive `canonical_event_type` (`email.`-prefixed),
+   * and the deprecated `type` duplicate — whose value keeps the exact legacy format:
+   * the bare stored event name, never `email.`-prefixed. Gateway rejections render
+   * `email.failed` + canonical `email.gw_reject`; MTA expirations render
+   * `email.bounced` + canonical `email.expired`; every unchanged outcome carries
+   * identical `event_type` and `canonical_event_type` values (and `type` keeps the
+   * stored name).
+   *
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
@@ -214,14 +228,39 @@ export class EmailMessages extends APIResource {
    *
    * @example
    * ```ts
-   * const emailMessage = await client.emailMessages.retrieve(
-   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   * );
+   * const emailMessageDetailResponse =
+   *   await client.emailMessages.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
    * ```
    */
-  retrieve(id: string, options?: RequestOptions): APIPromise<EmailMessageRetrieveResponse> {
+  retrieve(id: string, options?: RequestOptions): APIPromise<EmailMessageDetailResponse> {
     return this._client.get(path`/email_messages/${id}`, options);
   }
+
+  /**
+   * Moves an existing scheduled email to a new future send time. Only the delivery
+   * time (`scheduled_at`) changes; the message ID, content, recipients, tags, and
+   * metadata remain unchanged. Returns `409 Conflict` if the message is no longer
+   * scheduled or its scheduled-send worker has already started processing it. This
+   * route emits no dedicated `rescheduled` event.
+   *
+   * @example
+   * ```ts
+   * const emailMessageDetailResponse =
+   *   await client.emailMessages.updateSchedule(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     { scheduled_at: '2099-08-07T14:30:00Z' },
+   *   );
+   * ```
+   */
+  updateSchedule(
+    emailID: string,
+    body: EmailMessageUpdateScheduleParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailMessageDetailResponse> {
+    return this._client.patch(path`/email_messages/${emailID}/schedule`, { body, ...options });
+  }
 }
 
 export type MessageEventsEmailCursorPagination = EmailCursorPagination<MessageEvent>;
@@ -256,9 +295,57 @@ export interface AttachmentRequest {
 
 export type EmailAddressInput = string | DraftsAPI.EmailAddress;
 
+export interface EmailMessageDetailResponse {
+  data: EmailMessageDetailResponse.Data;
+}
+
+export namespace EmailMessageDetailResponse {
+  export interface Data extends DraftsAPI.EmailMessage {
+    /**
+     * HTML body submitted for the message.
+     */
+    html_body: string | null;
+
+    /**
+     * Plain-text body submitted for the message.
+     */
+    text_body: string | null;
+  }
+}
+
+/**
+ * An event on the per-message events endpoint. The legacy event_type and additive
+ * canonical_event_type are email.-prefixed. The deprecated type preserves the bare
+ * stored event name for compatibility.
+ */
 export interface MessageEvent {
+  /**
+   * 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;
+
+  /**
+   * 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;
+
   occurred_at: string;
 
+  /**
+   * @deprecated 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 };
@@ -302,24 +389,6 @@ export interface TrackingSettings {
   open_tracking?: boolean;
 }
 
-export interface EmailMessageRetrieveResponse {
-  data: EmailMessageRetrieveResponse.Data;
-}
-
-export namespace EmailMessageRetrieveResponse {
-  export interface Data extends DraftsAPI.EmailMessage {
-    /**
-     * HTML body submitted for the message.
-     */
-    html_body: string | null;
-
-    /**
-     * Plain-text body submitted for the message.
-     */
-    text_body: string | null;
-  }
-}
-
 export interface EmailMessageBatchResponse {
   data: Array<DraftsAPI.EmailMessage>;
 
@@ -367,7 +436,26 @@ export interface EmailMessageDeleteAllParams {
   address: string;
 }
 
-export interface EmailMessageListParams extends EmailCursorPaginationParams {}
+export interface EmailMessageListParams extends EmailCursorPaginationParams {
+  /**
+   * Metadata containment filter, supplied as a JSON object or comma-separated
+   * `key=value` pairs. All supplied key/value pairs must be contained in the message
+   * metadata. An empty value or empty JSON object omits the filter. Malformed
+   * values, valid non-object JSON, pairs without `=`, empty keys, and
+   * non-string/nested query shapes return HTTP 400.
+   */
+  'filter[metadata]'?: string;
+
+  /**
+   * Comma-separated tags. Each segment is trimmed, and messages having at least one
+   * supplied tag are returned; matching is exact and case-sensitive after trimming.
+   * Because commas delimit values and surrounding whitespace is removed, this filter
+   * cannot represent stored tags containing literal commas or leading/trailing
+   * whitespace. An empty value omits the filter. Empty segments and
+   * non-string/nested query shapes return HTTP 400.
+   */
+  'filter[tags]'?: string;
+}
 
 export interface EmailMessageCreateParams {
   /**
@@ -459,7 +547,9 @@ export interface EmailMessageCreateParams {
   inline_css?: boolean;
 
   /**
-   * Body param: Custom metadata. Write-only; not returned in responses.
+   * Body param: Custom metadata key/value pairs. Stored on the message, returned on
+   * message responses, and propagated to Email Detail Records. Usable in
+   * `filter[metadata]` when listing messages.
    */
   metadata?: { [key: string]: unknown };
 
@@ -482,15 +572,40 @@ export interface EmailMessageCreateParams {
   reply_to_all?: boolean | null;
 
   /**
-   * Body param
+   * Body param: Validates and accepts the message without injecting it into the MTA
+   * or outbound Kafka path. Nothing is delivered: sandbox records are non-billable,
+   * consume no daily-send-limit quota, and feed no delivery-reputation signals.
+   *
+   * The reserved sandbox test-recipient domain is `test.telnyx.com`. In sandbox
+   * mode, these addresses produce deterministic recipient-scoped lifecycle events:
+   *
+   * - `delivered@test.telnyx.com`: queued -> sending -> sent -> delivered
+   * - `hard-bounce@test.telnyx.com`: queued -> sending -> sent -> bounced
+   *   (permanent)
+   * - `soft-bounce@test.telnyx.com`: queued -> sending -> sent -> bounced
+   *   (transient)
+   * - `complaint@test.telnyx.com`: queued -> sending -> sent -> complained
+   * - `suppressed@test.telnyx.com`: queued -> suppressed
+   * - `invalid@test.telnyx.com`: queued -> sending -> failed (invalid recipient)
+   * - `dkim-fail@test.telnyx.com`: queued -> sending -> failed (DKIM unavailable)
+   * - `rate-limit@test.telnyx.com`: queued -> sending -> failed (rate limit
+   *   exceeded)
+   *
+   * Matching is case-insensitive for both the local part and the domain and requires
+   * the exact domain `test.telnyx.com` — subdomains and other domains do not match.
+   * Mixed sandbox sends simulate only reserved test recipients; other recipients
+   * retain ordinary sandbox behavior (accepted, no delivery attempted). Hard-bounce
+   * and complaint outcomes also use the normal automatic-suppression pipeline.
+   * Non-sandbox sends to these addresses use the normal delivery path.
    */
   sandbox_mode?: boolean;
 
   /**
-   * Body param: Future ISO 8601 time to schedule sending. Invalid or past timestamps
-   * are silently ignored and the email is sent immediately. The legacy alias
-   * `send_at` is still accepted for backward compatibility; when both are provided,
-   * `scheduled_at` wins.
+   * Body param: Future ISO 8601 delivery time. Invalid or non-future timestamps are
+   * rejected. Single sends return HTTP 422; in batch sends the invalid item is
+   * reported in the 207 per-item errors while other items continue. `send_at`
+   * remains a deprecated request alias. A non-null `scheduled_at` takes precedence
+   * over `send_at`; when `scheduled_at` is omitted or null, `send_at` is used.
    */
   scheduled_at?: string | null;
 
@@ -507,8 +622,9 @@ export interface EmailMessageCreateParams {
   subject?: string;
 
   /**
-   * Body param: Tags for categorization and reporting. Stored on the message and
-   * propagated to Email Detail Records. Not returned in API responses.
+   * Body param: Tags for categorization and filtering. Stored on the message,
+   * returned on message responses, and propagated to Email Detail Records. Usable in
+   * `filter[tags]` when listing messages.
    */
   tags?: Array<string>;
 
@@ -520,7 +636,10 @@ export interface EmailMessageCreateParams {
   /**
    * Body param: Variables for Liquid template rendering. Non-object values may cause
    * a 422 validation error on message creation, but are silently treated as an empty
-   * object for template rendering.
+   * object for template rendering. When the template enables `strict_variables`, a
+   * missing required variable fails the request with 422 (single send) or a per-item
+   * `unprocessable_entity` error (batch) naming the variable; no message is
+   * persisted for the failed item.
    */
   template_variables?: { [key: string]: unknown };
 
@@ -558,8 +677,13 @@ export interface EmailMessageBatchParams {
   messages: Array<EmailMessageBatchParams.Message>;
 
   /**
-   * Body param: Applies sandbox mode to all messages in the batch. Overrides any
-   * per-message sandbox_mode in the messages array.
+   * Body param: Applies sandbox mode to all messages in the batch and overrides any
+   * per-message `sandbox_mode` value — each message's effective `sandbox_mode` is
+   * exactly this envelope value. Reserved recipients at `test.telnyx.com` produce
+   * the deterministic event chains documented on CreateEmailRequest.sandbox_mode; no
+   * batch item is injected into the MTA or outbound Kafka path. Sandbox batch items
+   * are non-billable, consume no daily-send-limit quota, and feed no
+   * delivery-reputation signals.
    */
   sandbox_mode?: boolean;
 
@@ -629,7 +753,9 @@ export namespace EmailMessageBatchParams {
     inline_css?: boolean;
 
     /**
-     * Custom metadata. Write-only; not returned in responses.
+     * Custom metadata key/value pairs. Stored on the message, returned on message
+     * responses, and propagated to Email Detail Records. Usable in `filter[metadata]`
+     * when listing messages.
      */
     metadata?: { [key: string]: unknown };
 
@@ -639,13 +765,21 @@ export namespace EmailMessageBatchParams {
      */
     reply_to?: EmailMessagesAPI.EmailAddressInput;
 
+    /**
+     * Per-message sandbox flag. The batch-level `sandbox_mode` envelope value is
+     * authoritative: it overwrites every message's `sandbox_mode` before processing,
+     * including the `false` default when the envelope omits the field. A per-item
+     * `sandbox_mode: true` inside a non-sandbox batch is therefore a real send. Set
+     * the envelope field to run any batch item in sandbox mode.
+     */
     sandbox_mode?: boolean;
 
     /**
-     * Future ISO 8601 time to schedule sending. Invalid or past timestamps are
-     * silently ignored and the email is sent immediately. The legacy alias `send_at`
-     * is still accepted for backward compatibility; when both are provided,
-     * `scheduled_at` wins.
+     * Future ISO 8601 delivery time. Invalid or non-future timestamps are rejected.
+     * Single sends return HTTP 422; in batch sends the invalid item is reported in the
+     * 207 per-item errors while other items continue. `send_at` remains a deprecated
+     * request alias. A non-null `scheduled_at` takes precedence over `send_at`; when
+     * `scheduled_at` is omitted or null, `send_at` is used.
      */
     scheduled_at?: string | null;
 
@@ -662,8 +796,9 @@ export namespace EmailMessageBatchParams {
     subject?: string;
 
     /**
-     * Tags for categorization and reporting. Stored on the message and propagated to
-     * Email Detail Records. Not returned in API responses.
+     * Tags for categorization and filtering. Stored on the message, returned on
+     * message responses, and propagated to Email Detail Records. Usable in
+     * `filter[tags]` when listing messages.
      */
     tags?: Array<string>;
 
@@ -672,7 +807,10 @@ export namespace EmailMessageBatchParams {
     /**
      * Variables for Liquid template rendering. Non-object values may cause a 422
      * validation error on message creation, but are silently treated as an empty
-     * object for template rendering.
+     * object for template rendering. When the template enables `strict_variables`, a
+     * missing required variable fails the request with 422 (single send) or a per-item
+     * `unprocessable_entity` error (batch) naming the variable; no message is
+     * persisted for the failed item.
      */
     template_variables?: { [key: string]: unknown };
 
@@ -692,16 +830,23 @@ export namespace EmailMessageBatchParams {
 
 export interface EmailMessageRetrieveEventsParams extends EmailCursorPaginationParams {}
 
+export interface EmailMessageUpdateScheduleParams {
+  /**
+   * New ISO 8601 delivery time. Must be strictly in the future.
+   */
+  scheduled_at: string;
+}
+
 EmailMessages.Recipients = Recipients;
 
 export declare namespace EmailMessages {
   export {
     type AttachmentRequest as AttachmentRequest,
     type EmailAddressInput as EmailAddressInput,
+    type EmailMessageDetailResponse as EmailMessageDetailResponse,
     type MessageEvent as MessageEvent,
     type SuppressedRecipient as SuppressedRecipient,
     type TrackingSettings as TrackingSettings,
-    type EmailMessageRetrieveResponse as EmailMessageRetrieveResponse,
     type EmailMessageBatchResponse as EmailMessageBatchResponse,
     type MessageEventsEmailCursorPagination as MessageEventsEmailCursorPagination,
     type EmailMessageDeleteAllParams as EmailMessageDeleteAllParams,
@@ -709,6 +854,7 @@ export declare namespace EmailMessages {
     type EmailMessageCreateParams as EmailMessageCreateParams,
     type EmailMessageBatchParams as EmailMessageBatchParams,
     type EmailMessageRetrieveEventsParams as EmailMessageRetrieveEventsParams,
+    type EmailMessageUpdateScheduleParams as EmailMessageUpdateScheduleParams,
   };
 
   export {

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

@@ -4,16 +4,17 @@ export {
   EmailMessages,
   type AttachmentRequest,
   type EmailAddressInput,
+  type EmailMessageDetailResponse,
   type MessageEvent,
   type SuppressedRecipient,
   type TrackingSettings,
-  type EmailMessageRetrieveResponse,
   type EmailMessageBatchResponse,
   type EmailMessageDeleteAllParams,
   type EmailMessageListParams,
   type EmailMessageCreateParams,
   type EmailMessageBatchParams,
   type EmailMessageRetrieveEventsParams,
+  type EmailMessageUpdateScheduleParams,
   type MessageEventsEmailCursorPagination,
 } from './email-messages';
 export {

package/src/resources/email-messages/recipients.ts

@@ -101,7 +101,9 @@ export interface EmailRecipient {
     | 'bounced'
     | 'failed'
     | 'gw_reject'
-    | 'cancelled';
+    | 'cancelled'
+    | 'injection_timeout'
+    | 'expired';
 
   delivered_at?: string | null;
 
@@ -142,7 +144,9 @@ export interface RecipientListParams extends EmailCursorPaginationParams {
     | 'bounced'
     | 'failed'
     | 'gw_reject'
-    | 'cancelled';
+    | 'cancelled'
+    | 'injection_timeout'
+    | 'expired';
 }
 
 export interface RecipientRetrieveParams {