telnyx 7.12.0 → 7.13.0

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

@@ -0,0 +1,267 @@
+// 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 { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Per-domain webhook endpoints with event subscriptions
+ */
+export class Webhooks extends APIResource {
+  /**
+   * List webhooks for an email domain
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const emailWebhook of client.emailDomains.webhooks.list(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    domainID: string,
+    query: WebhookListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EmailWebhooksDefaultFlatPagination, EmailWebhook> {
+    return this._client.getAPIList(
+      path`/email_domains/${domainID}/webhooks`,
+      DefaultFlatPagination<EmailWebhook>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Creates a webhook endpoint subscribed to a specific allowlist of event types.
+   * Both `email.*` events (published by email-api) and `email_domain.*` events
+   * (published by this service) flow through the same webhooks.
+   *
+   * @example
+   * ```ts
+   * const emailWebhookResponse =
+   *   await client.emailDomains.webhooks.create(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       events: [
+   *         'email.sent',
+   *         'email.delivered',
+   *         'email.bounced',
+   *       ],
+   *       url: 'https://example.com/webhooks/email',
+   *     },
+   *   );
+   * ```
+   */
+  create(
+    domainID: string,
+    body: WebhookCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailWebhookResponse> {
+    return this._client.post(path`/email_domains/${domainID}/webhooks`, { body, ...options });
+  }
+
+  /**
+   * Delete a webhook
+   *
+   * @example
+   * ```ts
+   * const emailWebhookResponse =
+   *   await client.emailDomains.webhooks.delete(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     { domain_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+   *   );
+   * ```
+   */
+  delete(
+    id: string,
+    params: WebhookDeleteParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailWebhookResponse> {
+    const { domain_id } = params;
+    return this._client.delete(path`/email_domains/${domain_id}/webhooks/${id}`, options);
+  }
+
+  /**
+   * Retrieve a webhook
+   *
+   * @example
+   * ```ts
+   * const emailWebhookResponse =
+   *   await client.emailDomains.webhooks.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     { domain_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+   *   );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: WebhookRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailWebhookResponse> {
+    const { domain_id } = params;
+    return this._client.get(path`/email_domains/${domain_id}/webhooks/${id}`, options);
+  }
+
+  /**
+   * Update a webhook's URL and/or event subscription. A webhook is bound to its
+   * domain — `domain_id` is not mutable.
+   *
+   * @example
+   * ```ts
+   * const emailWebhookResponse =
+   *   await client.emailDomains.webhooks.update(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       domain_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *       events: [
+   *         'email.sent',
+   *         'email.delivered',
+   *         'email.opened',
+   *       ],
+   *     },
+   *   );
+   * ```
+   */
+  update(
+    id: string,
+    params: WebhookUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<EmailWebhookResponse> {
+    const { domain_id, ...body } = params;
+    return this._client.patch(path`/email_domains/${domain_id}/webhooks/${id}`, { body, ...options });
+  }
+}
+
+export type EmailWebhooksDefaultFlatPagination = DefaultFlatPagination<EmailWebhook>;
+
+export interface EmailWebhook {
+  id: string;
+
+  created_at: string;
+
+  domain_id: string;
+
+  /**
+   * Allowlist of event types delivered to this webhook. At least one event is
+   * required — there is no default-to-all.
+   */
+  events: Array<EmailWebhookEvent>;
+
+  record_type: 'email_webhook';
+
+  updated_at: string;
+
+  /**
+   * HTTPS endpoint to deliver subscribed events to.
+   */
+  url: string;
+}
+
+/**
+ * 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.
+ */
+export type EmailWebhookEvent =
+  | 'email.scheduled'
+  | 'email.sandbox'
+  | 'email.queued'
+  | 'email.sending'
+  | 'email.sent'
+  | 'email.delivered'
+  | 'email.deferred'
+  | 'email.bounced'
+  | 'email.failed'
+  | 'email.complained'
+  | 'email.opened'
+  | 'email.clicked'
+  | 'email.unsubscribed'
+  | 'email.received'
+  | 'email_domain.created'
+  | 'email_domain.verified'
+  | 'email_domain.degraded'
+  | 'email_domain.suspended'
+  | 'email_domain.deleted';
+
+export interface EmailWebhookResponse {
+  data: EmailWebhook;
+}
+
+export interface OffsetPaginationMeta {
+  page_number: number;
+
+  page_size: number;
+
+  total_pages: number;
+
+  total_results: number;
+}
+
+export interface WebhookListParams extends DefaultFlatPaginationParams {
+  /**
+   * Field to sort by. Prefix with `-` for descending order.
+   */
+  sort?: 'created_at' | '-created_at';
+}
+
+export interface WebhookCreateParams {
+  /**
+   * At least one event type is required.
+   */
+  events: Array<EmailWebhookEvent>;
+
+  /**
+   * HTTPS endpoint to deliver subscribed events to.
+   */
+  url: string;
+}
+
+export interface WebhookDeleteParams {
+  /**
+   * Email domain UUID
+   */
+  domain_id: string;
+}
+
+export interface WebhookRetrieveParams {
+  /**
+   * Email domain UUID
+   */
+  domain_id: string;
+}
+
+export interface WebhookUpdateParams {
+  /**
+   * Path param: Email domain UUID
+   */
+  domain_id: string;
+
+  /**
+   * Body param
+   */
+  events?: Array<EmailWebhookEvent>;
+
+  /**
+   * Body param
+   */
+  url?: string;
+}
+
+export declare namespace Webhooks {
+  export {
+    type EmailWebhook as EmailWebhook,
+    type EmailWebhookEvent as EmailWebhookEvent,
+    type EmailWebhookResponse as EmailWebhookResponse,
+    type OffsetPaginationMeta as OffsetPaginationMeta,
+    type EmailWebhooksDefaultFlatPagination as EmailWebhooksDefaultFlatPagination,
+    type WebhookListParams as WebhookListParams,
+    type WebhookCreateParams as WebhookCreateParams,
+    type WebhookDeleteParams as WebhookDeleteParams,
+    type WebhookRetrieveParams as WebhookRetrieveParams,
+    type WebhookUpdateParams as WebhookUpdateParams,
+  };
+}

package/src/resources/email-domains.ts

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

package/src/resources/email-events.ts

@@ -0,0 +1,269 @@
+// 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 DraftsAPI from './email-inboxes/drafts';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Retrieve account-level email events and event statistics.
+ */
+export class EmailEvents extends APIResource {
+  /**
+   * Lists account-level email events sorted oldest first by
+   * `occurred_at asc, id asc`.
+   */
+  list(
+    query: EmailEventListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EmailEventListResponse> {
+    return this._client.get('/email_events', { query, ...options });
+  }
+
+  /**
+   * Returns counts and rates for email events over a time range. The default start
+   * time is 30 days ago.
+   */
+  retrieveStats(
+    query: EmailEventRetrieveStatsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EmailEventRetrieveStatsResponse> {
+    return this._client.get('/email_events/stats', { query, ...options });
+  }
+}
+
+export type EmailEventType =
+  | 'queued'
+  | 'deferred'
+  | 'scheduled'
+  | 'cancelled'
+  | 'sandbox'
+  | 'sending'
+  | 'sent'
+  | 'failed'
+  | 'delivered'
+  | 'bounced'
+  | 'complained'
+  | 'rejected'
+  | 'opened'
+  | 'clicked'
+  | 'unsubscribed'
+  | 'daily_limit_exceeded';
+
+export interface TimeRange {
+  from: string | null;
+
+  to: string | null;
+}
+
+export interface EmailEventListResponse {
+  data: Array<EmailEventListResponse.Data>;
+
+  meta: EmailEventListResponse.Meta;
+}
+
+export namespace EmailEventListResponse {
+  export interface Data {
+    id: string;
+
+    email_id: string;
+
+    occurred_at: string;
+
+    record_type: 'email_event';
+
+    type: EmailEventsAPI.EmailEventType;
+
+    /**
+     * Summary of the associated email message. Present when the email_message preload
+     * is available.
+     */
+    email?: Data.Email;
+
+    payload?: { [key: string]: unknown };
+  }
+
+  export namespace Data {
+    /**
+     * Summary of the associated email message. Present when the email_message preload
+     * is available.
+     */
+    export interface Email {
+      cc: Array<DraftsAPI.EmailAddress>;
+
+      from: DraftsAPI.EmailAddress;
+
+      subject: string;
+
+      to: Array<DraftsAPI.EmailAddress>;
+    }
+  }
+
+  export interface Meta {
+    page_size: number;
+
+    time_range: EmailEventsAPI.TimeRange;
+
+    /**
+     * Cursor for the next page, when more results are available.
+     */
+    page_cursor?: string;
+  }
+}
+
+export interface EmailEventRetrieveStatsResponse {
+  data: EmailEventRetrieveStatsResponse.Data;
+}
+
+export namespace EmailEventRetrieveStatsResponse {
+  export interface Data {
+    /**
+     * Recipient-level outcome counts for the queried time range. Each to, cc, and bcc
+     * recipient counts separately; repeated events of the same type for the same
+     * message and recipient count once. Partial MTA injection results count successful
+     * recipients as sent and unsuccessful recipients as failed. Only the ten listed
+     * event types are counted; other valid event types (scheduled, cancelled, sandbox,
+     * sending, rejected) are not included in stats.
+     */
+    counts: Data.Counts;
+
+    /**
+     * Recipient-level event rates as percentages, rounded to 2 decimal places.
+     */
+    rates: Data.Rates;
+
+    record_type: 'email_event_stats';
+
+    time_range: EmailEventsAPI.TimeRange;
+  }
+
+  export namespace Data {
+    /**
+     * Recipient-level outcome counts for the queried time range. Each to, cc, and bcc
+     * recipient counts separately; repeated events of the same type for the same
+     * message and recipient count once. Partial MTA injection results count successful
+     * recipients as sent and unsuccessful recipients as failed. Only the ten listed
+     * event types are counted; other valid event types (scheduled, cancelled, sandbox,
+     * sending, rejected) are not included in stats.
+     */
+    export interface Counts {
+      bounced: number;
+
+      clicked: number;
+
+      complained: number;
+
+      deferred: number;
+
+      delivered: number;
+
+      failed: number;
+
+      opened: number;
+
+      queued: number;
+
+      sent: number;
+
+      unsubscribed: number;
+    }
+
+    /**
+     * Recipient-level event rates as percentages, rounded to 2 decimal places.
+     */
+    export interface Rates {
+      /**
+       * Bounced recipients / queued recipients as a percentage.
+       */
+      bounce_rate: number;
+
+      /**
+       * Recipients clicked / recipients opened as a percentage.
+       */
+      click_rate: number;
+
+      /**
+       * Recipients with a complaint feedback report / delivered recipients as a
+       * percentage.
+       */
+      complaint_rate: number;
+
+      /**
+       * Deferred recipients / queued recipients as a percentage.
+       */
+      deferred_rate: number;
+
+      /**
+       * Delivered recipients / queued recipients as a percentage.
+       */
+      delivery_rate: number;
+
+      /**
+       * Recipients opened / recipients delivered as a percentage.
+       */
+      open_rate: number;
+    }
+  }
+}
+
+export interface EmailEventListParams {
+  /**
+   * Filter events for a specific email message UUID. Invalid UUID values are
+   * silently ignored (no filter applied).
+   */
+  email_id?: string;
+
+  /**
+   * 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.
+   */
+  event_type?: string | Array<string>;
+
+  /**
+   * Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when omitted.
+   */
+  from?: string;
+
+  /**
+   * Opaque URL-safe Base64 cursor returned by a previous list response.
+   */
+  page_cursor?: string;
+
+  /**
+   * Number of results to return. Defaults to 25; maximum is 100. Invalid values are
+   * clamped to the valid range.
+   */
+  page_size?: number;
+
+  /**
+   * Inclusive ISO 8601 end timestamp. When `from` is provided without `to`, defaults
+   * to `from + 30 days`.
+   */
+  to?: string;
+}
+
+export interface EmailEventRetrieveStatsParams {
+  /**
+   * Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when omitted.
+   */
+  from?: string;
+
+  /**
+   * Inclusive ISO 8601 end timestamp. When `from` is provided without `to`, defaults
+   * to `from + 30 days`.
+   */
+  to?: string;
+}
+
+export declare namespace EmailEvents {
+  export {
+    type EmailEventType as EmailEventType,
+    type TimeRange as TimeRange,
+    type EmailEventListResponse as EmailEventListResponse,
+    type EmailEventRetrieveStatsResponse as EmailEventRetrieveStatsResponse,
+    type EmailEventListParams as EmailEventListParams,
+    type EmailEventRetrieveStatsParams as EmailEventRetrieveStatsParams,
+  };
+}