@messagebird/sdk 0.3.0 → 0.4.2

package/dist/index.d.mts

@@ -0,0 +1,3904 @@
+//#region src/core/http.d.ts
+/** Transport metadata exposed to callers via `.withResponse()`. */
+interface BirdResponse {
+  status: number;
+  headers: Headers;
+  /** Correlation ID — the `X-Request-Id` header. */
+  requestId: string;
+}
+/** Per-request lifecycle inputs, supplied by the resource method. */
+interface RequestLifecycleOptions {
+  /** HTTP method — decides idempotency-key generation and retry safety. */
+  method: string;
+  /** Caller-supplied idempotency key; auto-generated for mutations if absent. */
+  idempotencyKey?: string;
+  /** Caller cancellation. */
+  signal?: AbortSignal;
+  /** Per-attempt timeout (ms). Overrides the client default. */
+  timeout?: number;
+  /** Max retry attempts. Overrides the client default. */
+  maxRetries?: number;
+}
+/** The shape a generated hey-api SDK call resolves to. */
+interface FetchOutcome<T> {
+  data?: T;
+  error?: unknown;
+  /** Present whenever the HTTP round-trip completed; absent only on a rejected call. */
+  response?: Response;
+}
+/** Context handed to the call thunk on each attempt. */
+interface AttemptContext {
+  signal: AbortSignal;
+  idempotencyKey?: string;
+}
+interface CoreDefaults {
+  /** Per-attempt timeout (ms). */
+  timeout: number;
+  /** Max retry attempts. */
+  maxRetries: number;
+}
+declare class BirdHTTPClient {
+  private readonly defaults;
+  constructor(defaults: CoreDefaults);
+  /**
+   * Run a generated hey-api SDK call through the request lifecycle.
+   *
+   * @param call  Invokes the SDK function; receives the per-attempt signal and
+   *              the idempotency key to set as a header.
+   * @returns the parsed body plus transport metadata.
+   * @throws  a `BirdError` subclass on terminal failure; the native
+   *          `AbortError` if the caller's signal aborts.
+   */
+  request<T>(call: (ctx: AttemptContext) => Promise<FetchOutcome<T>>, options: RequestLifecycleOptions): Promise<{
+    data: T;
+    response: BirdResponse;
+  }>;
+}
+//#endregion
+//#region src/errors.d.ts
+/** Root of the hierarchy. Catch this to catch anything the SDK throws. */
+declare class BirdError extends Error {
+  constructor(message: string);
+}
+/** Network-level failure with no HTTP response (DNS, refused, socket hangup). */
+declare class BirdConnectionError extends BirdError {
+  constructor(message: string);
+}
+/** A single attempt exceeded its timeout. Retryable. */
+declare class BirdTimeoutError extends BirdError {
+  readonly timeoutMs: number;
+  constructor(message: string, timeoutMs: number);
+}
+/** A webhook payload failed signature verification (bad signature, stale timestamp, malformed headers). */
+declare class BirdWebhookVerificationError extends BirdError {
+  constructor(message: string);
+}
+/** One per-field validation failure (the `details` array on a 422). */
+interface ErrorDetail {
+  /** Dotted field path, e.g. `to[0].email`, `subject`, `.`. */
+  param: string;
+  /** What is wrong with this field. */
+  message: string;
+}
+/** One recovery step: an operation to call to resolve the error (ADR-0073). */
+interface ErrorNextAction {
+  /** operationId of the follow-up operation that resolves this error. */
+  operation: string;
+  /** Short human-readable label for the recovery step. */
+  description?: string;
+  /** Permission scope the recovery operation requires, when it is scoped. */
+  scope?: string;
+}
+/** Constructor fields shared by every API error, mapped from the wire body. */
+interface BirdAPIErrorFields {
+  statusCode: number;
+  /** Opaque, stable error code (`E#####`). */
+  code: string;
+  /** Coarse category — the value callers branch on. */
+  type: string;
+  /** Human-readable slug for logs. Paired with `code`, never replaces it. */
+  errorName: string;
+  message: string;
+  /** Stable link to the docs page for this code. */
+  docUrl: string;
+  /** Correlation ID — also the `X-Request-Id` response header. */
+  requestId: string;
+  /** Offending field, when applicable. */
+  param?: string;
+  /** Verbatim code from a downstream system (SMTP reply, payment decline). */
+  vendorCode?: string;
+  /** Human recovery line for this error, when a recovery is known (ADR-0073). */
+  remediation?: string;
+  /** Operations that resolve this error, in the order to try them (ADR-0073). */
+  next?: ErrorNextAction[];
+}
+/** The server returned an error body. Base for every `type`-specific class. */
+declare class BirdAPIError extends BirdError {
+  readonly statusCode: number;
+  readonly code: string;
+  readonly type: string;
+  readonly errorName: string;
+  readonly docUrl: string;
+  readonly requestId: string;
+  readonly param?: string;
+  readonly vendorCode?: string;
+  readonly remediation?: string;
+  readonly next?: ErrorNextAction[];
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 401 — authentication failed or missing. */
+declare class BirdAuthError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 403 — authenticated but not allowed. */
+declare class BirdPermissionError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 404 — resource does not exist. */
+declare class BirdNotFoundError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 409 — semantic conflict (e.g. a unique value already taken). */
+declare class BirdConflictError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 400 — malformed request. */
+declare class BirdBadRequestError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 402 — billing/balance problem. */
+declare class BirdBillingError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 412/428 — a precondition was not met. */
+declare class BirdPreconditionError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 413 — request body too large. */
+declare class BirdPayloadTooLargeError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 500 — unexpected server error. */
+declare class BirdInternalError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 501 — endpoint not implemented. */
+declare class BirdNotImplementedError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 421 — request reached the wrong region (ADR-0036). */
+declare class BirdMisdirectedError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 503 — service temporarily unavailable. */
+declare class BirdServiceUnavailableError extends BirdAPIError {
+  constructor(fields: BirdAPIErrorFields);
+}
+/** 422 — field validation failed; `details` carries the per-field errors. */
+declare class BirdValidationError extends BirdAPIError {
+  readonly details: ErrorDetail[];
+  constructor(fields: BirdAPIErrorFields & {
+    details: ErrorDetail[];
+  });
+}
+/** 429 — rate limited; `retryAfter` is the server-advised wait in seconds. */
+declare class BirdRateLimitError extends BirdAPIError {
+  readonly retryAfter?: number;
+  constructor(fields: BirdAPIErrorFields & {
+    retryAfter?: number;
+  });
+}
+//#endregion
+//#region src/core/result.d.ts
+/** Per-request overrides accepted by every resource method. */
+interface RequestOptions {
+  /** Idempotency key; auto-generated for mutations if omitted, reused on retry. */
+  idempotencyKey?: string;
+  /** Caller cancellation. Rejects with the native `AbortError`. */
+  signal?: AbortSignal;
+  /** Per-attempt timeout (ms). Overrides the client default. */
+  timeout?: number;
+  /** Max retry attempts. Overrides the client default. */
+  maxRetries?: number;
+  /** Extra headers for this request. SDK-internal headers win on conflict. */
+  headers?: Record<string, string>;
+}
+/**
+ * The result of `.safe()` — the value or the error, never thrown. On success
+ * `data` and the `response` envelope are present and `error` is `null`. On
+ * failure `error` is a `BirdError` you can `instanceof`-narrow, and `data`/
+ * `response` are `null` — the metadata you need (status, request id) is on the
+ * error itself. A caller-initiated abort is not a Bird failure and still throws
+ * (the native `AbortError`, ADR-0042 §1).
+ */
+type SafeResult<T> = {
+  data: T;
+  error: null;
+  response: BirdResponse;
+} | {
+  data: null;
+  error: BirdError;
+  response: null;
+};
+/** Single-result return: `await` for the value, `.withResponse()` for metadata. */
+interface APIPromise<T> extends Promise<T> {
+  withResponse(): Promise<{
+    data: T;
+    response: BirdResponse;
+  }>;
+  /** Resolve to `{ data, error }` instead of throwing. */
+  safe(): Promise<SafeResult<T>>;
+}
+/** One cursor-paginated page — the wire envelope shape (snake), verbatim. */
+interface CursorPage<T> {
+  data: T[];
+  /** Pass back as `starting_after` to advance. Null at the end. */
+  next_cursor: string | null;
+  /** Pass back as `ending_before` to step back. Null at the start. */
+  prev_cursor: string | null;
+  /** Refresh anchor; pass as `ending_before` later for items since this page. */
+  refresh_cursor: string | null;
+  /** Total across all pages — only when `include_total=true` was passed. */
+  total?: number | null;
+}
+/**
+ * List return (R1): `await` resolves the first page; `for await` walks every
+ * item across all pages, fetching subsequent pages lazily.
+ */
+interface PaginatedPromise<T> extends Promise<CursorPage<T>>, AsyncIterable<T> {
+  withResponse(): Promise<{
+    data: CursorPage<T>;
+    response: BirdResponse;
+  }>;
+  /** Resolve the first page as `{ data, error }` instead of throwing. */
+  safe(): Promise<SafeResult<CursorPage<T>>>;
+}
+//#endregion
+//#region src/generated/types.gen.d.ts
+/**
+ * Payload of the sms.undelivered event.
+ */
+type EventSmsUndeliveredData = EventSmsBase & {
+  /**
+   * Why the message was not delivered.
+   */
+  error: SmsError;
+};
+/**
+ * Bird-stable failure reason. `invalid_destination` — the number is not assigned, ported out, or malformed. `unreachable` — handset off or out of coverage. `blocked_by_carrier` — the carrier filtered the message. `blocked_by_recipient` — the recipient device blocked the sender. `landline_unreachable` — the destination is a landline that does not accept SMS. `content_rejected` — the carrier rejected the content. `sender_unregistered` — the sender is not registered for the destination. `recipient_opted_out` — the recipient is on a suppression list. `provider_unavailable` — an upstream failure after retries. `unknown` — an unmapped failure.
+ *
+ */
+type SmsErrorCode = "invalid_destination" | "unreachable" | "blocked_by_carrier" | "blocked_by_recipient" | "landline_unreachable" | "content_rejected" | "sender_unregistered" | "recipient_opted_out" | "provider_unavailable" | "unknown";
+/**
+ * Failure detail for a message that could not be delivered or was rejected. Null when there is no failure.
+ */
+type SmsError = {
+  code: SmsErrorCode;
+  /**
+   * Human-readable explanation of the failure.
+   */
+  description: string;
+  /**
+   * Raw carrier-supplied error code, when available, for low-level debugging.
+   */
+  carrier_error_code?: string | null;
+  /**
+   * When the failure occurred.
+   */
+  occurred_at: string;
+} | null;
+/**
+ * Structured key/value label attached to a message. Surfaces in list filters, the event log, and webhook payloads. Use tags for low-cardinality filtering dimensions (category, experiment ID, template ID). For arbitrary per-send context that does not need to be filterable, use `metadata`.
+ * Tag count and per-tag size are capped to keep per-send tag payloads small — see the send request for the array maximum. Tag names are unique within a send; supplying the same name twice is rejected.
+ *
+ */
+type Tag = {
+  /**
+   * Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
+   *
+   */
+  name: string;
+  /**
+   * Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
+   *
+   */
+  value: string;
+};
+type WorkspaceId = string;
+type SmsMessageId = string;
+/**
+ * Identity fields shared by every SMS lifecycle event payload.
+ */
+type EventSmsBase = {
+  /**
+   * ID of the SMS message.
+   */
+  sms_id: SmsMessageId;
+  /**
+   * ID of the workspace.
+   */
+  workspace_id: WorkspaceId;
+  /**
+   * Recipient phone number in E.164 format.
+   */
+  to: string;
+  /**
+   * Sender the message was sent from — an E.164 number, an alphanumeric sender ID, or a short code.
+   */
+  from: string;
+  /**
+   * Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
+   *
+   */
+  tags: Array<Tag> | null;
+  /**
+   * The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
+   *
+   */
+  metadata: {
+    [key: string]: unknown;
+  } | null;
+};
+/**
+ * The carrier reported a non-permanent failure to deliver the message.
+ */
+type EventSmsUndelivered = {
+  /**
+   * Event type.
+   */
+  type: "sms.undelivered";
+  /**
+   * Time the non-delivery was recorded.
+   */
+  timestamp: string;
+  data: EventSmsUndeliveredData;
+};
+/**
+ * Payload of the sms.sent event.
+ */
+type EventSmsSentData = EventSmsBase & {
+  /**
+   * Carrier that handled the message, or null when not known.
+   */
+  carrier: string | null;
+  /**
+   * Mobile country code and mobile network code of the carrier, or null when not known.
+   */
+  mcc_mnc: string | null;
+};
+/**
+ * Bird handed the message to the carrier for delivery.
+ */
+type EventSmsSent = {
+  /**
+   * Event type.
+   */
+  type: "sms.sent";
+  /**
+   * Time the message was handed to the carrier.
+   */
+  timestamp: string;
+  data: EventSmsSentData;
+};
+/**
+ * Payload of the sms.rejected event.
+ */
+type EventSmsRejectedData = EventSmsBase & {
+  /**
+   * Why the message was rejected before reaching the carrier.
+   */
+  error: SmsError;
+};
+/**
+ * Bird rejected the message before sending it to the carrier (invalid destination, suppression, or a content/policy guard).
+ */
+type EventSmsRejected = {
+  /**
+   * Event type.
+   */
+  type: "sms.rejected";
+  /**
+   * Time the rejection was recorded.
+   */
+  timestamp: string;
+  data: EventSmsRejectedData;
+};
+/**
+ * Payload of the sms.failed event.
+ */
+type EventSmsFailedData = EventSmsBase & {
+  /**
+   * Why the message terminally failed.
+   */
+  error: SmsError;
+};
+/**
+ * The message terminally failed and will not be delivered.
+ */
+type EventSmsFailed = {
+  /**
+   * Event type.
+   */
+  type: "sms.failed";
+  /**
+   * Time the failure was recorded.
+   */
+  timestamp: string;
+  data: EventSmsFailedData;
+};
+/**
+ * Payload of the sms.expired event.
+ */
+type EventSmsExpiredData = EventSmsBase;
+/**
+ * The message's validity period elapsed before it could be delivered.
+ */
+type EventSmsExpired = {
+  /**
+   * Event type.
+   */
+  type: "sms.expired";
+  /**
+   * Time the message expired.
+   */
+  timestamp: string;
+  data: EventSmsExpiredData;
+};
+/**
+ * Payload of the sms.delivered event.
+ */
+type EventSmsDeliveredData = EventSmsBase & {
+  /**
+   * Carrier that delivered the message, or null when not known.
+   */
+  carrier: string | null;
+  /**
+   * Mobile country code and mobile network code of the carrier, or null when not known.
+   */
+  mcc_mnc: string | null;
+};
+/**
+ * The carrier confirmed delivery of the message to the recipient handset.
+ */
+type EventSmsDelivered = {
+  /**
+   * Event type.
+   */
+  type: "sms.delivered";
+  /**
+   * Time the carrier confirmed delivery.
+   */
+  timestamp: string;
+  data: EventSmsDeliveredData;
+};
+/**
+ * Payload of the sms.accepted event.
+ */
+type EventSmsAcceptedData = EventSmsBase;
+/**
+ * Bird accepted the SMS send request and queued it for processing.
+ */
+type EventSmsAccepted = {
+  /**
+   * Event type.
+   */
+  type: "sms.accepted";
+  /**
+   * Time Bird accepted the request.
+   */
+  timestamp: string;
+  data: EventSmsAcceptedData;
+};
+/**
+ * An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce). Payload schema not yet finalized.
+ */
+type EventEmailSuppressionCreated = {
+  /**
+   * Event type.
+   */
+  type: "email_suppression.created";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  /**
+   * Event payload. The fields for this event are not yet finalized.
+   */
+  data: {
+    [key: string]: never;
+  };
+};
+/**
+ * Payload of the email_mailbox.thread_created event.
+ */
+type EventEmailMailboxThreadCreatedData = {
+  /**
+   * ID of the thread.
+   */
+  thread_id: ThreadId;
+  /**
+   * ID of the mailbox.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * Subject of the first message in the thread, or null when it had none.
+   */
+  subject: string | null;
+  /**
+   * Which direction created the thread.
+   */
+  initiated_by: "inbound" | "outbound";
+};
+type MailboxId = string;
+type ThreadId = string;
+/**
+ * A new thread was created in a mailbox, from either direction.
+ */
+type EventEmailMailboxThreadCreated = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.thread_created";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxThreadCreatedData;
+};
+/**
+ * Payload of the email_mailbox.suspended event.
+ */
+type EventEmailMailboxSuspendedData = {
+  /**
+   * ID of the suspended mailbox.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * Why the mailbox was suspended.
+   */
+  reason: string;
+};
+/**
+ * Platform abuse controls suspended a mailbox. Sends are rejected and inbound is quarantined until it is reinstated.
+ */
+type EventEmailMailboxSuspended = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.suspended";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxSuspendedData;
+};
+/**
+ * Payload of the email_mailbox.message_sent event.
+ */
+type EventEmailMailboxMessageSentData = {
+  /**
+   * ID of the sent message. The same send fires the per-recipient email.* lifecycle events with this ID as email_id — when you subscribe to both families, dedupe by this ID.
+   */
+  message_id: EmailId;
+  /**
+   * ID of the mailbox the message was sent from.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * ID of the thread the message belongs to.
+   */
+  thread_id: ThreadId;
+};
+type EmailId = string;
+/**
+ * A mailbox send reached provider handoff — the per-message status folded to sent. Status events are per-message folds, not per-recipient telemetry; the same send also fires the shipped per-recipient email.* lifecycle events. Pick one family per automation and dedupe by message_id.
+ */
+type EventEmailMailboxMessageSent = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_sent";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageSentData;
+};
+/**
+ * An email was received into a mailbox and stored with disposition unauthenticated — sender authentication could not be verified. Opt-in. Non-inbox dispositions fire only this mailbox variant, never email.received — existing email.received automations never start processing unauthenticated mail because a mailbox was attached. The payload carries identifiers, threading, authentication results, and the extracted text.
+ */
+type EventEmailMailboxMessageReceivedUnauthenticated = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_received_unauthenticated";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageReceivedData;
+};
+type InboundEmailMessageId = string;
+/**
+ * Payload shared by the email_mailbox.message_received event family. Carries identifiers, threading, disposition, authentication results, and the extracted text — enough for an agent to act without a fetch. Fetch original source (while within its 30-day window) via the thread-member endpoints.
+ */
+type EventEmailMailboxMessageReceivedData = {
+  /**
+   * ID of the received message. The same message fires email.received with this ID as inbound_message_id — when you subscribe to both families, dedupe by this ID.
+   */
+  message_id: InboundEmailMessageId;
+  /**
+   * ID of the mailbox that received the message.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * ID of the thread the message was filed into.
+   */
+  thread_id: ThreadId;
+  /**
+   * ID (ein_…) of the explicit inbound route that matched, or null when the message was delivered by the virtual exact-address route.
+   */
+  route_id?: string | null;
+  /**
+   * Envelope-from address.
+   */
+  from: string;
+  /**
+   * Recipient addresses the message was sent to.
+   */
+  to: Array<string>;
+  /**
+   * Subject line as received, or null when the message had no subject.
+   */
+  subject: string | null;
+  /**
+   * Where the message landed after receive policy, rules, and scanning were applied.
+   */
+  disposition: "inbox" | "blocked" | "unauthenticated";
+  /**
+   * Plain-text body with quoted history stripped, capped at 64 KB (see truncated_text). Null when extraction produced nothing. This copy is what the mailbox durably retains.
+   */
+  extracted_text?: string | null;
+  /**
+   * True when extracted_text was truncated to the 64 KB cap; fetch the full text via the thread-member endpoint.
+   */
+  truncated_text?: boolean;
+  /**
+   * Number of attachments on the message. Metadata is durable; bytes are fetchable while within the 30-day original-source window.
+   */
+  attachment_count: number;
+  /**
+   * Whether SPF passed for the sender, or null when no verdict was computable.
+   */
+  spf_pass?: boolean | null;
+  /**
+   * Whether DKIM passed for the sender, or null when no verdict was computable.
+   */
+  dkim_pass?: boolean | null;
+  /**
+   * Whether DMARC passed for the sender, or null when no verdict was computable.
+   */
+  dmarc_pass?: boolean | null;
+};
+/**
+ * An email was received into a mailbox and stored with disposition blocked — it failed the mailbox receive policy or a block rule. Opt-in. Non-inbox dispositions fire only this mailbox variant, never email.received — existing email.received automations never start processing blocked mail because a mailbox was attached. The payload carries identifiers, threading, authentication results, and the extracted text.
+ */
+type EventEmailMailboxMessageReceivedBlocked = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_received_blocked";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageReceivedData;
+};
+/**
+ * An email was received into a mailbox, threaded, and stored with disposition inbox. The payload carries identifiers, threading, authentication results, and the extracted text — enough for an agent to act without a fetch. Dual-fire rule: mailbox-owned inbound with disposition inbox ALSO fires the unchanged email.received event; the streams are unordered relative to each other, so pick one family per automation and dedupe by message_id.
+ */
+type EventEmailMailboxMessageReceived = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_received";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageReceivedData;
+};
+/**
+ * Payload of the email_mailbox.message_failed event.
+ */
+type EventEmailMailboxMessageFailedData = {
+  /**
+   * ID of the failed message. The same send fires the per-recipient email.* lifecycle events with this ID as email_id — when you subscribe to both families, dedupe by this ID.
+   */
+  message_id: EmailId;
+  /**
+   * ID of the mailbox the message was sent from.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * ID of the thread the message belongs to.
+   */
+  thread_id: ThreadId;
+  /**
+   * Why the send folded to failed.
+   */
+  reason: string;
+};
+/**
+ * A mailbox send folded to a terminal failure. Status events are per-message folds, not per-recipient telemetry: one event per message, distinct in cardinality from the shipped per-recipient email.* lifecycle events, which the same send also fires. Pick one family per automation and dedupe by message_id.
+ */
+type EventEmailMailboxMessageFailed = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_failed";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageFailedData;
+};
+/**
+ * Payload of the email_mailbox.message_delivered event.
+ */
+type EventEmailMailboxMessageDeliveredData = {
+  /**
+   * ID of the delivered message. The same send fires the per-recipient email.* lifecycle events with this ID as email_id — when you subscribe to both families, dedupe by this ID.
+   */
+  message_id: EmailId;
+  /**
+   * ID of the mailbox the message was sent from.
+   */
+  mailbox_id: MailboxId;
+  /**
+   * ID of the thread the message belongs to.
+   */
+  thread_id: ThreadId;
+};
+/**
+ * A mailbox send folded to delivered — every recipient reached a terminal delivered outcome. Status events are per-message folds, not per-recipient telemetry: one event per message, distinct in cardinality from the shipped per-recipient email.delivered (one event per recipient), which the same send also fires. Pick one family per automation and dedupe by message_id.
+ */
+type EventEmailMailboxMessageDelivered = {
+  /**
+   * Event type.
+   */
+  type: "email_mailbox.message_delivered";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  data: EventEmailMailboxMessageDeliveredData;
+};
+/**
+ * Payload of the email.unsubscribed event.
+ */
+type EventEmailUnsubscribedData = EventEmailBase;
+/**
+ * Envelope position of a recipient on an outbound email event.
+ */
+type RecipientRole = "to" | "cc" | "bcc";
+type RecipientId = string;
+/**
+ * Identity fields shared by every email lifecycle event payload.
+ */
+type EventEmailBase = {
+  /**
+   * ID of the email send.
+   */
+  email_id: EmailId;
+  /**
+   * ID of the recipient.
+   */
+  recipient_id: RecipientId;
+  /**
+   * ID of the workspace.
+   */
+  workspace_id: WorkspaceId;
+  /**
+   * Recipient address as it appeared on the envelope.
+   */
+  recipient: string;
+  /**
+   * Envelope position of the recipient.
+   */
+  recipient_role: RecipientRole;
+  /**
+   * Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
+   *
+   */
+  tags: Array<Tag> | null;
+  /**
+   * The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
+   *
+   */
+  metadata: {
+    [key: string]: unknown;
+  } | null;
+};
+/**
+ * Recipient unsubscribed by clicking a tracked unsubscribe link in the email. Fires once per recipient.
+ */
+type EventEmailUnsubscribed = {
+  /**
+   * Event type.
+   */
+  type: "email.unsubscribed";
+  /**
+   * Time the unsubscribe was recorded.
+   */
+  timestamp: string;
+  data: EventEmailUnsubscribedData;
+};
+/**
+ * Payload of the email.scheduled event.
+ */
+type EventEmailScheduledData = EventEmailMessageBase & {
+  /**
+   * When the message is scheduled to send.
+   */
+  scheduled_at: string;
+};
+/**
+ * Identity fields shared by the message-level email lifecycle events (scheduled, canceled), which are not tied to a single recipient.
+ */
+type EventEmailMessageBase = {
+  /**
+   * ID of the email send.
+   */
+  email_id: EmailId;
+  /**
+   * ID of the workspace.
+   */
+  workspace_id: WorkspaceId;
+  /**
+   * Tags provided on the send request, echoed on the event so you can route and correlate without an extra lookup. Null when the send carried no tags.
+   *
+   */
+  tags: Array<Tag> | null;
+  /**
+   * The metadata object provided on the send request, echoed on the event so you can correlate events with your own records. Null when the send carried no metadata.
+   *
+   */
+  metadata: {
+    [key: string]: unknown;
+  } | null;
+};
+/**
+ * Bird accepted a send scheduled for a future time. Fires once per message when the schedule is created, not per recipient.
+ */
+type EventEmailScheduled = {
+  /**
+   * Event type.
+   */
+  type: "email.scheduled";
+  /**
+   * Time the send was scheduled.
+   */
+  timestamp: string;
+  data: EventEmailScheduledData;
+};
+/**
+ * Why an email was rejected before delivery.
+ * `recipient_suppressed` means the recipient is on the workspace suppression list, so Bird did not attempt delivery. `transmission_failed` means the message could not be transmitted for delivery. `generation_failure` means the message could not be built for delivery (a template or content issue). `policy_rejection` means the message was refused by sending policy. `domain_unverified` means the sending domain was not verified. `quota_exceeded` means the organization's send quota was reached. `recipient_not_allowed` means a recipient was not permitted for this send (for shared onboarding-domain sends, recipients must be verified workspace members).
+ *
+ */
+type EmailRejectionReason = "recipient_suppressed" | "transmission_failed" | "generation_failure" | "policy_rejection" | "domain_unverified" | "quota_exceeded" | "recipient_not_allowed";
+/**
+ * Payload of the email.rejected event.
+ */
+type EventEmailRejectedData = EventEmailBase & {
+  rejection_reason: EmailRejectionReason;
+};
+/**
+ * Bird rejected the email before sending it (suppression list hit, transmission failure, or a content/policy guard). Fires once per recipient.
+ */
+type EventEmailRejected = {
+  /**
+   * Event type.
+   */
+  type: "email.rejected";
+  /**
+   * Time the rejection was recorded.
+   */
+  timestamp: string;
+  data: EventEmailRejectedData;
+};
+/**
+ * Payload of the email.received event.
+ */
+type EventEmailReceivedData = {
+  /**
+   * ID of the received email. Use it with GET /v1/email/inbound-messages/{id} to fetch the body, raw content, and attachments.
+   */
+  inbound_message_id: InboundEmailMessageId;
+  /**
+   * ID of the workspace.
+   */
+  workspace_id: WorkspaceId;
+  /**
+   * RFC 5322 Message-ID header from the sender, or null when the sender did not include one.
+   */
+  message_id: string | null;
+  /**
+   * Envelope-from address.
+   */
+  from: string;
+  /**
+   * Recipient addresses the message was sent to.
+   */
+  to: Array<string>;
+  /**
+   * Subject line as received, or null when the message had no subject.
+   */
+  subject: string | null;
+  /**
+   * In-Reply-To header — the Message-ID this message replies to, or null when it is not a reply.
+   */
+  in_reply_to?: string | null;
+  /**
+   * Whether SPF passed for the sender, or null when the result did not carry an SPF verdict.
+   */
+  spf_pass?: boolean | null;
+  /**
+   * Whether DKIM passed for the sender, or null when the result did not carry a DKIM verdict.
+   */
+  dkim_pass?: boolean | null;
+  /**
+   * Whether DMARC passed for the sender, or null when the result did not carry a DMARC verdict.
+   */
+  dmarc_pass?: boolean | null;
+  /**
+   * Spam score for the message. Always null at present; reserved for a future content-scoring capability.
+   */
+  spam_score?: number | null;
+};
+/**
+ * Bird received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentication results — enough to route and triage without a fetch. Fetch the body, full headers, and attachments with GET /v1/email/inbound-messages/{id}.
+ */
+type EventEmailReceived = {
+  /**
+   * Event type.
+   */
+  type: "email.received";
+  /**
+   * When Bird received the message.
+   */
+  timestamp: string;
+  data: EventEmailReceivedData;
+};
+/**
+ * Payload of the email.processed event.
+ */
+type EventEmailProcessedData = EventEmailBase;
+/**
+ * Bird processed the message and queued it for delivery to the recipient's mail server. Fires once per recipient when the message enters the SMTP delivery queue.
+ */
+type EventEmailProcessed = {
+  /**
+   * Event type.
+   */
+  type: "email.processed";
+  /**
+   * Time Bird processed the message and queued it for SMTP delivery.
+   */
+  timestamp: string;
+  data: EventEmailProcessedData;
+};
+/**
+ * Payload of the email.out_of_band_bounce event.
+ */
+type EventEmailOutOfBandBounceData = EventEmailBase & {
+  bounce_type: EmailBounceType;
+  /**
+   * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified.
+   *
+   */
+  bounce_class: number | null;
+  /**
+   * SMTP reply code returned by the receiving mail server, or null when none was provided.
+   */
+  bounce_code: string | null;
+  /**
+   * Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
+   */
+  bounce_description: string | null;
+  /**
+   * The IP address used to send this message, or null when it is not known.
+   */
+  sending_ip: string | null;
+};
+/**
+ * Bounce classification. `hard` is a permanent failure (invalid address or non-existent domain). `soft` is a transient failure (mailbox full, server temporarily unavailable). `block` indicates the receiving mail server blocked the sending IP for reputation reasons. `admin` indicates an administrative refusal (relaying denied, blocklisted domain). `undetermined` is used when the receiving server's response is ambiguous.
+ *
+ */
+type EmailBounceType = "hard" | "soft" | "undetermined" | "admin" | "block";
+/**
+ * A bounce notification arrived after the message had already been accepted for delivery. Fires once per recipient.
+ */
+type EventEmailOutOfBandBounce = {
+  /**
+   * Event type.
+   */
+  type: "email.out_of_band_bounce";
+  /**
+   * Time the bounce notification was recorded.
+   */
+  timestamp: string;
+  data: EventEmailOutOfBandBounceData;
+};
+/**
+ * Payload of the email.opened event.
+ */
+type EventEmailOpenedData = EventEmailBase & {
+  /**
+   * IP address of the client that opened the email, or null when it is not known.
+   */
+  ip_address: string | null;
+  /**
+   * User-agent string of the client that opened the email, or null when it is not known.
+   */
+  user_agent: string | null;
+};
+/**
+ * The recipient opened the email (the tracking pixel was loaded). May fire more than once per recipient.
+ */
+type EventEmailOpened = {
+  /**
+   * Event type.
+   */
+  type: "email.opened";
+  /**
+   * Time the open was recorded.
+   */
+  timestamp: string;
+  data: EventEmailOpenedData;
+};
+/**
+ * Payload of the email.list_unsubscribed event.
+ */
+type EventEmailListUnsubscribedData = EventEmailBase;
+/**
+ * Recipient unsubscribed via the RFC 8058 one-click List-Unsubscribe mechanism. Fires once per recipient.
+ */
+type EventEmailListUnsubscribed = {
+  /**
+   * Event type.
+   */
+  type: "email.list_unsubscribed";
+  /**
+   * Time the unsubscribe was recorded.
+   */
+  timestamp: string;
+  data: EventEmailListUnsubscribedData;
+};
+/**
+ * Payload of the email.delivered event.
+ */
+type EventEmailDeliveredData = EventEmailBase;
+/**
+ * An outbound email reached the recipient's mail server and was accepted.
+ */
+type EventEmailDelivered = {
+  /**
+   * Event type.
+   */
+  type: "email.delivered";
+  /**
+   * Time the recipient's mail server accepted the message.
+   */
+  timestamp: string;
+  data: EventEmailDeliveredData;
+};
+/**
+ * Payload of the email.deferred event.
+ */
+type EventEmailDeferredData = EventEmailBase & {
+  bounce_type: EmailBounceType;
+  /**
+   * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Distinguishes, for example, a greylisting deferral from a full mailbox.
+   *
+   */
+  bounce_class: number | null;
+  /**
+   * Human-readable reason the receiving mail server gave for the deferral, or null when none was provided.
+   */
+  defer_reason: string | null;
+  /**
+   * The IP address used to send this message, or null when it is not known.
+   */
+  sending_ip: string | null;
+};
+/**
+ * The recipient's mail server temporarily refused the email; delivery will be retried. May fire more than once per recipient.
+ */
+type EventEmailDeferred = {
+  /**
+   * Event type.
+   */
+  type: "email.deferred";
+  /**
+   * Time the deferral was recorded.
+   */
+  timestamp: string;
+  data: EventEmailDeferredData;
+};
+/**
+ * Payload of the email.complained event.
+ */
+type EventEmailComplainedData = EventEmailBase & {
+  /**
+   * The kind of feedback the mailbox provider reported (such as `abuse` or `fraud`), or null when the provider did not specify one.
+   */
+  feedback_type: string | null;
+};
+/**
+ * The recipient marked the email as spam through their mailbox provider's feedback loop. Fires once per recipient.
+ */
+type EventEmailComplained = {
+  /**
+   * Event type.
+   */
+  type: "email.complained";
+  /**
+   * Time the complaint was recorded.
+   */
+  timestamp: string;
+  data: EventEmailComplainedData;
+};
+/**
+ * Payload of the email.clicked event.
+ */
+type EventEmailClickedData = EventEmailBase & {
+  /**
+   * The URL the recipient clicked.
+   */
+  url: string;
+  /**
+   * IP address of the client that clicked the link, or null when it is not known.
+   */
+  ip_address: string | null;
+  /**
+   * User-agent string of the client that clicked the link, or null when it is not known.
+   */
+  user_agent: string | null;
+};
+/**
+ * The recipient clicked a tracked link in the email. May fire more than once per recipient.
+ */
+type EventEmailClicked = {
+  /**
+   * Event type.
+   */
+  type: "email.clicked";
+  /**
+   * Time the click was recorded.
+   */
+  timestamp: string;
+  data: EventEmailClickedData;
+};
+/**
+ * Payload of the email.canceled event.
+ */
+type EventEmailCanceledData = EventEmailMessageBase;
+/**
+ * A scheduled send was canceled before it fired. Fires once per message, not per recipient.
+ */
+type EventEmailCanceled = {
+  /**
+   * Event type.
+   */
+  type: "email.canceled";
+  /**
+   * Time the scheduled send was canceled.
+   */
+  timestamp: string;
+  data: EventEmailCanceledData;
+};
+/**
+ * Payload of the email.bounced event.
+ */
+type EventEmailBouncedData = EventEmailBase & {
+  bounce_type: EmailBounceType;
+  /**
+   * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Lets you distinguish, for example, a DNS failure from a spam block when both would be `bounce_type: soft` or `bounce_type: block`.
+   *
+   */
+  bounce_class: number | null;
+  /**
+   * SMTP reply code returned by the receiving mail server, or null when none was provided.
+   */
+  bounce_code: string | null;
+  /**
+   * Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
+   */
+  bounce_description: string | null;
+  /**
+   * The IP address used to send this message, or null when it is not known.
+   */
+  sending_ip: string | null;
+};
+/**
+ * An outbound email permanently failed at the recipient's mail server. Fires once per recipient.
+ */
+type EventEmailBounced = {
+  /**
+   * Event type.
+   */
+  type: "email.bounced";
+  /**
+   * Time the bounce was recorded.
+   */
+  timestamp: string;
+  data: EventEmailBouncedData;
+};
+/**
+ * Payload of the email.accepted event.
+ */
+type EventEmailAcceptedData = EventEmailBase;
+/**
+ * Bird accepted the email send and is preparing to deliver. Fires once per requested recipient at acceptance time.
+ */
+type EventEmailAccepted = {
+  /**
+   * Event type.
+   */
+  type: "email.accepted";
+  /**
+   * Time Bird accepted the send.
+   */
+  timestamp: string;
+  data: EventEmailAcceptedData;
+};
+/**
+ * A sending domain completed DNS verification successfully. Payload schema not yet finalized.
+ */
+type EventDomainVerified = {
+  /**
+   * Event type.
+   */
+  type: "domain.verified";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  /**
+   * Event payload. The fields for this event are not yet finalized.
+   */
+  data: {
+    [key: string]: never;
+  };
+};
+/**
+ * A sending domain failed DNS verification. Payload schema not yet finalized.
+ */
+type EventDomainFailed = {
+  /**
+   * Event type.
+   */
+  type: "domain.failed";
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+  /**
+   * Event payload. The fields for this event are not yet finalized.
+   */
+  data: {
+    [key: string]: never;
+  };
+};
+/**
+ * Discriminated union of every webhook event the Bird platform emits.
+ * Each variant is the full delivery body: `type` names the event, `timestamp` is when the event occurred, and `data` carries the event-specific payload. The `type` property selects the variant — SDKs that consume this schema (openapi-typescript, oapi-codegen) generate a narrowed union keyed on `type`, so customer code can switch on the event id and access the variant-specific payload fields without casting.
+ * Delivery metadata (the event id and per-attempt signature headers) rides in HTTP headers per Standard Webhooks and is handled by the SDK's webhook verification helper, which returns one of these variants.
+ *
+ */
+type WebhookEvent = ({
+  type: "domain.failed";
+} & EventDomainFailed) | ({
+  type: "domain.verified";
+} & EventDomainVerified) | ({
+  type: "email.accepted";
+} & EventEmailAccepted) | ({
+  type: "email.bounced";
+} & EventEmailBounced) | ({
+  type: "email.canceled";
+} & EventEmailCanceled) | ({
+  type: "email.clicked";
+} & EventEmailClicked) | ({
+  type: "email.complained";
+} & EventEmailComplained) | ({
+  type: "email.deferred";
+} & EventEmailDeferred) | ({
+  type: "email.delivered";
+} & EventEmailDelivered) | ({
+  type: "email.list_unsubscribed";
+} & EventEmailListUnsubscribed) | ({
+  type: "email.opened";
+} & EventEmailOpened) | ({
+  type: "email.out_of_band_bounce";
+} & EventEmailOutOfBandBounce) | ({
+  type: "email.processed";
+} & EventEmailProcessed) | ({
+  type: "email.received";
+} & EventEmailReceived) | ({
+  type: "email.rejected";
+} & EventEmailRejected) | ({
+  type: "email.scheduled";
+} & EventEmailScheduled) | ({
+  type: "email.unsubscribed";
+} & EventEmailUnsubscribed) | ({
+  type: "email_mailbox.message_delivered";
+} & EventEmailMailboxMessageDelivered) | ({
+  type: "email_mailbox.message_failed";
+} & EventEmailMailboxMessageFailed) | ({
+  type: "email_mailbox.message_received";
+} & EventEmailMailboxMessageReceived) | ({
+  type: "email_mailbox.message_received_blocked";
+} & EventEmailMailboxMessageReceivedBlocked) | ({
+  type: "email_mailbox.message_received_unauthenticated";
+} & EventEmailMailboxMessageReceivedUnauthenticated) | ({
+  type: "email_mailbox.message_sent";
+} & EventEmailMailboxMessageSent) | ({
+  type: "email_mailbox.suspended";
+} & EventEmailMailboxSuspended) | ({
+  type: "email_mailbox.thread_created";
+} & EventEmailMailboxThreadCreated) | ({
+  type: "email_suppression.created";
+} & EventEmailSuppressionCreated) | ({
+  type: "sms.accepted";
+} & EventSmsAccepted) | ({
+  type: "sms.delivered";
+} & EventSmsDelivered) | ({
+  type: "sms.expired";
+} & EventSmsExpired) | ({
+  type: "sms.failed";
+} & EventSmsFailed) | ({
+  type: "sms.rejected";
+} & EventSmsRejected) | ({
+  type: "sms.sent";
+} & EventSmsSent) | ({
+  type: "sms.undelivered";
+} & EventSmsUndelivered);
+type Timestamps = {
+  readonly created_at: string;
+  readonly updated_at: string;
+};
+/**
+ * File attached to an email send. The attachment bytes are passed as base64-encoded `content` directly in the request body (required). The `path` field (provide a URL and Bird fetches the attachment for you) is a preview feature and currently unavailable. Requests are rejected with 422 if `content` is missing — `path` alone does not satisfy the schema. When `path` becomes generally available, the schema will be relaxed so that exactly one of `content` or `path` is required.
+ * Inline images for `<img src="cid:..."/>` references in the HTML body use the `content_id` field together with `content`.
+ * Bird enforces a **20 MB estimated generated message size** cap. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. This is not a raw file-size cap. As a rule of thumb, keep total raw attachment content at or below **15 MB** so the generated message has enough room after encoding and MIME wrapping.
+ * Recipient-side delivery reality: downstream limits vary by product and tenant/server policy. Gmail personal and Outlook.com document 25 MB attachment limits. Exchange Online defaults to 35 MB send / 36 MB receive, but admins can configure limits; on-prem Exchange Server organizational defaults are 10 MB. Sends close to Bird's 20 MB generated-message cap may be accepted by Bird but bounce at the recipient's mail server.
+ * Batch sends can include attachments on individual message objects. Each message still has the 20 MB estimated generated-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap. Certain executable / script content types are rejected at validation time.
+ *
+ */
+type EmailAttachment = {
+  /**
+   * Filename shown to the recipient. Required.
+   */
+  filename: string;
+  /**
+   * Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
+   *
+   */
+  content: string;
+  /**
+   * Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use `content` instead. The schema currently requires `content`, so a request with only `path` is rejected with 422 for missing `content`; a request supplying both `content` and `path` is rejected with 422 `unsupported_feature` until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
+   *
+   */
+  path?: string;
+  /**
+   * MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
+   *
+   */
+  content_type?: string;
+  /**
+   * RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as `<img src="cid:{content_id}"/>`. When omitted, the attachment is rendered as a regular file attachment.
+   *
+   */
+  content_id?: string;
+};
+/**
+ * An email address with an optional display name.
+ */
+type EmailAddress = {
+  /**
+   * Email address.
+   */
+  email: string;
+  /**
+   * Display name shown alongside the address in mail clients.
+   */
+  name?: string;
+};
+/**
+ * A sender or recipient address. Accepts a plain email string (`jane@example.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@example.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request; responses always return the object form.
+ *
+ */
+type EmailAddressInput = string | EmailAddress;
+type ContactId = string;
+type EmailTemplateVersionList = {
+  /**
+   * All versions of the template, newest first.
+   */
+  data: Array<EmailTemplateVersion>;
+};
+/**
+ * A single variable slot a template fills in from the values supplied when sending. Shared across channels (SMS, email) so template introspection reads the same everywhere.
+ *
+ */
+type TemplateVariable = {
+  /**
+   * The parameters key this slot is filled with.
+   */
+  readonly key: string;
+  /**
+   * The value type this slot accepts. Open enum — treat any unrecognized value as a future type rather than an error. SMS templates use the typed slots (`code`, `amount`, …); email templates use `text`.
+   *
+   */
+  readonly type: string;
+  /**
+   * Whether the slot must be supplied when sending. Advisory for email templates, where a missing value renders as empty rather than rejecting the send.
+   *
+   */
+  readonly required: boolean;
+  /**
+   * A human-readable description of the accepted values.
+   */
+  readonly constraint: string;
+};
+type EmailTemplateId = string;
+type EmailTemplateVersionId = string;
+type EmailTemplateVersion = {
+  /**
+   * Template version ID.
+   */
+  readonly id: EmailTemplateVersionId;
+  /**
+   * The template this version belongs to.
+   */
+  readonly template_id: EmailTemplateId;
+  /**
+   * Sequential published-version number (1, 2, 3…). Null while the version is a draft.
+   */
+  readonly version_number?: number | null;
+  /**
+   * Lifecycle status of this version.
+   */
+  readonly status: "draft" | "published";
+  /**
+   * The version's revision counter.
+   */
+  readonly revision: number;
+  /**
+   * The variable slots this version's content fills in from the values you supply when sending.
+   */
+  readonly variables: Array<TemplateVariable>;
+  /**
+   * When this version was created.
+   */
+  readonly created_at: string;
+  /**
+   * When this version was published, or null if it has not been published.
+   */
+  readonly published_at?: string | null;
+};
+/**
+ * Partial update of a template's metadata and its draft content. Only the fields you send are changed; the rest are left as-is. Include the draft `revision` you last read so concurrent edits are detected.
+ *
+ */
+type EmailTemplateUpdate = {
+  /**
+   * The draft revision you last read (from the template's `revision` field). A stale value returns a conflict so you can reload and retry.
+   *
+   */
+  revision: number;
+  /**
+   * New workspace-unique slug handle. Must stay unique within the workspace. Lowercase letters, numbers, and hyphens.
+   *
+   */
+  name?: string;
+  /**
+   * New description of the template's purpose. Send null to clear it.
+   */
+  description?: string | null;
+  /**
+   * New email subject line for the draft. Send null to clear it.
+   */
+  subject?: string | null;
+  /**
+   * New HTML body — the source markup for the template's format.
+   */
+  html?: string;
+  /**
+   * New plain-text body for the draft. Send null to clear it.
+   */
+  text?: string | null;
+  /**
+   * Brand kit to apply to the draft.
+   */
+  brand_kit_id?: BrandKitId;
+};
+type BrandKitId = string;
+type EmailTemplate = {
+  /**
+   * Template ID.
+   */
+  readonly id: EmailTemplateId;
+  /**
+   * Workspace that owns the template.
+   */
+  readonly workspace_id: WorkspaceId;
+  /**
+   * The template's workspace-unique slug handle. Pass it (or the id) as the template reference when sending.
+   */
+  name: string;
+  /**
+   * Optional description of the template's purpose. Null when unset.
+   */
+  description?: string | null;
+  scope: TemplateScope;
+  category: EmailTemplateCategory;
+  source: EmailTemplateSource;
+  /**
+   * The variable slots this template's current draft fills in from the values you supply when sending.
+   */
+  readonly variables: Array<TemplateVariable>;
+  /**
+   * The current editable draft version.
+   */
+  readonly draft_version_id: EmailTemplateVersionId;
+  /**
+   * The currently published version, or null if the template has never been published.
+   */
+  readonly published_version_id?: EmailTemplateVersionId | null;
+  /**
+   * The draft's revision counter. Send it back on the next update to detect concurrent edits.
+   */
+  readonly revision: number;
+  /**
+   * The draft's email subject line. Null when unset.
+   */
+  subject?: string | null;
+  /**
+   * The draft's HTML body. Null when unset.
+   */
+  html?: string | null;
+  /**
+   * The draft's plain-text body. Null when unset.
+   */
+  text?: string | null;
+  /**
+   * The brand kit applied to the draft, or null if none.
+   */
+  readonly brand_kit_id?: BrandKitId | null;
+  /**
+   * When the template was created.
+   */
+  readonly created_at: string;
+  /**
+   * When the template was last modified.
+   */
+  readonly updated_at: string;
+};
+/**
+ * The authoring format the template is written in. Fixed at creation.
+ */
+type EmailTemplateSource = "liquid" | "handlebars" | "html";
+/**
+ * Whether the template is transactional or marketing email.
+ */
+type EmailTemplateCategory = "transactional" | "marketing";
+/**
+ * Whether the template is a built-in Bird template (`system`) or one your workspace authored (`workspace`).
+ */
+type TemplateScope = "system" | "workspace";
+/**
+ * Parameters for creating an email template and its initial draft.
+ */
+type EmailTemplateCreate = {
+  /**
+   * The template's workspace-unique slug handle — a stable alternative to the template ID when sending by template. Lowercase letters, numbers, and hyphens.
+   *
+   */
+  name: string;
+  /**
+   * Optional description of the template's purpose.
+   */
+  description?: string;
+  category: EmailTemplateCategory;
+  /**
+   * The authoring format the template is written in, fixed at creation. `liquid` currently supports variable substitution only (e.g. `{{ first_name }}`); filters, tags, and control flow are not yet supported — fuller Liquid support is coming soon.
+   *
+   */
+  source: EmailTemplateSource;
+  /**
+   * The email subject line for the initial draft.
+   */
+  subject?: string;
+  /**
+   * The HTML body — the source markup for the chosen format.
+   */
+  html?: string;
+  /**
+   * The optional plain-text body.
+   */
+  text?: string;
+  /**
+   * Optional brand kit to apply to the draft.
+   */
+  brand_kit_id?: BrandKitId;
+};
+type EmailTemplateSummary = {
+  /**
+   * Template ID.
+   */
+  readonly id: EmailTemplateId;
+  /**
+   * Workspace that owns the template.
+   */
+  readonly workspace_id: WorkspaceId;
+  /**
+   * The template's workspace-unique slug handle. Pass it (or the id) as the template reference when sending.
+   */
+  name: string;
+  /**
+   * Optional description of the template's purpose. Null when unset.
+   */
+  description?: string | null;
+  scope: TemplateScope;
+  category: EmailTemplateCategory;
+  source: EmailTemplateSource;
+  /**
+   * The current editable draft version.
+   */
+  readonly draft_version_id: EmailTemplateVersionId;
+  /**
+   * The currently published version, or null if never published.
+   */
+  readonly published_version_id?: EmailTemplateVersionId | null;
+  /**
+   * When the template was created.
+   */
+  readonly created_at: string;
+  /**
+   * When the template was last modified.
+   */
+  readonly updated_at: string;
+};
+type SmsTemplateList = {
+  /**
+   * The templates available to your workspace. The catalogue is small and returned in full — this list is not paginated.
+   */
+  data: Array<SmsTemplate>;
+};
+type SmsTemplateVersionId = string;
+/**
+ * Content classification. Drives opt-out (STOP) policy, quiet-hours, and per-country compliance.
+ */
+type SmsMessageCategory = "transactional" | "marketing" | "authentication" | "service";
+type SmsTemplateId = string;
+type SmsTemplate = {
+  /**
+   * Unique identifier for the template.
+   */
+  readonly id: SmsTemplateId;
+  /**
+   * The template's stable handle. Pass it (or the id) as the template reference when sending.
+   */
+  readonly name: string;
+  /**
+   * Human-readable description of what the template is for.
+   */
+  readonly description: string;
+  scope: TemplateScope;
+  /**
+   * Content classification applied to messages sent from this template.
+   */
+  readonly category: SmsMessageCategory;
+  /**
+   * The template body in its default language, shown for preview.
+   */
+  readonly body: string;
+  /**
+   * The typed slots this template fills in from the values you supply when sending.
+   */
+  readonly variables: Array<TemplateVariable>;
+  /**
+   * The languages this template is available in, as BCP-47 tags.
+   */
+  readonly available_languages: Array<string>;
+  /**
+   * The template's lifecycle state. Built-in templates are always `active`.
+   */
+  readonly status: "active" | "draft" | "pending" | "approved" | "rejected";
+  /**
+   * The current editable draft version. Always null today — SMS templates are not yet versioned; present for parity with email templates.
+   */
+  readonly draft_version_id: SmsTemplateVersionId | null;
+  /**
+   * The currently published version, or null if the template has never been published. Always null today — SMS templates are not yet versioned; present for parity with email templates.
+   */
+  readonly published_version_id?: SmsTemplateVersionId | null;
+  /**
+   * The draft's revision counter. Always null today — SMS templates are not yet versioned; present for parity with email templates.
+   */
+  readonly revision: number | null;
+  /**
+   * When the template was created. Null for built-in templates.
+   */
+  readonly created_at: string | null;
+  /**
+   * When the template was last updated. Null for built-in templates.
+   */
+  readonly updated_at: string | null;
+};
+type SmsMessageBatchResponse = {
+  /**
+   * One entry per message in the batch, in submission order.
+   */
+  data: Array<SmsMessage>;
+  /**
+   * Aggregate result for the batch.
+   */
+  summary: SmsBatchSummary;
+};
+/**
+ * Aggregate result for an SMS batch.
+ */
+type SmsBatchSummary = {
+  /**
+   * Number of messages accepted in the batch.
+   */
+  accepted_count: number;
+};
+/**
+ * Per-component cost breakdown. Returned on single-message reads; omitted from list rows.
+ */
+type SmsCostBreakdown = {
+  /**
+   * Per-segment price as a decimal string.
+   */
+  per_segment: string;
+  /**
+   * Number of billable segments.
+   */
+  segments: number;
+  /**
+   * ISO 3166-1 alpha-2 destination country the price was resolved for.
+   */
+  country_code: string;
+  /**
+   * Carrier surcharge component as a decimal string (for example US 10DLC fees). `0.0000` when none applies.
+   */
+  carrier_surcharge: string;
+};
+/**
+ * ISO 4217 three-letter currency code.
+ */
+type CurrencyCode = string;
+/**
+ * Cost of the message. Null until the message has been priced; the cost is populated as the message is processed, not at the moment it is accepted.
+ */
+type SmsCost = {
+  /**
+   * ISO 4217 currency code for the cost amount. Omitted when the cost is not denominated in a currency (for example a zero-priced internal send).
+   */
+  readonly currency_code?: CurrencyCode;
+  /**
+   * Total cost as a decimal string — the per-segment rate multiplied by the segment count, plus any surcharges.
+   */
+  readonly amount: string;
+  /**
+   * Per-component cost breakdown. Returned on single-message reads; omitted from list rows.
+   */
+  breakdown?: SmsCostBreakdown;
+} | null;
+/**
+ * Segment breakdown for the message body. Segment count drives billing.
+ */
+type SmsSegments = {
+  /**
+   * Number of segments the body is split into. Each segment is a billable unit.
+   */
+  readonly count: number;
+  /**
+   * Encoding used for the body. `GSM_7BIT` fits 160 characters in a single segment (153 per part when multi-segment); `UCS2` is used when the body contains any character outside the GSM 03.38 alphabet (emoji, CJK, some accented characters) and fits 70 characters in a single segment (67 per part when multi-segment).
+   *
+   */
+  readonly encoding: "GSM_7BIT" | "UCS2";
+  /**
+   * Character count of the body under the selected encoding.
+   */
+  readonly characters: number;
+};
+/**
+ * Delivery status. `scheduled` means the message is queued to send at a future time and has not been dispatched yet. `accepted` means Bird accepted the request and it is awaiting handoff to the carrier network. `sent` means it was handed to the carrier and is awaiting a delivery receipt. `delivered` is confirmed delivery. `undelivered` is a non-permanent non-delivery (handset off, content blocked). `failed` is a terminal permanent failure. `rejected` means Bird refused it before reaching the carrier. `canceled` means a scheduled message was canceled before it was sent. `expired` means the validity period elapsed without a terminal receipt. `received` applies to inbound messages.
+ *
+ */
+type SmsMessageStatus = "scheduled" | "accepted" | "sent" | "delivered" | "undelivered" | "failed" | "rejected" | "canceled" | "expired" | "received";
+type SmsMessage = {
+  /**
+   * Message ID.
+   */
+  readonly id: SmsMessageId;
+  /**
+   * Whether the message was sent from a Bird sender (`outbound`) or received from a subscriber (`inbound`).
+   */
+  readonly direction: "outbound" | "inbound";
+  readonly status: SmsMessageStatus;
+  /**
+   * Recipient phone number in E.164 format.
+   */
+  to: string;
+  /**
+   * Sender the message was sent from — an E.164 number, an alphanumeric sender ID, or a short code.
+   */
+  from: string;
+  /**
+   * Message body.
+   */
+  text: string;
+  /**
+   * Content classification supplied on the send. Null for inbound messages.
+   */
+  category?: SmsMessageCategory | null;
+  /**
+   * Segment breakdown for the body.
+   */
+  segments: SmsSegments;
+  /**
+   * Cost of the message. Null until the message has been priced.
+   */
+  cost?: SmsCost;
+  /**
+   * Structured `{name, value}` filter labels applied to this message.
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON metadata stored on the message and echoed in webhook payloads.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+  /**
+   * How long, in seconds, Bird keeps trying to deliver before the message transitions to `expired`.
+   */
+  readonly validity_period?: number;
+  /**
+   * Carrier that handled the message, when known. Populated once a delivery receipt identifies it.
+   */
+  readonly carrier?: string | null;
+  /**
+   * Mobile country code and mobile network code of the carrier, when known.
+   */
+  readonly mcc_mnc?: string | null;
+  /**
+   * Failure detail on a terminally failed or rejected message. Null otherwise.
+   */
+  last_error?: SmsError;
+  /**
+   * When the message was accepted (outbound) or received (inbound).
+   */
+  readonly created_at: string;
+  /**
+   * When the message was handed to the carrier. Null until then.
+   */
+  readonly sent_at?: string | null;
+  /**
+   * When delivery was confirmed. Null until then.
+   */
+  readonly delivered_at?: string | null;
+};
+/**
+ * Batch of SMS message send requests. All items are validated before any are queued.
+ */
+type SmsMessageBatchRequest = Array<SmsMessageSendRequest>;
+type SmsTemplateSend = unknown & {
+  /**
+   * The template to send, by its id.
+   */
+  id?: SmsTemplateId;
+  /**
+   * The template to send, by its name handle (for example `bird_otp_verification`). Browse the available templates and their variables with the templates endpoint.
+   *
+   */
+  name?: string;
+  /**
+   * Language tag (BCP 47, for example `fr` or `pt-BR`) selecting the localized body. Falls back to the closest available language, then English, when the exact tag is not stocked. Omit for English.
+   *
+   */
+  language?: string;
+  /**
+   * Values for the template's variables, keyed by variable name. The accepted keys and their formats are fixed per template — see the template's `variables` on the templates endpoint. Every required variable must be supplied, and no undeclared key may be present. Cap: 16 KB serialized.
+   *
+   */
+  parameters?: {
+    [key: string]: unknown;
+  };
+};
+type SmsMessageSendRequest = unknown & {
+  /**
+   * Recipient phone number in E.164 format (for example `+15551234567`). One recipient per message.
+   */
+  to: string;
+  /**
+   * Sender to send from: an E.164 number (`+15557654321`), an alphanumeric sender ID (up to 11 characters, for example `MyBrand`), or a short code (5–6 digits). When omitted, Bird selects an eligible sender for you.
+   *
+   */
+  from?: string;
+  /**
+   * Free-text message body. Required unless `template` is supplied (the two are mutually exclusive). At least 1 character, up to a 12-segment cap (roughly 1836 GSM-7 or 804 UCS-2 characters). Bird does not truncate; a body exceeding 12 segments is rejected with a 422. The limit is on segment count, not characters, because GSM-7 and UCS-2 encodings differ in characters per segment.
+   *
+   */
+  text?: string;
+  /**
+   * Content classification. Drives opt-out (STOP) policy, quiet-hours, and per-country compliance. Required on a free-text send; omit it on a template send, where the category is derived from the template.
+   *
+   */
+  category?: SmsMessageCategory;
+  /**
+   * Preview feature — how long, in seconds (60–172800), Bird keeps trying to deliver before the message transitions to `expired`. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   *
+   */
+  validity_period?: number;
+  /**
+   * Structured `{name, value}` labels for filtering and analytics. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics by tag, and surface in webhook payloads. Maximum 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`). For arbitrary structured context you do not need as a filter dimension, use `metadata` instead.
+   *
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON object stored on the message, returned on API reads, and echoed in webhook payloads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use `tags` instead.
+   *
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Preview feature — multimedia (MMS) attachments. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  media_urls?: Array<string>;
+  /**
+   * Preview feature — sender selection from a messaging profile pool. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  messaging_profile_id?: string;
+  /**
+   * Preview feature — send-later scheduling. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  scheduled_at?: string;
+  /**
+   * Send using a stored template instead of free text. Mutually exclusive with `text`; the message category is derived from the template, so `from`, `category`, and `media_urls` are not accepted alongside it.
+   *
+   */
+  template?: SmsTemplateSend;
+  /**
+   * Preview feature — broadcast correlation. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  broadcast_id?: string;
+  /**
+   * Preview feature — campaign correlation for analytics. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  campaign_id?: string;
+  /**
+   * Preview feature — audience-targeted sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  audience_id?: string;
+  /**
+   * Preview feature — contact-targeted sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  contact_id?: string;
+  /**
+   * Preview feature — topic-gated sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  topic_id?: string;
+  /**
+   * Preview feature — per-segment price ceiling. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  max_price_per_segment?: number;
+  /**
+   * Preview feature — per-recipient substitution for batch sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  personalization?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Preview feature — link click tracking. Defaults to `false`. Currently unavailable; setting this to `true` returns `422 unsupported_feature`.
+   */
+  track_clicks?: boolean;
+};
+type AudienceContactsRemoveRequest = {
+  /**
+   * Contacts to remove from the audience. Removing a contact that is not a member has no effect. If any ID does not exist, the whole request fails and no contacts are removed.
+   */
+  contact_ids: Array<ContactId>;
+};
+type AudienceContactsAddRequest = {
+  /**
+   * Contacts to add to the audience. Adding a contact that is already a member has no effect. If any ID does not exist, the whole request fails and no contacts are added.
+   */
+  contact_ids: Array<ContactId>;
+};
+type Contact = {
+  /**
+   * Contact ID.
+   */
+  readonly id: ContactId;
+  /**
+   * The contact's email address, stored trimmed and lowercased. Unique within the workspace.
+   */
+  email: string;
+  /**
+   * The contact's first name.
+   */
+  first_name?: string | null;
+  /**
+   * The contact's last name.
+   */
+  last_name?: string | null;
+  /**
+   * Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
+   */
+  external_id?: string | null;
+  /**
+   * Custom property values for this contact, available as template variables in broadcasts. Each key is a property created via the contact properties API, and each value is a string, number, or boolean matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized.
+   *
+   */
+  data?: {
+    [key: string]: unknown;
+  };
+} & Timestamps;
+type AudienceMember = {
+  contact: Contact;
+  /**
+   * When this contact joined the audience. Members are listed in join order, most recent first.
+   */
+  readonly joined_at: string;
+};
+type AudienceUpdateRequest = {
+  /**
+   * Display name for the audience.
+   */
+  name?: string;
+  /**
+   * Longer description of who this audience is. Set to null to clear.
+   */
+  description?: string | null;
+};
+type AudienceCreateRequest = {
+  /**
+   * Display name for the audience.
+   */
+  name: string;
+  /**
+   * Longer description of who this audience is.
+   */
+  description?: string;
+  /**
+   * How the audience's recipients are determined. `static` audiences have an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable — creating an audience with either returns an error.
+   *
+   */
+  type?: "static" | "dynamic" | "external";
+};
+type AudienceId = string;
+type Audience = {
+  /**
+   * Audience ID.
+   */
+  readonly id: AudienceId;
+  /**
+   * Display name for the audience.
+   */
+  name: string;
+  /**
+   * Longer description of who this audience is.
+   */
+  description?: string | null;
+  /**
+   * How the audience's recipients are determined. `static` audiences have an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable — creating an audience with either returns an error.
+   *
+   */
+  type: "static" | "dynamic" | "external";
+} & Timestamps;
+type ContactPropertyUpdateRequest = {
+  /**
+   * Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, or boolean matching the declared type (strings up to 500 characters). Set to null to remove the fallback.
+   */
+  fallback_value?: unknown;
+};
+type ContactPropertyCreateRequest = {
+  /**
+   * The property key, used as the key in contact data and as the template variable name in broadcasts. Lowercase letters, digits, and underscores, starting with a letter. Cannot be changed after creation.
+   */
+  key: string;
+  /**
+   * The value type every contact must use for this property. Cannot be changed after creation.
+   */
+  type: "string" | "number" | "boolean";
+  /**
+   * Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, or boolean matching the declared type (strings up to 500 characters), or null for no fallback.
+   */
+  fallback_value?: unknown;
+};
+type ContactPropertyId = string;
+type ContactProperty = {
+  /**
+   * Contact property ID.
+   */
+  readonly id: ContactPropertyId;
+  /**
+   * The property key, used as the key in contact data and as the template variable name in broadcasts. Lowercase letters, digits, and underscores, starting with a letter. Cannot be changed after creation.
+   */
+  key: string;
+  /**
+   * The value type every contact must use for this property. Cannot be changed after creation.
+   */
+  type: "string" | "number" | "boolean";
+  /**
+   * Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, or boolean matching the declared type (strings up to 500 characters), or null when no fallback is set.
+   */
+  fallback_value?: unknown;
+  /**
+   * Whether the property is archived. An archived property is rejected in new contact writes and stops rendering in templates, but every value already stored on contacts is preserved. Reactivate it with unarchive.
+   */
+  readonly archived?: boolean;
+} & Timestamps;
+type ContactUpdateRequest = {
+  /**
+   * New email address for the contact. Trimmed and lowercased before it is stored and checked for uniqueness. Must not be in use by another contact in the workspace.
+   */
+  email?: string;
+  /**
+   * The contact's first name. Set to null to clear.
+   */
+  first_name?: string | null;
+  /**
+   * The contact's last name. Set to null to clear.
+   */
+  last_name?: string | null;
+  /**
+   * Your own identifier for this contact. Unique within the workspace when set. Set to null to clear.
+   */
+  external_id?: string | null;
+  /**
+   * Custom property values to change, merged into the contact's existing data. Keys you supply are set, keys set to null are removed, and keys you omit are left unchanged. Each key must be a property created via the contact properties API, and each value must be a string, number, or boolean matching the property's declared type (strings up to 500 characters). The merged result is capped at 2 KB serialized.
+   *
+   */
+  data?: {
+    [key: string]: unknown;
+  };
+};
+type ContactUpsertResult = {
+  /**
+   * One entry per contact in the request, in submission order.
+   */
+  data: Array<ContactUpsertResultItem>;
+};
+type ContactUpsertError = {
+  /**
+   * Machine-readable error category for this entry, such as `validation_error` or `conflict_error`, in the same vocabulary as the top-level error `type`. New categories may be added over time, so treat unrecognized values as a generic failure.
+   */
+  type: string;
+  /**
+   * Human-readable explanation of why this entry failed.
+   */
+  message: string;
+};
+type ContactUpsertResultItem = {
+  /**
+   * Email address of the contact this entry refers to.
+   */
+  email: string;
+  /**
+   * What happened to this contact. A failed entry does not affect the other entries in the request.
+   */
+  status: "created" | "updated" | "failed";
+  /**
+   * ID of the created or updated contact. Absent when the entry failed.
+   */
+  contact_id?: ContactId;
+  /**
+   * Why this entry failed. Absent for successful entries.
+   */
+  error?: ContactUpsertError;
+};
+type ContactUpsertRequest = {
+  /**
+   * Contacts to create or update, matched by email address. Existing contacts are updated with the supplied fields; new ones are created.
+   */
+  contacts: Array<ContactCreateRequest>;
+  /**
+   * Audiences every contact in this request is added to. Contacts that are already members are left in place.
+   */
+  audience_ids?: Array<AudienceId>;
+  /**
+   * How a supplied `data` object is applied to an existing contact. `merge` (the default) merges the supplied keys onto the contact's stored custom values, and a key with a `null` value deletes that one key. `replace` overwrites the whole stored `data` map with the supplied one. In both modes a contact that omits `data` keeps its stored values unchanged, so an import that touches one attribute never wipes the others.
+   *
+   */
+  data_mode?: "merge" | "replace";
+};
+type ContactCreateRequest = {
+  /**
+   * The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace.
+   */
+  email: string;
+  /**
+   * The contact's first name.
+   */
+  first_name?: string;
+  /**
+   * The contact's last name.
+   */
+  last_name?: string;
+  /**
+   * Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
+   */
+  external_id?: string;
+  /**
+   * Custom property values for this contact. Each key must be a property created via the contact properties API, and each value must be a string, number, or boolean matching the property's declared type (strings up to 500 characters); a null value is ignored. Total size is capped at 2 KB serialized.
+   *
+   */
+  data?: {
+    [key: string]: unknown;
+  };
+};
+type EmailMessageBatchResponse = {
+  /**
+   * One entry per message in the batch, in submission order.
+   */
+  data: Array<EmailMessageBatchItem>;
+};
+type EmailMessageBatchItem = {
+  /**
+   * Message ID assigned to this batch item.
+   */
+  readonly id: EmailId;
+  /**
+   * Initial status of this message in the batch.
+   */
+  readonly status: "accepted";
+  /**
+   * Resolved category for this batch item.
+   */
+  category: "marketing" | "transactional";
+};
+/**
+ * Batch of email message send requests. All items are validated before any are queued. Attachments are allowed on individual messages. Each message must stay within the 20 MB estimated generated message-size cap. The serialized JSON request body for the batch has a hard 20 MB cap.
+ *
+ */
+type EmailMessageBatchRequest = Array<EmailMessageSendRequest>;
+type EmailTemplateSend = unknown & {
+  /**
+   * The template to send, by its id.
+   */
+  id?: EmailTemplateId;
+  /**
+   * The template to send, by its name handle (for example `welcome-email`).
+   */
+  name?: string;
+  /**
+   * Values for the template's variables, keyed by variable name. A token with no matching value renders empty. Cap: 16 KB serialized.
+   *
+   */
+  parameters?: {
+    [key: string]: unknown;
+  };
+};
+type EmailMessageSendRequest = {
+  /**
+   * Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name. Must be from a verified domain in this workspace.
+   */
+  from: EmailAddressInput;
+  /**
+   * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   */
+  to: Array<EmailAddressInput>;
+  /**
+   * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   */
+  cc?: Array<EmailAddressInput>;
+  /**
+   * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   */
+  bcc?: Array<EmailAddressInput>;
+  /**
+   * Message subject line. Required for inline sends; omit it when sending a `template` (the template supplies the subject).
+   */
+  subject?: string;
+  /**
+   * HTML body. At least one of html or text must be provided.
+   */
+  html?: string;
+  /**
+   * Plain-text body. At least one of html or text must be provided.
+   */
+  text?: string;
+  /**
+   * Reply-To addresses, each a plain email string, an RFC 5322 mailbox string, or an object with an optional display name. RFC 5322 allows multiple. Every recipient reply hits all listed addresses, so 1-2 is typical; the 25 cap exists to prevent runaway header sizes that some MTAs reject.
+   *
+   */
+  reply_to?: Array<EmailAddressInput>;
+  /**
+   * Custom email headers as key-value pairs (for example `References`, `In-Reply-To`, or your own `X-*` headers). Reserved headers are rejected with a `422`: set the message's addressing and subject through the dedicated fields (`from`, `to`, `cc`, `bcc`, `reply_to`, `subject`) rather than here, and headers the platform generates for you — `Content-Type`, `Content-Transfer-Encoding`, `DKIM-Signature`, `Received`, and `Return-Path` — cannot be overridden. `List-Unsubscribe` and `List-Unsubscribe-Post` are honored as-is on `transactional` sends; on `marketing` sends the platform sets a compliant unsubscribe header for you, so supplying them there is rejected with a `422`. Header values may not contain carriage-return or line-feed characters.
+   *
+   */
+  headers?: {
+    [key: string]: string;
+  };
+  /**
+   * Structured `{name, value}` labels for **filtering and analytics**. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics rollups by tag, and surface in webhook payloads. Cap: 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`, `template_id`). For arbitrary structured context that you do not need as a filter dimension, use `metadata` instead.
+   *
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON object **stored, returned on API reads, and echoed in webhook payloads**. Path-queryable in analytics (e.g. filter on `metadata.order_id`) but not surfaced as a first-class dashboard filter dimension. Cap: 2 KB serialized. Use metadata for per-send context like internal IDs, foreign keys, and structured payloads you want round-tripped through events. For low-cardinality filterable labels, use `tags` instead.
+   *
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Template variables used to personalize inline content. Tokens in the subject and body (e.g. `{{ first_name }}`) are replaced with these values at send time. Shared across all recipients of this send. A token with no matching key renders empty. Cap: 16 KB serialized. When sending a stored `template`, put the values in `template.parameters` instead.
+   *
+   */
+  parameters?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Send a stored template instead of inline content. When set, omit `subject`/`html`/`text` — the template supplies them; personalize with `template.parameters`.
+   *
+   */
+  template?: EmailTemplateSend;
+  /**
+   * Whether to track open events for this message.
+   */
+  track_opens?: boolean;
+  /**
+   * Whether to track click events for this message.
+   */
+  track_clicks?: boolean;
+  /**
+   * ID of the IP pool to send from (`ipp_` prefix), or `ipp_shared` to route through the shared pool explicitly. Omit to use your organization's default pool. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a `422`.
+   *
+   */
+  ip_pool_id?: string;
+  /**
+   * Content classification — independent of which endpoint you use. Controls suppression policy: `marketing` blocks on all suppression reasons (use for marketing content); `transactional` allows delivery through complaint and unsubscribe suppressions (use for receipts, password resets, and similar operational messages). Default: marketing.
+   *
+   */
+  category?: "marketing" | "transactional";
+  /**
+   * Preview feature — threaded replies. Currently unavailable; supplying this field returns `422 unsupported_feature`. When generally available, sets In-Reply-To and References headers automatically.
+   */
+  in_reply_to_message_id?: EmailId;
+  /**
+   * File attachments. Bird rejects sends whose estimated generated message size exceeds 20 MB. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. Keep total raw attachment content at or below 15 MB for reliable headroom. In batch sends, this per-message cap still applies and the serialized JSON request body for the whole batch has a hard 20 MB cap. See the EmailAttachment schema for the full field contract.
+   *
+   */
+  attachments?: Array<EmailAttachment>;
+  /**
+   * Preview feature — send-later scheduling. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  scheduled_at?: string;
+  /**
+   * Preview feature — contact-targeted sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+   */
+  contact_id?: string;
+  /**
+   * Preview feature — topic-gated sends. Currently unavailable; supplying this field returns `422 unsupported_feature`. When generally available, a non-empty `topic_id` gates delivery on the recipient's opt-in state for that topic — if the recipient is opt_out, the send is silently suppressed and an `email.suppressed` event fires with `reason: topic_opt_out`.
+   *
+   */
+  topic_id?: string;
+};
+type EmailAttachmentId = string;
+/**
+ * Attachment metadata returned on API reads. The original content is not echoed back inline — only the metadata needed for display and audit. To download the raw attachment bytes (while content storage is enabled and within the retention window), use `GET /v1/email/messages/{message_id}/attachments/{attachment_id}`, which returns the file with its own content type and a Content-Disposition filename.
+ *
+ */
+type EmailAttachmentRef = {
+  /**
+   * Attachment ID, stable per email send.
+   */
+  readonly id?: EmailAttachmentId;
+  /**
+   * Filename as shown to the recipient.
+   */
+  filename: string;
+  /**
+   * Resolved MIME type at send time.
+   */
+  content_type?: string;
+  /**
+   * Decoded size in bytes.
+   */
+  size: number;
+  /**
+   * True when the attachment was sent inline via a `content_id` reference in the HTML body, false for regular file attachments.
+   *
+   */
+  inline?: boolean;
+  /**
+   * The Content-ID set at send time, when the attachment was inline.
+   */
+  content_id?: string | null;
+};
+/**
+ * Aggregate delivery status of an email, derived from its recipients' states. `scheduled` means the message is queued to send at a future time and has not been dispatched yet; `canceled` means a scheduled message was canceled before it was sent.
+ *
+ */
+type EmailMessageStatus = "scheduled" | "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected" | "canceled";
+type EmailMessage = {
+  /**
+   * Message ID.
+   */
+  readonly id: EmailId;
+  /**
+   * Sender address. `name` is present when a display name was provided on the send.
+   */
+  from: EmailAddress;
+  /**
+   * Primary recipients. Length is the recipient count; use the broadcasts endpoint for audience-targeted sends. Each entry's `name` is present when a display name was provided on the send.
+   */
+  to: Array<EmailAddress>;
+  /**
+   * CC recipients.
+   */
+  cc?: Array<EmailAddress>;
+  /**
+   * BCC recipients.
+   */
+  bcc?: Array<EmailAddress>;
+  /**
+   * Message subject line.
+   */
+  subject: string;
+  /**
+   * Content classification. Controls suppression policy — `marketing` blocks on all suppression reasons; `transactional` allows delivery through complaint and unsubscribe suppressions.
+   *
+   */
+  category: "marketing" | "transactional";
+  /**
+   * Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
+   */
+  reply_to?: Array<EmailAddress> | null;
+  /**
+   * Aggregate delivery status derived from recipient states. `scheduled` means the message is queued to send at a future time and has not been dispatched yet. `accepted` means Bird has the send and is preparing to deliver. `processed` means Bird has processed the message and queued it for delivery to the recipient's mail server. `canceled` means a scheduled message was canceled before it was sent.
+   *
+   */
+  readonly status: EmailMessageStatus;
+  /**
+   * Number of recipients currently in the `accepted` state — Bird has the send and is preparing to deliver.
+   */
+  readonly accepted_count: number;
+  /**
+   * Number of recipients for whom Bird has processed the message and queued it for delivery.
+   */
+  readonly processed_count: number;
+  /**
+   * Number of recipients whose messages were accepted by the remote MTA.
+   */
+  readonly delivered_count: number;
+  /**
+   * Number of recipients that resulted in a permanent delivery failure.
+   */
+  readonly bounced_count: number;
+  /**
+   * Number of recipients that reported spam.
+   */
+  readonly complained_count: number;
+  /**
+   * Number of recipients in transient delivery deferral; the provider is retrying.
+   */
+  readonly deferred_count: number;
+  /**
+   * Number of recipients rejected before delivery. See the per-recipient `rejection_reason` field on `GET /v1/email/messages/{message_id}/recipients` for the specific cause (suppression match, transmission failure, generation failure, or policy refusal).
+   *
+   */
+  readonly rejected_count: number;
+  /**
+   * Time between Bird accepting the send and the message being processed for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches `processed`.
+   *
+   */
+  readonly processing_latency_ms?: number | null;
+  /**
+   * Time between the message being processed and the receiving mail server accepting it, in milliseconds, for the fastest delivered recipient. Null until the first recipient is delivered.
+   *
+   */
+  readonly delivery_latency_ms?: number | null;
+  /**
+   * End-to-end accept → delivered time for the fastest delivered recipient, in milliseconds. Null until the first recipient is delivered.
+   *
+   */
+  readonly total_latency_ms?: number | null;
+  /**
+   * Total open events across all recipients.
+   */
+  readonly open_count: number;
+  /**
+   * Total click events across all recipients.
+   */
+  readonly click_count: number;
+  /**
+   * Structured `{name, value}` filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed; use the future content-retrieval endpoint when storage is enabled.
+   */
+  attachments?: Array<EmailAttachmentRef>;
+  /**
+   * Whether open tracking is enabled for this send.
+   */
+  track_opens: boolean;
+  /**
+   * Whether click tracking is enabled for this send.
+   */
+  track_clicks: boolean;
+  /**
+   * When the send request was accepted.
+   */
+  readonly created_at: string;
+  /**
+   * Thread this message belongs to. Null until threading is enabled.
+   */
+  readonly thread_id?: string | null;
+  /**
+   * The message this one is a reply to, if any.
+   */
+  readonly in_reply_to_message_id?: EmailId | null;
+  /**
+   * When all recipients reached a terminal delivered state, or null if not yet fully delivered.
+   */
+  readonly delivered_at?: string | null;
+  /**
+   * When this message is scheduled to send, for a send created with a future send time. Null for an immediate send. Stays set after the scheduled send fires.
+   */
+  readonly scheduled_at?: string | null;
+};
+type ListEmailMessagesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+    /**
+     * Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
+     */
+    created_after?: string;
+    /**
+     * Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
+     */
+    created_before?: string;
+    /**
+     * Filter by aggregate delivery status.
+     */
+    status?: "scheduled" | "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected" | "canceled";
+    /**
+     * Filter by tag. Accepts `name` to match any send carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
+     *
+     */
+    tag?: Array<string>;
+    /**
+     * Filter by category.
+     */
+    category?: "marketing" | "transactional";
+    /**
+     * Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message; normalised to lowercase before comparison.
+     *
+     */
+    to?: string;
+    /**
+     * Filter by sender address. Exact match against the message `from` field; normalised to lowercase before comparison.
+     *
+     */
+    from?: string;
+  };
+  url: "/v1/email/messages";
+};
+type ListContactsData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact.
+     */
+    email?: string;
+    /**
+     * Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact.
+     */
+    external_id?: string;
+    /**
+     * Case-insensitive substring match against the contact's email address.
+     */
+    search?: string;
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+  };
+  url: "/v1/contacts";
+};
+type ListContactPropertiesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+  };
+  url: "/v1/contact-properties";
+};
+type ListAudiencesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+  };
+  url: "/v1/audiences";
+};
+type ListAudienceContactsData = {
+  body?: never;
+  path: {
+    /**
+     * Audience ID.
+     */
+    audience_id: AudienceId;
+  };
+  query?: {
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+  };
+  url: "/v1/audiences/{audience_id}/contacts";
+};
+type ListSmsMessagesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+    /**
+     * Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
+     */
+    created_after?: string;
+    /**
+     * Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
+     */
+    created_before?: string;
+    /**
+     * Filter by direction. Omit for both.
+     */
+    direction?: "outbound" | "inbound";
+    /**
+     * Filter by status; repeat the parameter to match any of several. One of scheduled, accepted, sent, delivered, undelivered, failed, rejected, canceled, expired, or received.
+     *
+     */
+    status?: Array<string>;
+    /**
+     * Filter to messages whose failure reason matches one of the supplied values; repeat the parameter to match any of several. One of invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, or unknown.
+     *
+     */
+    error_code?: Array<string>;
+    /**
+     * Filter by category.
+     */
+    category?: "transactional" | "marketing" | "authentication" | "service";
+    /**
+     * Filter by recipient phone number (E.164 exact match).
+     */
+    to?: string;
+    /**
+     * Filter by sender (E.164, alphanumeric, or short code — exact match).
+     */
+    from?: string;
+    /**
+     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair. Repeat the parameter to AND-combine several tag filters.
+     *
+     */
+    tag?: Array<string>;
+  };
+  url: "/v1/sms/messages";
+};
+type ListSmsTemplatesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Filter by scope. Omit for all.
+     */
+    scope?: "system" | "workspace";
+    /**
+     * Filter by category.
+     */
+    category?: "transactional" | "marketing" | "authentication" | "service";
+    /**
+     * Keep only templates available in this language, as a BCP-47 tag.
+     */
+    language?: string;
+  };
+  url: "/v1/sms/templates";
+};
+type ListEmailTemplatesData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * Filter by template category.
+     */
+    category?: EmailTemplateCategory;
+    /**
+     * Filter by authoring format.
+     */
+    source?: EmailTemplateSource;
+    /**
+     * Case-insensitive search matching the template's name or description (substring).
+     */
+    name?: string;
+    /**
+     * Maximum number of items to return per page.
+     */
+    limit?: number;
+    /**
+     * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+     */
+    starting_after?: string;
+    /**
+     * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+     */
+    ending_before?: string;
+  };
+  url: "/v1/email/templates";
+};
+//#endregion
+//#region src/generated/core/auth.gen.d.ts
+type AuthToken = string | undefined;
+interface Auth {
+  /**
+   * Which part of the request do we use to send the auth?
+   *
+   * @default 'header'
+   */
+  in?: "header" | "query" | "cookie";
+  /**
+   * Header or query parameter name.
+   *
+   * @default 'Authorization'
+   */
+  name?: string;
+  scheme?: "basic" | "bearer";
+  type: "apiKey" | "http";
+}
+//#endregion
+//#region src/generated/core/pathSerializer.gen.d.ts
+interface SerializerOptions<T> {
+  /**
+   * @default true
+   */
+  explode: boolean;
+  style: T;
+}
+type ArrayStyle = "form" | "spaceDelimited" | "pipeDelimited";
+type ObjectStyle = "form" | "deepObject";
+//#endregion
+//#region src/generated/core/bodySerializer.gen.d.ts
+type QuerySerializer = (query: Record<string, unknown>) => string;
+type BodySerializer = (body: unknown) => unknown;
+type QuerySerializerOptionsObject = {
+  allowReserved?: boolean;
+  array?: Partial<SerializerOptions<ArrayStyle>>;
+  object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+type QuerySerializerOptions = QuerySerializerOptionsObject & {
+  /**
+   * Per-parameter serialization overrides. When provided, these settings
+   * override the global array/object settings for specific parameter names.
+   */
+  parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+//#endregion
+//#region src/generated/core/types.gen.d.ts
+type HttpMethod = "connect" | "delete" | "get" | "head" | "options" | "patch" | "post" | "put" | "trace";
+type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+  /**
+   * Returns the final request URL.
+   */
+  buildUrl: BuildUrlFn;
+  getConfig: () => Config;
+  request: RequestFn;
+  setConfig: (config: Config) => Config;
+} & { [K in HttpMethod]: MethodFn } & ([SseFn] extends [never] ? {
+  sse?: never;
+} : {
+  sse: { [K in HttpMethod]: SseFn };
+});
+interface Config$1 {
+  /**
+   * Auth token or a function returning auth token. The resolved value will be
+   * added to the request payload as defined by its `security` array.
+   */
+  auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+  /**
+   * A function for serializing request body parameter. By default,
+   * {@link JSON.stringify()} will be used.
+   */
+  bodySerializer?: BodySerializer | null;
+  /**
+   * An object containing any HTTP headers that you want to pre-populate your
+   * `Headers` object with.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+   */
+  headers?: RequestInit["headers"] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+  /**
+   * The request method.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+   */
+  method?: Uppercase<HttpMethod>;
+  /**
+   * A function for serializing request query parameters. By default, arrays
+   * will be exploded in form style, objects will be exploded in deepObject
+   * style, and reserved characters are percent-encoded.
+   *
+   * This method will have no effect if the native `paramsSerializer()` Axios
+   * API function is used.
+   *
+   * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+   */
+  querySerializer?: QuerySerializer | QuerySerializerOptions;
+  /**
+   * A function validating request data. This is useful if you want to ensure
+   * the request conforms to the desired shape, so it can be safely sent to
+   * the server.
+   */
+  requestValidator?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function transforming response data before it's returned. This is useful
+   * for post-processing data, e.g., converting ISO strings into Date objects.
+   */
+  responseTransformer?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function validating response data. This is useful if you want to ensure
+   * the response conforms to the desired shape, so it can be safely passed to
+   * the transformers and returned to the user.
+   */
+  responseValidator?: (data: unknown) => Promise<unknown>;
+}
+//#endregion
+//#region src/generated/core/serverSentEvents.gen.d.ts
+type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, "method"> & Pick<Config$1, "method" | "responseTransformer" | "responseValidator"> & {
+  /**
+   * Fetch API implementation. You can use this option to provide a custom
+   * fetch instance.
+   *
+   * @default globalThis.fetch
+   */
+  fetch?: typeof fetch;
+  /**
+   * Implementing clients can call request interceptors inside this hook.
+   */
+  onRequest?: (url: string, init: RequestInit) => Promise<Request>;
+  /**
+   * Callback invoked when a network or parsing error occurs during streaming.
+   *
+   * This option applies only if the endpoint returns a stream of events.
+   *
+   * @param error The error that occurred.
+   */
+  onSseError?: (error: unknown) => void;
+  /**
+   * Callback invoked when an event is streamed from the server.
+   *
+   * This option applies only if the endpoint returns a stream of events.
+   *
+   * @param event Event streamed from the server.
+   * @returns Nothing (void).
+   */
+  onSseEvent?: (event: StreamEvent<TData>) => void;
+  serializedBody?: RequestInit["body"];
+  /**
+   * Default retry delay in milliseconds.
+   *
+   * This option applies only if the endpoint returns a stream of events.
+   *
+   * @default 3000
+   */
+  sseDefaultRetryDelay?: number;
+  /**
+   * Maximum number of retry attempts before giving up.
+   */
+  sseMaxRetryAttempts?: number;
+  /**
+   * Maximum retry delay in milliseconds.
+   *
+   * Applies only when exponential backoff is used.
+   *
+   * This option applies only if the endpoint returns a stream of events.
+   *
+   * @default 30000
+   */
+  sseMaxRetryDelay?: number;
+  /**
+   * Optional sleep function for retry backoff.
+   *
+   * Defaults to using `setTimeout`.
+   */
+  sseSleepFn?: (ms: number) => Promise<void>;
+  url: string;
+};
+interface StreamEvent<TData = unknown> {
+  data: TData;
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
+  stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+};
+//#endregion
+//#region src/generated/client/utils.gen.d.ts
+type ErrInterceptor<Err, Res, Req, Options> = (error: Err, /** response may be undefined due to a network error where no response object is produced */
+
+response: Res | undefined, /** request may be undefined, because error may be from building the request object itself */
+
+request: Req | undefined, options: Options) => Err | Promise<Err>;
+type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
+type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
+declare class Interceptors<Interceptor> {
+  fns: Array<Interceptor | null>;
+  clear(): void;
+  eject(id: number | Interceptor): void;
+  exists(id: number | Interceptor): boolean;
+  getInterceptorIndex(id: number | Interceptor): number;
+  update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
+  use(fn: Interceptor): number;
+}
+interface Middleware<Req, Res, Err, Options> {
+  error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
+  request: Interceptors<ReqInterceptor<Req, Options>>;
+  response: Interceptors<ResInterceptor<Res, Req, Options>>;
+}
+//#endregion
+//#region src/generated/client/types.gen.d.ts
+type ResponseStyle = "data" | "fields";
+interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, "body" | "headers" | "method">, Config$1 {
+  /**
+   * Base URL for all requests made by this client.
+   */
+  baseUrl?: T["baseUrl"];
+  /**
+   * Fetch API implementation. You can use this option to provide a custom
+   * fetch instance.
+   *
+   * @default globalThis.fetch
+   */
+  fetch?: typeof fetch;
+  /**
+   * Please don't use the Fetch client for Next.js applications. The `next`
+   * options won't have any effect.
+   *
+   * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
+   */
+  next?: never;
+  /**
+   * Return the response data parsed in a specified format. By default, `auto`
+   * will infer the appropriate method from the `Content-Type` response header.
+   * You can override this behavior with any of the {@link Body} methods.
+   * Select `stream` if you don't want to parse response data at all.
+   *
+   * @default 'auto'
+   */
+  parseAs?: "arrayBuffer" | "auto" | "blob" | "formData" | "json" | "stream" | "text";
+  /**
+   * Should we return only data or multiple fields (data, error, response, etc.)?
+   *
+   * @default 'fields'
+   */
+  responseStyle?: ResponseStyle;
+  /**
+   * Throw an error instead of returning it in the response?
+   *
+   * @default false
+   */
+  throwOnError?: T["throwOnError"];
+}
+interface RequestOptions$1<TData = unknown, TResponseStyle extends ResponseStyle = "fields", ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+  responseStyle: TResponseStyle;
+  throwOnError: ThrowOnError;
+}>, Pick<ServerSentEventsOptions<TData>, "onRequest" | "onSseError" | "onSseEvent" | "sseDefaultRetryDelay" | "sseMaxRetryAttempts" | "sseMaxRetryDelay"> {
+  /**
+   * Any body that you want to add to your request.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+   */
+  body?: unknown;
+  path?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  /**
+   * Security mechanism(s) to use for the request.
+   */
+  security?: ReadonlyArray<Auth>;
+  url: Url;
+}
+interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = "fields", ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions$1<unknown, TResponseStyle, ThrowOnError, Url> {
+  headers: Headers;
+  serializedBody?: string;
+}
+type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = "fields"> = ThrowOnError extends true ? Promise<TResponseStyle extends "data" ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+  data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+  request: Request;
+  response: Response;
+}> : Promise<TResponseStyle extends "data" ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
+  data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+  error: undefined;
+} | {
+  data: undefined;
+  error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+}) & {
+  /** request may be undefined, because error may be from building the request object itself */request?: Request; /** response may be undefined, because error may be from building the request object itself or from a network error */
+  response?: Response;
+}>;
+interface ClientOptions {
+  baseUrl?: string;
+  responseStyle?: ResponseStyle;
+  throwOnError?: boolean;
+}
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions$1<TData, TResponseStyle, ThrowOnError>, "method">) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type SseFn = <TData = unknown, _TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions$1<never, TResponseStyle, ThrowOnError>, "method">) => Promise<ServerSentEventsResult<TData>>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions$1<TData, TResponseStyle, ThrowOnError>, "method"> & Pick<Required<RequestOptions$1<TData, TResponseStyle, ThrowOnError>>, "method">) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type BuildUrlFn = <TData extends {
+  body?: unknown;
+  path?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  url: string;
+}>(options: TData & Options<TData>) => string;
+type Client = Client$1<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
+  interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
+};
+interface TDataShape {
+  body?: unknown;
+  headers?: unknown;
+  path?: unknown;
+  query?: unknown;
+  url: string;
+}
+type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = "fields"> = OmitKeys<RequestOptions$1<TResponse, TResponseStyle, ThrowOnError>, "body" | "path" | "query" | "url"> & ([TData] extends [never] ? unknown : Omit<TData, "url">);
+//#endregion
+//#region src/resources/base.d.ts
+/** Resolved per-attempt inputs handed to the hey-api SDK call. */
+interface CallContext {
+  signal: AbortSignal;
+  /** Merged headers: caller `headers` plus the resolved `Idempotency-Key`. */
+  headers: Record<string, string>;
+}
+declare abstract class Resource {
+  protected readonly core: BirdHTTPClient;
+  protected readonly client: Client;
+  constructor(core: BirdHTTPClient, client: Client);
+  /** Run a single typed call through the lifecycle. */
+  protected call<T>(method: string, options: RequestOptions | undefined, invoke: (ctx: CallContext) => Promise<FetchOutcome<T>>): APIPromise<T>;
+  /** Run a cursor-paginated list through the lifecycle (each page retried independently). */
+  protected paginated<T>(method: string, options: RequestOptions | undefined, invoke: (ctx: CallContext, cursor: string | undefined) => Promise<FetchOutcome<CursorPage<T>>>): PaginatedPromise<T>;
+}
+//#endregion
+//#region src/resources/email.d.ts
+/** Body for `bird.email.send`. */
+type EmailSendParams = EmailMessageSendRequest;
+/** Body for `bird.email.sendBatch` — an array of send params, validated as a unit. */
+type EmailSendBatchParams = EmailMessageBatchRequest;
+/** Result of `bird.email.sendBatch` — one accepted item per submitted message. */
+type EmailSendBatchResult = EmailMessageBatchResponse;
+/** Filters and cursor params for `bird.email.list`. */
+type EmailListQuery = NonNullable<ListEmailMessagesData["query"]>;
+/**
+ * Channel-level defaults set at client construction. Field names mirror the
+ * send params (so they read as pre-filled fields). Any field set here becomes
+ * optional in `send` and is filled when omitted (per-send value wins).
+ */
+type EmailChannelDefaults = Partial<Pick<EmailSendParams, "from" | "reply_to" | "category" | "track_opens" | "track_clicks" | "headers" | "tags" | "metadata">>;
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/** Keys that carry a configured default — made optional in `send`. */
+type DefaultedKeys<D> = D extends object ? Extract<keyof D, keyof EmailSendParams> : never;
+/** `send` params with defaulted fields made optional. */
+type EmailSend<D> = PartialBy<EmailSendParams, DefaultedKeys<D>>;
+declare class EmailResource<D extends EmailChannelDefaults | undefined = undefined> extends Resource {
+  #private;
+  constructor(core: ConstructorParameters<typeof Resource>[0], client: ConstructorParameters<typeof Resource>[1], defaults?: D);
+  /**
+   * Send an email message. Resolves once the message is accepted for delivery
+   * (the API's 202). Throws on failure — a 422 (unverified sender, all
+   * recipients suppressed, validation) is a `BirdValidationError`. Fields set as
+   * channel defaults may be omitted (per-send value wins).
+   *
+   * @example Send a message
+   * const msg = await bird.email.send({
+   *   from: { email: "onboarding@messagebird.dev", name: "Bird" },
+   *   to: ["delivered@messagebird.dev"],
+   *   subject: "Hello from Bird",
+   *   html: "<p>My first Bird email.</p>",
+   * });
+   * console.log(msg.id, msg.status); // "em_…", "accepted"
+   *
+   * @example A richer send — cc/bcc, reply-to, tags, metadata, click-tracking off, and an idempotency key (safe to retry; the server dedupes)
+   * await bird.email.send(
+   *   {
+   *     from: "hello@acme.com",
+   *     to: ["a@example.com", "b@example.com"],
+   *     cc: ["manager@example.com"],
+   *     reply_to: ["support@acme.com"],
+   *     subject: "Your March invoice",
+   *     html: "<p>Attached.</p>",
+   *     tags: [{ name: "category", value: "billing" }],
+   *     metadata: { invoice_id: "inv_123" },
+   *     track_clicks: false,
+   *   },
+   *   { idempotencyKey: "invoice-march/cust_1" },
+   * );
+   *
+   * @example Branch on the typed error hierarchy
+   * import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
+   *
+   * try {
+   *   await bird.email.send({
+   *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+   *     to: ["delivered@messagebird.dev"],
+   *     subject: "Hello from Bird",
+   *     html: "<p>My first Bird email.</p>",
+   *   });
+   * } catch (err) {
+   *   if (err instanceof BirdRateLimitError) console.log(`rate limited — retry in ${err.retryAfter}s`);
+   *   else if (err instanceof BirdValidationError) console.error(err.details);
+   *   else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
+   *   else throw err;
+   * }
+   *
+   * @example Errors as values with `.safe()`
+   * const { data, error } = await bird.email
+   *   .send({
+   *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+   *     to: ["delivered@messagebird.dev"],
+   *     subject: "Hello from Bird",
+   *     html: "<p>My first Bird email.</p>",
+   *   })
+   *   .safe();
+   * if (error) console.error(error.message);
+   * else console.log(data.id);
+   */
+  send(params: EmailSend<D>, options?: RequestOptions): APIPromise<EmailMessage>;
+  /**
+   * Send a batch of up to 100 independent email messages in one request. The
+   * batch is validated as a unit — if any item fails validation (unverified
+   * sender, all recipients suppressed, field-level errors) the whole batch is
+   * rejected with a `BirdValidationError` and nothing is queued. Resolves with
+   * one accepted item per submitted message, in submission order, once the batch
+   * is accepted (the API's 202). Channel defaults are applied per item.
+   *
+   * @example Send a batch of messages
+   * const batch = await bird.email.sendBatch([
+   *   {
+   *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+   *     to: ["alice@example.com"],
+   *     subject: "Your receipt",
+   *     html: "<p>Thanks, Alice.</p>",
+   *   },
+   *   {
+   *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+   *     to: ["bob@example.com"],
+   *     subject: "Your receipt",
+   *     html: "<p>Thanks, Bob.</p>",
+   *   },
+   * ]);
+   * for (const item of batch.data) console.log(item.id, item.status);
+   */
+  sendBatch(params: EmailSendBatchParams, options?: RequestOptions): APIPromise<EmailSendBatchResult>;
+  /**
+   * Fetch a message with aggregate delivery status.
+   *
+   * @example
+   * const msg = await bird.email.get("em_abc123");
+   * msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
+   * msg.delivered_count;
+   * msg.bounced_count;
+   */
+  get(messageId: string, options?: RequestOptions): APIPromise<EmailMessage>;
+  /**
+   * List messages, newest first. `await` resolves the first page; `for await`
+   * walks every message across all pages.
+   *
+   * @example Iterate every message, or take one page
+   * for await (const message of bird.email.list({ status: "bounced" })) {
+   *   console.log(message.id);
+   * }
+   * const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
+   */
+  list(query?: EmailListQuery, options?: RequestOptions): PaginatedPromise<EmailMessage>;
+}
+//#endregion
+//#region src/resources/audiences.d.ts
+/** Body for `bird.audiences.create`. */
+type AudienceCreateParams = AudienceCreateRequest;
+/** Body for `bird.audiences.update` — a partial patch. */
+type AudienceUpdateParams = AudienceUpdateRequest;
+/** Body for `bird.audiences.addContacts`. */
+type AudienceAddContactsParams = AudienceContactsAddRequest;
+/** Body for `bird.audiences.removeContacts`. */
+type AudienceRemoveContactsParams = AudienceContactsRemoveRequest;
+/** Filters and cursor params for `bird.audiences.list`. */
+type AudienceListQuery = NonNullable<ListAudiencesData["query"]>;
+/** Cursor params for `bird.audiences.listContacts`. */
+type AudienceContactsQuery = NonNullable<ListAudienceContactsData["query"]>;
+declare class AudiencesResource extends Resource {
+  /**
+   * Create an audience.
+   *
+   * @example Create an audience
+   * const audience = await bird.audiences.create({ name: "Newsletter subscribers" });
+   * console.log(audience.id); // "aud_…"
+   */
+  create(params: AudienceCreateParams, options?: RequestOptions): APIPromise<Audience>;
+  /**
+   * List the workspace's audiences, newest first. `await` resolves the first
+   * page; `for await` walks every audience across pages.
+   *
+   * @example
+   * for await (const audience of bird.audiences.list()) {
+   *   console.log(audience.id, audience.name);
+   * }
+   */
+  list(query?: AudienceListQuery, options?: RequestOptions): PaginatedPromise<Audience>;
+  /**
+   * Fetch a single audience by id.
+   *
+   * @example
+   * const audience = await bird.audiences.get("aud_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  get(audienceId: string, options?: RequestOptions): APIPromise<Audience>;
+  /**
+   * Update an audience. Only the fields you send change.
+   *
+   * @example
+   * await bird.audiences.update("aud_01krdgeqcxet5s7t44vh8rt9mg", { name: "Renamed" });
+   */
+  update(audienceId: string, params: AudienceUpdateParams, options?: RequestOptions): APIPromise<Audience>;
+  /**
+   * Delete an audience. Its contacts are unaffected.
+   *
+   * @example
+   * await bird.audiences.delete("aud_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  delete(audienceId: string, options?: RequestOptions): APIPromise<void>;
+  /**
+   * List the contacts in an audience, newest first. `await` resolves the first
+   * page; `for await` walks every member across pages.
+   *
+   * @example
+   * for await (const member of bird.audiences.listContacts("aud_01krdgeqcxet5s7t44vh8rt9mg")) {
+   *   console.log(member.contact.id, member.joined_at);
+   * }
+   */
+  listContacts(audienceId: string, query?: AudienceContactsQuery, options?: RequestOptions): PaginatedPromise<AudienceMember>;
+  /**
+   * Add contacts to an audience by id.
+   *
+   * @example
+   * await bird.audiences.addContacts("aud_01krdgeqcxet5s7t44vh8rt9mg", {
+   *   contact_ids: ["con_1", "con_2"],
+   * });
+   */
+  addContacts(audienceId: string, params: AudienceAddContactsParams, options?: RequestOptions): APIPromise<void>;
+  /**
+   * Remove a set of contacts from an audience.
+   *
+   * @example
+   * await bird.audiences.removeContacts("aud_01krdgeqcxet5s7t44vh8rt9mg", {
+   *   contact_ids: ["con_1", "con_2"],
+   * });
+   */
+  removeContacts(audienceId: string, params: AudienceRemoveContactsParams, options?: RequestOptions): APIPromise<void>;
+  /**
+   * Remove a single contact from an audience.
+   *
+   * @example
+   * await bird.audiences.removeContact("aud_01krdgeqcxet5s7t44vh8rt9mg", "con_1");
+   */
+  removeContact(audienceId: string, contactId: string, options?: RequestOptions): APIPromise<void>;
+}
+//#endregion
+//#region src/resources/contactProperties.d.ts
+/** Body for `bird.contactProperties.create`. */
+type ContactPropertyCreateParams = ContactPropertyCreateRequest;
+/** Body for `bird.contactProperties.update` — a partial patch. */
+type ContactPropertyUpdateParams = ContactPropertyUpdateRequest;
+/** Filters and cursor params for `bird.contactProperties.list`. */
+type ContactPropertyListQuery = NonNullable<ListContactPropertiesData["query"]>;
+declare class ContactPropertiesResource extends Resource {
+  /**
+   * Define a contact property. The `key` must be unique in the workspace and is
+   * how contacts reference the field in their `data`.
+   *
+   * @example
+   * const prop = await bird.contactProperties.create({ key: "plan", type: "string" });
+   * console.log(prop.id); // "cp_…"
+   */
+  create(params: ContactPropertyCreateParams, options?: RequestOptions): APIPromise<ContactProperty>;
+  /**
+   * List the workspace's contact properties. `await` resolves the first page;
+   * `for await` walks every property across pages.
+   *
+   * @example
+   * for await (const prop of bird.contactProperties.list()) {
+   *   console.log(prop.key, prop.type);
+   * }
+   */
+  list(query?: ContactPropertyListQuery, options?: RequestOptions): PaginatedPromise<ContactProperty>;
+  /**
+   * Fetch a single contact property by id.
+   *
+   * @example
+   * const prop = await bird.contactProperties.get("cp_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  get(propertyId: string, options?: RequestOptions): APIPromise<ContactProperty>;
+  /**
+   * Update a contact property. Only the fields you send change.
+   *
+   * @example
+   * await bird.contactProperties.update("cp_01krdgeqcxet5s7t44vh8rt9mg", { fallback_value: "free" });
+   */
+  update(propertyId: string, params: ContactPropertyUpdateParams, options?: RequestOptions): APIPromise<ContactProperty>;
+  /**
+   * Archive a contact property, retiring the field without deleting its data.
+   *
+   * @example
+   * await bird.contactProperties.archive("cp_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  archive(propertyId: string, options?: RequestOptions): APIPromise<ContactProperty>;
+  /**
+   * Restore an archived contact property.
+   *
+   * @example
+   * await bird.contactProperties.unarchive("cp_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  unarchive(propertyId: string, options?: RequestOptions): APIPromise<ContactProperty>;
+}
+//#endregion
+//#region src/resources/contacts.d.ts
+/** Body for `bird.contacts.create`. */
+type ContactCreateParams = ContactCreateRequest;
+/** Body for `bird.contacts.update` — a partial patch. */
+type ContactUpdateParams = ContactUpdateRequest;
+/** Body for `bird.contacts.batch` — create-or-update many contacts in one call. */
+type ContactBatchParams = ContactUpsertRequest;
+/** Filters and cursor params for `bird.contacts.list`. */
+type ContactListQuery = NonNullable<ListContactsData["query"]>;
+declare class ContactsResource extends Resource {
+  /**
+   * Create a contact. `email` is required and unique within the workspace; set
+   * custom fields via `data` (each key a property defined in contact properties).
+   *
+   * @example Create a contact
+   * const contact = await bird.contacts.create({
+   *   email: "jane@acme.com",
+   *   first_name: "Jane",
+   * });
+   * console.log(contact.id); // "con_…"
+   */
+  create(params: ContactCreateParams, options?: RequestOptions): APIPromise<Contact>;
+  /**
+   * List the workspace's contacts, newest first. `await` resolves the first page;
+   * `for await` walks every contact across pages. Filter by `email`,
+   * `external_id`, or a `search` term.
+   *
+   * @example Iterate every contact, or take one page
+   * for await (const contact of bird.contacts.list({ search: "acme.com" })) {
+   *   console.log(contact.id, contact.email);
+   * }
+   * const page = await bird.contacts.list({ limit: 50 }); // page.data, page.next_cursor
+   */
+  list(query?: ContactListQuery, options?: RequestOptions): PaginatedPromise<Contact>;
+  /**
+   * Fetch a single contact by id.
+   *
+   * @example
+   * const contact = await bird.contacts.get("con_01krdgeqcxet5s7t44vh8rt9mg");
+   * contact.email;
+   */
+  get(contactId: string, options?: RequestOptions): APIPromise<Contact>;
+  /**
+   * Update a contact. Only the fields you send change.
+   *
+   * @example
+   * const contact = await bird.contacts.update("con_01krdgeqcxet5s7t44vh8rt9mg", {
+   *   first_name: "Jane",
+   * });
+   */
+  update(contactId: string, params: ContactUpdateParams, options?: RequestOptions): APIPromise<Contact>;
+  /**
+   * Delete a contact by id.
+   *
+   * @example
+   * await bird.contacts.delete("con_01krdgeqcxet5s7t44vh8rt9mg");
+   */
+  delete(contactId: string, options?: RequestOptions): APIPromise<void>;
+  /**
+   * Create or update many contacts in one call, matched by email. Returns a
+   * per-contact result.
+   *
+   * @example
+   * const result = await bird.contacts.batch({
+   *   contacts: [{ email: "jane@acme.com", first_name: "Jane" }],
+   * });
+   */
+  batch(params: ContactBatchParams, options?: RequestOptions): APIPromise<ContactUpsertResult>;
+}
+//#endregion
+//#region src/resources/emailTemplates.d.ts
+/** Body for `bird.emailTemplates.create`. */
+type EmailTemplateCreateParams = EmailTemplateCreate;
+/** Body for `bird.emailTemplates.update` — a partial patch of the draft. */
+type EmailTemplateUpdateParams = EmailTemplateUpdate;
+/** Filters and cursor params for `bird.emailTemplates.list`. */
+type EmailTemplateListQuery = NonNullable<ListEmailTemplatesData["query"]>;
+declare class EmailTemplatesResource extends Resource {
+  /**
+   * Create a template and its initial editable draft. Pick the authoring format
+   * with `source` (`liquid`, `handlebars`, or `html`); the name must be unique
+   * in the workspace or the call throws a `BirdConflictError`.
+   *
+   * @example Create a template
+   * const tpl = await bird.emailTemplates.create({
+   *   name: "welcome-email",
+   *   description: "Welcome",
+   *   category: "transactional",
+   *   source: "handlebars",
+   *   subject: "Welcome, {{ first_name }}!",
+   *   html: "<h1>Hi {{ first_name }}</h1>",
+   * });
+   * console.log(tpl.id, tpl.revision); // "emt_…", 0
+   */
+  create(params: EmailTemplateCreateParams, options?: RequestOptions): APIPromise<EmailTemplate>;
+  /**
+   * List the workspace's templates, newest first. `await` resolves the first
+   * page; `for await` walks every template across all pages. Filter by
+   * `category`, `source`, or a case-insensitive `name` prefix.
+   *
+   * @example Iterate every template, or take one page
+   * for await (const tpl of bird.emailTemplates.list({ category: "transactional" })) {
+   *   console.log(tpl.id, tpl.name);
+   * }
+   * const page = await bird.emailTemplates.list({ limit: 50 }); // page.data, page.next_cursor
+   */
+  list(query?: EmailTemplateListQuery, options?: RequestOptions): PaginatedPromise<EmailTemplateSummary>;
+  /**
+   * Fetch a template with its current draft content (subject, HTML, text), the
+   * draft `revision`, and its draft/published version ids.
+   *
+   * @example
+   * const tpl = await bird.emailTemplates.get("emt_abc123");
+   * tpl.subject;
+   * tpl.published_version_id; // null until first publish
+   */
+  get(templateId: string, options?: RequestOptions): APIPromise<EmailTemplate>;
+  /**
+   * Update a template's metadata and draft content. Only the fields you send
+   * change. Pass the draft `revision` you last read; if another edit landed
+   * first the call throws a `BirdConflictError` — reload and retry.
+   *
+   * @example Edit the draft, guarded by the revision you read
+   * const tpl = await bird.emailTemplates.get("emt_abc123");
+   * const updated = await bird.emailTemplates.update("emt_abc123", {
+   *   revision: tpl.revision,
+   *   subject: "Welcome aboard, {{ first_name }}!",
+   * });
+   */
+  update(templateId: string, params: EmailTemplateUpdateParams, options?: RequestOptions): APIPromise<EmailTemplate>;
+  /**
+   * Delete a template and all its versions. The name becomes available for
+   * reuse in the workspace.
+   *
+   * @example
+   * await bird.emailTemplates.delete("emt_abc123");
+   */
+  delete(templateId: string, options?: RequestOptions): APIPromise<void>;
+  /**
+   * Publish the current draft as a new immutable, numbered version and make it
+   * the live version used by sends. The draft stays editable. The draft must
+   * have a subject and a body, or the call throws.
+   *
+   * @example Publish, then send by template
+   * const version = await bird.emailTemplates.publish("emt_abc123");
+   * console.log(version.version_number); // 1, 2, 3…
+   * await bird.email.send({
+   *   from: "hello@acme.com",
+   *   to: ["alice@example.com"],
+   *   template: { id: "emt_abc123", parameters: { first_name: "Alice" } },
+   * });
+   */
+  publish(templateId: string, options?: RequestOptions): APIPromise<EmailTemplateVersion>;
+  /**
+   * List every version of a template — the current draft plus all published
+   * versions — newest first. Returns the full set in one response (`.data`);
+   * this list is not paginated.
+   *
+   * @example
+   * const { data } = await bird.emailTemplates.listVersions("emt_abc123");
+   * for (const v of data) console.log(v.version_number, v.status);
+   */
+  listVersions(templateId: string, options?: RequestOptions): APIPromise<EmailTemplateVersionList>;
+  /**
+   * Fetch a single version of a template.
+   *
+   * @example
+   * const version = await bird.emailTemplates.getVersion("emt_abc123", "emv_def456");
+   * version.status; // "draft" | "published"
+   */
+  getVersion(templateId: string, versionId: string, options?: RequestOptions): APIPromise<EmailTemplateVersion>;
+}
+//#endregion
+//#region src/resources/sms.d.ts
+/** Body for `bird.sms.send` — supply either `text` (with `category`) or `template`. */
+type SmsSendParams = SmsMessageSendRequest;
+/** Body for `bird.sms.sendBatch` — an array of up to 100 sends. */
+type SmsSendBatchParams = SmsMessageBatchRequest;
+/** Result of `bird.sms.sendBatch`. */
+type SmsSendBatchResult = SmsMessageBatchResponse;
+/** Filters and cursor params for `bird.sms.list`. */
+type SmsListQuery = NonNullable<ListSmsMessagesData["query"]>;
+declare class SmsResource extends Resource {
+  /**
+   * Send one SMS to a single recipient. Supply either `text` (with a `category`)
+   * or a stored `template` (by `id` or `name`, with its `parameters`). The
+   * result is `accepted`, not yet delivered — read it back with `get` to confirm.
+   *
+   * @example Send free text
+   * const msg = await bird.sms.send({
+   *   to: "+15551234567",
+   *   text: "Your verification code is 123456.",
+   *   category: "authentication",
+   * });
+   * console.log(msg.id, msg.status);
+   *
+   * @example Send by template
+   * await bird.sms.send({
+   *   to: "+15551234567",
+   *   template: { name: "bird_otp_verification", parameters: { code: "123456" } },
+   * });
+   */
+  send(params: SmsSendParams, options?: RequestOptions): APIPromise<SmsMessage>;
+  /**
+   * Send up to 100 independent SMS messages in one call. Each item is a full send
+   * (free text or template); all items are validated before any are queued.
+   *
+   * @example
+   * const result = await bird.sms.sendBatch([
+   *   { to: "+15551111111", text: "Hi Alice!", category: "marketing" },
+   *   { to: "+15552222222", text: "Hi Bob!", category: "marketing" },
+   * ]);
+   */
+  sendBatch(params: SmsSendBatchParams, options?: RequestOptions): APIPromise<SmsSendBatchResult>;
+  /**
+   * Fetch a single SMS message: its current delivery status, segment breakdown,
+   * cost, and failure detail if it failed.
+   *
+   * @example
+   * const msg = await bird.sms.get("sms_abc123");
+   * msg.status; // "accepted" | "delivered" | …
+   */
+  get(messageId: string, options?: RequestOptions): APIPromise<SmsMessage>;
+  /**
+   * List SMS messages, newest first. `await` resolves the first page; `for await`
+   * walks every message across all pages. Filter by direction, status, category,
+   * recipient, sender, or tag.
+   *
+   * @example
+   * for await (const msg of bird.sms.list({ direction: "outbound" })) {
+   *   console.log(msg.id, msg.status);
+   * }
+   */
+  list(query?: SmsListQuery, options?: RequestOptions): PaginatedPromise<SmsMessage>;
+}
+//#endregion
+//#region src/resources/smsTemplates.d.ts
+/** Filters for `bird.smsTemplates.list`. */
+type SmsTemplateListQuery = NonNullable<ListSmsTemplatesData["query"]>;
+declare class SmsTemplatesResource extends Resource {
+  /**
+   * List the SMS templates available to the workspace — Bird's built-in
+   * templates plus any the workspace authored. The catalogue is small and
+   * returned in full (`.data`); this list is not paginated. Filter by `scope`,
+   * `category`, or `language` (a BCP-47 language tag).
+   *
+   * @example List the built-in templates
+   * const { data } = await bird.smsTemplates.list({ scope: "system" });
+   * for (const tpl of data) console.log(tpl.id, tpl.name);
+   */
+  list(query?: SmsTemplateListQuery, options?: RequestOptions): APIPromise<SmsTemplateList>;
+  /**
+   * Fetch a single SMS template by its name or id, including its body and the
+   * variables it expects.
+   *
+   * @example
+   * const tpl = await bird.smsTemplates.get("bird_otp_verification");
+   * console.log(tpl.body, tpl.variables);
+   */
+  get(templateRef: string, options?: RequestOptions): APIPromise<SmsTemplate>;
+}
+//#endregion
+//#region src/resources/webhooks.d.ts
+/** A verified webhook event — discriminated on `type` (ADR-0028 wire contract). */
+type BirdWebhookEvent = WebhookEvent;
+/** Inbound request headers, as a `Headers` object or a plain record. */
+type WebhookHeaders = Headers | Record<string, string>;
+/** Client-level webhooks config (`new BirdClient({ webhooks: { secret } })`). */
+interface WebhookOptions {
+  /** Signing secret used by `unwrap`; a per-call `secret` overrides it. */
+  secret?: string;
+}
+declare class WebhooksResource {
+  #private;
+  constructor(config?: WebhookOptions);
+  /**
+   * Verify a webhook delivery and return the typed event.
+   *
+   * **Pass the raw request body**, exactly as received — do NOT parse it first.
+   * The Standard Webhooks signature is computed over the raw bytes, so parsing
+   * and re-serializing before verifying is the classic webhook bug.
+   *
+   * The secret comes from `webhooks.secret` on the client; pass `{ secret }` to
+   * override per call. Throws {@link BirdWebhookVerificationError} on a bad
+   * signature, a stale timestamp, or missing/malformed headers. Unknown event
+   * types are returned as-is (handle them in a `default` case) so a newer server
+   * event can't break an older SDK.
+   *
+   * @example One call verifies the signature and returns the typed event
+   * // Pass the RAW request body; set the secret via new BirdClient({ webhooks: { secret } }).
+   * const event = bird.webhooks.unwrap(rawBody, headers);
+   * console.log(event.type); // discriminated union — narrow on event.type
+   *
+   * @example Verify and dispatch — pass the raw request body, never the parsed JSON
+   * // new BirdClient({ apiKey, webhooks: { secret } })
+   * try {
+   *   const event = bird.webhooks.unwrap(rawBody, req.headers);
+   *   switch (event.type) {
+   *     case "email.delivered":
+   *       markDelivered(event.email_id, event.recipient); // narrowed; fields are flat
+   *       break;
+   *     case "email.bounced":
+   *     case "email.complained":
+   *       suppress(event.recipient);
+   *       break;
+   *     default: // unknown future event types — an older SDK won't break on a new one
+   *   }
+   * } catch (err) {
+   *   if (err instanceof BirdWebhookVerificationError) {
+   *     // reject with 400 — bad signature, stale timestamp, or missing/malformed headers
+   *   } else throw err;
+   * }
+   */
+  unwrap(payload: string, headers: WebhookHeaders, options?: WebhookOptions): BirdWebhookEvent;
+}
+//#endregion
+//#region src/client.d.ts
+interface BirdClientOptions {
+  apiKey: string;
+  /** Explicit base URL; overrides region resolution. For local/self-hosted use. */
+  baseUrl?: string;
+  /** Region override (e.g. `"eu1"`); the API key prefix is used by default. */
+  region?: string;
+  /** Per-attempt timeout in ms. Default 60_000. */
+  timeout?: number;
+  /** Max retry attempts on retryable failures (429, 5xx, network). Default 2. */
+  maxRetries?: number;
+  /** Custom fetch — testing, proxying, edge-runtime adapters. Default global fetch. */
+  fetch?: typeof fetch;
+  /** Headers added to every request. SDK-internal headers win on conflict. */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Email channel defaults. Any field set here may be omitted in
+   * `bird.email.send` (the type enforces this); the per-send value wins.
+   */
+  email?: EmailChannelDefaults;
+  /** Webhooks config — `secret` is the default used by `bird.webhooks.unwrap`. */
+  webhooks?: WebhookOptions;
+}
+/** A raw request for the `bird.request` escape hatch. */
+interface BirdRequest {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /**
+   * Absolute path on the API host, e.g. `/v1/email/domains`; must start
+   * with a single `/`.
+   */
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  /** JSON request body. */
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+type EmailDefaultsOf<O> = O extends {
+  email: infer E extends EmailChannelDefaults;
+} ? E : undefined;
+/**
+ * The Bird API client. Construct it with an API key; the region is taken from
+ * the key's prefix (`bk_{region}_…`) — pass `baseUrl` or `region` to override.
+ *
+ * @example Construct and send
+ * const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
+ * const msg = await bird.email.send({
+ *   from: "hello@acme.com",
+ *   to: ["customer@example.com"],
+ *   subject: "Welcome aboard",
+ *   html: "<h1>Hi there 👋</h1>",
+ * });
+ * console.log(msg.id);
+ *
+ * @example Channel defaults — set common send fields once; a per-send value always wins
+ * const bird = new BirdClient({
+ *   apiKey: process.env.BIRD_API_KEY!,
+ *   email: { from: "hello@acme.com", category: "transactional" },
+ * });
+ * // `from` and `category` are filled from the defaults; both stay optional in `send`.
+ * await bird.email.send({ to: ["customer@example.com"], subject: "Hi", html: "<p>hi</p>" });
+ *
+ * @example All client options
+ * const bird = new BirdClient({
+ *   apiKey: process.env.BIRD_API_KEY!,
+ *   region: "eu1", // optional — override the region from the key prefix
+ *   baseUrl: "http://localhost:8080", // optional — overrides region entirely (local/self-hosted)
+ *   timeout: 60_000, // per-attempt timeout in ms (default 60_000)
+ *   maxRetries: 2, // retry budget for transient failures (default 2)
+ * });
+ */
+declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions> {
+  #private;
+  protected readonly core: BirdHTTPClient;
+  /** The email channel — `bird.email.send(...)`, `.get(...)`, `.list(...)`. */
+  readonly email: EmailResource<EmailDefaultsOf<O>>;
+  /** Email templates — `bird.emailTemplates.create(...)`, `.list(...)`, `.publish(...)`, … */
+  readonly emailTemplates: EmailTemplatesResource;
+  /** The SMS channel — `bird.sms.send(...)`, `.get(...)`, `.list(...)`. */
+  readonly sms: SmsResource;
+  /** SMS templates — `bird.smsTemplates.list(...)`, `.get(...)`. */
+  readonly smsTemplates: SmsTemplatesResource;
+  /** Contacts — `bird.contacts.create(...)`, `.list(...)`, `.get(...)`, `.batch(...)`, … */
+  readonly contacts: ContactsResource;
+  /** Audiences — `bird.audiences.create(...)`, `.list(...)`, `.addContacts(...)`, … */
+  readonly audiences: AudiencesResource;
+  /** Contact properties — `bird.contactProperties.create(...)`, `.list(...)`, `.archive(...)`, … */
+  readonly contactProperties: ContactPropertiesResource;
+  /** Webhooks — `bird.webhooks.unwrap(payload, headers)` verifies an inbound delivery. */
+  readonly webhooks: WebhooksResource;
+  constructor(options: O);
+  /**
+   * Escape hatch for endpoints the typed resources don't cover. Runs the full
+   * lifecycle (auth, retries, idempotency, error mapping); you supply the
+   * response type. Prefer a typed resource method where one exists.
+   *
+   * @throws {TypeError} if `req.path` does not start with exactly one `/` or
+   *   resolves to a different origin than the configured Bird API base URL.
+   *
+   * @example Reach an endpoint outside the curated surface — you supply the response type
+   * type Suppressions = { data: Array<{ recipient: string }> };
+   * const suppressions = await bird.request<Suppressions>({ method: "GET", path: "/v1/email/suppressions" });
+   * console.log(suppressions.data.length);
+   */
+  request<T = unknown>(req: BirdRequest, options?: RequestOptions): APIPromise<T>;
+}
+//#endregion
+//#region src/region.d.ts
+/** Extracts the region code from a `bk_{region}_{token}` key, or undefined. */
+declare function regionFromApiKey(apiKey: string): string | undefined;
+declare function baseUrlForRegion(region: string): string;
+//#endregion
+//#region src/event-types.gen.d.ts
+/**
+ * Webhook event types known at this SDK version. The wire value is an open
+ * string: a value added by a newer server is returned by `unwrap` unchanged,
+ * so switch on these with a `default` branch.
+ */
+declare const WebhookEventType: {
+  readonly DomainFailed: "domain.failed";
+  readonly DomainVerified: "domain.verified";
+  readonly EmailAccepted: "email.accepted";
+  readonly EmailBounced: "email.bounced";
+  readonly EmailCanceled: "email.canceled";
+  readonly EmailClicked: "email.clicked";
+  readonly EmailComplained: "email.complained";
+  readonly EmailDeferred: "email.deferred";
+  readonly EmailDelivered: "email.delivered";
+  readonly EmailListUnsubscribed: "email.list_unsubscribed";
+  readonly EmailMailboxMessageDelivered: "email_mailbox.message_delivered";
+  readonly EmailMailboxMessageFailed: "email_mailbox.message_failed";
+  readonly EmailMailboxMessageReceived: "email_mailbox.message_received";
+  readonly EmailMailboxMessageReceivedBlocked: "email_mailbox.message_received_blocked";
+  readonly EmailMailboxMessageReceivedUnauthenticated: "email_mailbox.message_received_unauthenticated";
+  readonly EmailMailboxMessageSent: "email_mailbox.message_sent";
+  readonly EmailMailboxSuspended: "email_mailbox.suspended";
+  readonly EmailMailboxThreadCreated: "email_mailbox.thread_created";
+  readonly EmailOpened: "email.opened";
+  readonly EmailOutOfBandBounce: "email.out_of_band_bounce";
+  readonly EmailProcessed: "email.processed";
+  readonly EmailReceived: "email.received";
+  readonly EmailRejected: "email.rejected";
+  readonly EmailScheduled: "email.scheduled";
+  readonly EmailSuppressionCreated: "email_suppression.created";
+  readonly EmailUnsubscribed: "email.unsubscribed";
+  readonly SmsAccepted: "sms.accepted";
+  readonly SmsDelivered: "sms.delivered";
+  readonly SmsExpired: "sms.expired";
+  readonly SmsFailed: "sms.failed";
+  readonly SmsRejected: "sms.rejected";
+  readonly SmsSent: "sms.sent";
+  readonly SmsUndelivered: "sms.undelivered";
+};
+/** A known webhook event type value. */
+type WebhookEventTypeValue = (typeof WebhookEventType)[keyof typeof WebhookEventType];
+//#endregion
+export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceContactsQuery, type AudienceCreateParams, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type EmailTemplate, type EmailTemplateCreateParams, type EmailTemplateListQuery, type EmailTemplateSummary, type EmailTemplateUpdateParams, type EmailTemplateVersion, type ErrorDetail, type ErrorNextAction, type PaginatedPromise, type RequestOptions, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, baseUrlForRegion, regionFromApiKey };
+//# sourceMappingURL=index.d.mts.map