@messagebird/sdk 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -78,6 +78,15 @@ interface ErrorDetail {
     /** 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;
@@ -96,6 +105,10 @@ interface BirdAPIErrorFields {
     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 {
@@ -107,6 +120,8 @@ declare class BirdAPIError extends BirdError {
     readonly requestId: string;
     readonly param?: string;
     readonly vendorCode?: string;
+    readonly remediation?: string;
+    readonly next?: ErrorNextAction[];
     constructor(fields: BirdAPIErrorFields);
 }
 /** 401 — authentication failed or missing. */
@@ -269,11 +284,11 @@ type SmsError = {
     occurred_at: string;
 } | null;
 /**
- * Structured key/value tag attached to an SMS message. Surfaces in list filters, the event log, and webhook payloads. Use tags for low-cardinality filtering dimensions (category, experiment 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 SMSMessageSendRequest for the array maximum.
+ * 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 SmsTag = {
+type Tag = {
     /**
      * Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
      *
@@ -311,7 +326,7 @@ type EventSmsBase = {
      * 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<SmsTag> | null;
+    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.
      *
@@ -493,23 +508,6 @@ type EventEmailSuppressionCreated = {
  * Payload of the email.unsubscribed event.
  */
 type EventEmailUnsubscribedData = EventEmailBase;
-/**
- * Structured key/value tag attached to an email send. 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 EmailMessageSendRequest for the array maximum.
- *
- */
-type EmailTag = {
-    /**
-     * 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;
-};
 /**
  * Envelope position of a recipient on an outbound email event.
  */
@@ -544,7 +542,7 @@ type EventEmailBase = {
      * 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<EmailTag> | null;
+    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.
      *
@@ -567,12 +565,60 @@ type EventEmailUnsubscribed = {
     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.
+ * `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";
+type EmailRejectionReason = "recipient_suppressed" | "transmission_failed" | "generation_failure" | "policy_rejection" | "domain_unverified" | "quota_exceeded" | "recipient_not_allowed";
 /**
  * Payload of the email.rejected event.
  */
@@ -867,6 +913,24 @@ type EventEmailClicked = {
     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.
  */
@@ -975,6 +1039,8 @@ type WebhookEvent = ({
 } & EventEmailAccepted) | ({
     type: "email.bounced";
 } & EventEmailBounced) | ({
+    type: "email.canceled";
+} & EventEmailCanceled) | ({
     type: "email.clicked";
 } & EventEmailClicked) | ({
     type: "email.complained";
@@ -995,6 +1061,8 @@ type WebhookEvent = ({
 } & EventEmailReceived) | ({
     type: "email.rejected";
 } & EventEmailRejected) | ({
+    type: "email.scheduled";
+} & EventEmailScheduled) | ({
     type: "email.unsubscribed";
 } & EventEmailUnsubscribed) | ({
     type: "email_suppression.created";
@@ -1013,271 +1081,905 @@ type WebhookEvent = ({
 } & EventSmsSent) | ({
     type: "sms.undelivered";
 } & EventSmsUndelivered);
-type EmailMessageBatchResponse = {
-    /**
-     * One entry per message in the batch, in submission order.
-     */
-    data: Array<EmailMessageBatchItem>;
-};
-type EmailMessageBatchItem = {
+/**
+ * An email address with an optional display name.
+ */
+type EmailAddress = {
     /**
-     * Message ID assigned to this batch item.
+     * Email address.
      */
-    readonly id: EmailId;
+    email: string;
     /**
-     * Initial status of this message in the batch.
+     * Display name shown alongside the address in mail clients.
      */
-    readonly status: "accepted";
+    name?: string;
+};
+type EmailTemplateVersionList = {
     /**
-     * Resolved category for this batch item.
+     * All versions of the template, newest first.
      */
-    category: "marketing" | "transactional";
+    data: Array<EmailTemplateVersion>;
 };
 /**
- * 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>;
-/**
- * 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.
+ * 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 EmailAttachment = {
+type TemplateVariable = {
     /**
-     * Filename shown to the recipient. Required.
+     * The parameters key this slot is filled with.
      */
-    filename: string;
+    readonly key: string;
     /**
-     * Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
+     * 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`.
      *
      */
-    content: string;
+    readonly type: 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.
+     * Whether the slot must be supplied when sending. Advisory for email templates, where a missing value renders as empty rather than rejecting the send.
      *
      */
-    path?: string;
+    readonly required: boolean;
     /**
-     * MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
-     *
+     * A human-readable description of the accepted values.
      */
-    content_type?: string;
+    readonly constraint: string;
+};
+type EmailTemplateId = string;
+type EmailTemplateVersionId = string;
+type EmailTemplateVersion = {
     /**
-     * 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.
-     *
+     * Template version ID.
      */
-    content_id?: string;
-};
-/**
- * An email address with an optional display name.
- */
-type EmailAddress = {
+    readonly id: EmailTemplateVersionId;
     /**
-     * Email address.
+     * The template this version belongs to.
      */
-    email: string;
+    readonly template_id: EmailTemplateId;
     /**
-     * Display name shown alongside the address in mail clients.
+     * Sequential published-version number (1, 2, 3…). Null while the version is a draft.
      */
-    name?: string;
+    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;
 };
 /**
- * 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.
+ * 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 EmailAddressInput = string | EmailAddress;
-type EmailMessageSendRequest = {
+type EmailTemplateUpdate = {
     /**
-     * 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.
+     * The draft revision you last read (from the template's `revision` field). A stale value returns a conflict so you can reload and retry.
+     *
      */
-    from: EmailAddressInput;
+    revision: number;
     /**
-     * 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.
+     * New template name. Must stay unique within the workspace.
      */
-    to: Array<EmailAddressInput>;
+    name?: string;
     /**
-     * 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.
+     * New workspace-unique slug handle for send-by-template. Send null to clear it. Lowercase letters, numbers, and hyphens.
+     *
      */
-    cc?: Array<EmailAddressInput>;
+    alias?: string | null;
     /**
-     * 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.
+     * New description of the template's purpose. Send null to clear it.
      */
-    bcc?: Array<EmailAddressInput>;
+    description?: string | null;
     /**
-     * Message subject line.
+     * New email subject line for the draft. Send null to clear it.
      */
-    subject: string;
+    subject?: string | null;
     /**
-     * HTML body. At least one of html or text must be provided.
+     * New HTML body — the source markup for the template's format.
      */
     html?: string;
     /**
-     * Plain-text body. At least one of html or text must be provided.
+     * New plain-text body for the draft. Send null to clear it.
      */
-    text?: string;
+    text?: string | null;
     /**
-     * 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.
-     *
+     * Brand kit to apply to the draft.
      */
-    reply_to?: Array<EmailAddressInput>;
+    brand_kit_id?: BrandKitId;
+};
+type BrandKitId = string;
+type EmailTemplate = {
     /**
-     * Custom email headers as key-value pairs.
+     * Template ID.
      */
-    headers?: {
-        [key: string]: string;
-    };
+    readonly id: EmailTemplateId;
     /**
-     * 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.
-     *
+     * Workspace that owns the template.
      */
-    tags?: Array<EmailTag>;
+    readonly workspace_id: WorkspaceId;
     /**
-     * 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.
-     *
+     * Human-readable template name, unique within the workspace.
      */
-    metadata?: {
-        [key: string]: unknown;
-    };
+    name: string;
     /**
-     * Whether to track open events for this message.
+     * The template's workspace-unique slug handle for send-by-template, or null if unset.
      */
-    track_opens?: boolean;
+    alias?: string | null;
     /**
-     * Whether to track click events for this message.
+     * Optional description of the template's purpose. Null when unset.
      */
-    track_clicks?: boolean;
+    description?: string | null;
+    scope: TemplateScope;
+    category: EmailTemplateCategory;
+    source: EmailTemplateSource;
     /**
-     * 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`.
-     *
+     * The variable slots this template's current draft fills in from the values you supply when sending.
      */
-    ip_pool_id?: string;
+    readonly variables: Array<TemplateVariable>;
     /**
-     * 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: transactional.
-     *
+     * The current editable draft version.
      */
-    category?: "marketing" | "transactional";
+    readonly draft_version_id: EmailTemplateVersionId;
     /**
-     * Preview feature — threaded replies. Currently unavailable; supplying this field returns `422 unsupported_feature`. When generally available, sets In-Reply-To and References headers automatically.
+     * The currently published version, or null if the template has never been published.
      */
-    in_reply_to_message_id?: EmailId;
+    readonly published_version_id?: EmailTemplateVersionId | null;
     /**
-     * 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.
-     *
+     * The draft's revision counter. Send it back on the next update to detect concurrent edits.
      */
-    attachments?: Array<EmailAttachment>;
+    readonly revision: number;
     /**
-     * Preview feature — send-later scheduling. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+     * The draft's email subject line. Null when unset.
      */
-    scheduled_at?: string;
+    subject?: string | null;
     /**
-     * Preview feature — contact-targeted sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+     * The draft's HTML body. Null when unset.
      */
-    contact_id?: string;
+    html?: string | null;
     /**
-     * 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`.
-     *
+     * The draft's plain-text body. Null when unset.
      */
-    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 = {
+    text?: string | null;
     /**
-     * Attachment ID, stable per email send.
+     * The brand kit applied to the draft, or null if none.
      */
-    readonly id?: EmailAttachmentId;
+    readonly brand_kit_id?: BrandKitId | null;
     /**
-     * Filename as shown to the recipient.
+     * When the template was created.
      */
-    filename: string;
+    readonly created_at: string;
     /**
-     * Resolved MIME type at send time.
+     * When the template was last modified.
      */
-    content_type?: string;
+    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 = {
     /**
-     * Decoded size in bytes.
+     * Human-readable template name, unique within the workspace.
      */
-    size: number;
+    name: string;
     /**
-     * True when the attachment was sent inline via a `content_id` reference in the HTML body, false for regular file attachments.
+     * Optional workspace-unique slug handle for the template — a stable alternative to the template ID when sending by template. Lowercase letters, numbers, and hyphens.
      *
      */
-    inline?: boolean;
+    alias?: string;
     /**
-     * The Content-ID set at send time, when the attachment was inline.
+     * Optional description of the template's purpose.
      */
-    content_id?: string | null;
-};
-type EmailMessage = {
+    description?: string;
+    category: EmailTemplateCategory;
     /**
-     * Message ID.
+     * 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.
+     *
      */
-    readonly id: EmailId;
+    source: EmailTemplateSource;
     /**
-     * Sender address. `name` is present when a display name was provided on the send.
+     * The email subject line for the initial draft.
      */
-    from: EmailAddress;
+    subject?: string;
     /**
-     * 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.
+     * The HTML body — the source markup for the chosen format.
      */
-    to: Array<EmailAddress>;
+    html?: string;
     /**
-     * CC recipients.
+     * The optional plain-text body.
      */
-    cc?: Array<EmailAddress>;
+    text?: string;
     /**
-     * BCC recipients.
+     * Optional brand kit to apply to the draft.
      */
-    bcc?: Array<EmailAddress>;
+    brand_kit_id?: BrandKitId;
+};
+type EmailTemplateSummary = {
     /**
-     * Message subject line.
+     * Template ID.
      */
-    subject: string;
+    readonly id: EmailTemplateId;
     /**
-     * Content classification. Controls suppression policy — `marketing` blocks on all suppression reasons; `transactional` allows delivery through complaint and unsubscribe suppressions.
-     *
+     * Workspace that owns the template.
      */
-    category: "marketing" | "transactional";
+    readonly workspace_id: WorkspaceId;
     /**
-     * Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
+     * Human-readable template name, unique within the workspace.
      */
-    reply_to?: Array<EmailAddress> | null;
+    name: string;
     /**
-     * Aggregate delivery status derived from recipient states. `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.
-     *
+     * The template's workspace-unique slug handle for send-by-template, or null if unset.
      */
-    readonly status: "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected";
+    alias?: string | null;
     /**
-     * Number of recipients currently in the `accepted` state — Bird has the send and is preparing to deliver.
+     * Optional description of the template's purpose. Null when unset.
      */
-    readonly accepted_count: number;
+    description?: string | null;
+    scope: TemplateScope;
+    category: EmailTemplateCategory;
+    source: EmailTemplateSource;
     /**
-     * Number of recipients for whom Bird has processed the message and queued it for delivery.
+     * The current editable draft version.
      */
-    readonly processed_count: number;
+    readonly draft_version_id: EmailTemplateVersionId;
     /**
-     * Number of recipients whose messages were accepted by the remote MTA.
+     * The currently published version, or null if never published.
      */
-    readonly delivered_count: number;
+    readonly published_version_id?: EmailTemplateVersionId | null;
     /**
-     * Number of recipients that resulted in a permanent delivery failure.
+     * When the template was created.
      */
-    readonly bounced_count: number;
+    readonly created_at: string;
     /**
-     * Number of recipients that reported spam.
+     * When the template was last modified.
      */
-    readonly complained_count: number;
+    readonly updated_at: string;
+};
+type SmsTemplateList = {
     /**
-     * Number of recipients in transient delivery deferral; the provider is retrying.
+     * The templates available to your workspace. The catalogue is small and returned in full — this list is not paginated.
      */
-    readonly deferred_count: number;
+    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;
+    /**
+     * Human-readable description of what the template is for.
+     */
+    readonly name: string;
+    /**
+     * The template's stable handle. Pass it (or the id) as the template reference when sending.
+     */
+    readonly alias: 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_locales: 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 alias handle (for example `bird_otp_verification`). Browse the available templates and their variables with the templates endpoint.
+     *
+     */
+    alias?: 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.
+     *
+     */
+    locale?: 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 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>;
+/**
+ * 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;
+};
+type EmailTemplateSend = unknown & {
+    /**
+     * The template to send, by its id.
+     */
+    id?: EmailTemplateId;
+    /**
+     * The template to send, by its alias handle (for example `welcome-email`).
+     */
+    alias?: 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;
+    };
+};
+/**
+ * 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 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.
+     */
+    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: transactional.
+     *
+     */
+    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;
+};
+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: "scheduled" | "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected" | "canceled";
+    /**
+     * 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).
      *
@@ -1309,7 +2011,7 @@ type EmailMessage = {
     /**
      * Structured `{name, value}` filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.
      */
-    tags?: Array<EmailTag>;
+    tags?: Array<Tag>;
     /**
      * Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.
      */
@@ -1344,6 +2046,10 @@ type EmailMessage = {
      * 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;
@@ -1372,12 +2078,12 @@ type ListEmailMessagesData = {
         /**
          * Filter by aggregate delivery status.
          */
-        status?: "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected";
+        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`). For filtering on arbitrary `metadata` fields, use the metadata path-filter parameters instead.
+         * 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?: string;
+        tag?: Array<string>;
         /**
          * Filter by category.
          */
@@ -1395,6 +2101,114 @@ type ListEmailMessagesData = {
     };
     url: "/v1/email/messages";
 };
+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.
+         */
+        locale?: string;
+    };
+    url: "/v1/sms/templates";
+};
+type ListEmailTemplatesData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Filter by template category.
+         */
+        category?: EmailTemplateCategory;
+        /**
+         * Filter by authoring format.
+         */
+        source?: EmailTemplateSource;
+        /**
+         * Filter by name prefix (case-insensitive).
+         */
+        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";
+};
 
 type AuthToken = string | undefined;
 interface Auth {
@@ -1689,7 +2503,7 @@ interface ClientOptions {
     throwOnError?: boolean;
 }
 type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<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<never, TResponseStyle, ThrowOnError>, "method">) => Promise<ServerSentEventsResult<TData, TError>>;
+type SseFn = <TData = unknown, _TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, "method">) => Promise<ServerSentEventsResult<TData>>;
 type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, "method"> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, "method">) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 type BuildUrlFn = <TData extends {
     body?: unknown;
@@ -1858,6 +2672,194 @@ declare class EmailResource<D extends EmailChannelDefaults | undefined = undefin
     list(query?: EmailListQuery, options?: RequestOptions$1): PaginatedPromise<EmailMessage>;
 }
 
+/** 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",
+     *   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$1): 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$1): 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$1): 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$1): 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$1): 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$1): 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$1): 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$1): APIPromise<EmailTemplateVersion>;
+}
+
+/** 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 `alias`, 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: { alias: "bird_otp_verification", parameters: { code: "123456" } },
+     * });
+     */
+    send(params: SmsSendParams, options?: RequestOptions$1): 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$1): 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$1): 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$1): PaginatedPromise<SmsMessage>;
+}
+
+/** 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 `locale` (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$1): APIPromise<SmsTemplateList>;
+    /**
+     * Fetch a single SMS template by its alias 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$1): APIPromise<SmsTemplate>;
+}
+
 /** 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. */
@@ -1985,6 +2987,12 @@ declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions>
     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;
     /** Webhooks — `bird.webhooks.unwrap(payload, headers)` verifies an inbound delivery. */
     readonly webhooks: WebhooksResource;
     constructor(options: O);
@@ -2018,6 +3026,7 @@ declare const WebhookEventType: {
     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";
@@ -2028,6 +3037,7 @@ declare const WebhookEventType: {
     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";
@@ -2041,4 +3051,4 @@ declare const WebhookEventType: {
 /** A known webhook event type value. */
 type WebhookEventTypeValue = (typeof WebhookEventType)[keyof typeof WebhookEventType];
 
-export { type APIPromise, 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 CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type ErrorDetail, type PaginatedPromise, type RequestOptions$1 as RequestOptions, type SafeResult, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, baseUrlForRegion, regionFromApiKey };
+export { type APIPromise, 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 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$1 as 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 };