unitpost 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- declare const SDK_VERSION = "0.3.0";
1
+ declare const SDK_VERSION = "0.4.0";
2
2
  interface ApiFieldError {
3
3
  /** Dotted path to the offending field, e.g. "template.variables.first_name". */
4
4
  field: string;
@@ -129,9 +129,10 @@ type ApiKey = {
129
129
  type ApiKeyCreate = {
130
130
  name: string;
131
131
  scope?: "full" | "sending" | "read_only";
132
- capabilities?: Array<"contacts:read" | "contacts:write" | "suppressions:read" | "suppressions:write" | "segments:read" | "segments:write" | "topics:read" | "topics:write" | "templates:read" | "templates:write" | "components:read" | "components:write" | "campaigns:read" | "campaigns:write" | "campaigns:send" | "domains:read" | "domains:write" | "emails:read" | "emails:send" | "sms:read" | "sms:send" | "sms:manage" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
132
+ capabilities?: Array<"contacts:read" | "contacts:write" | "suppressions:read" | "suppressions:write" | "segments:read" | "segments:write" | "topics:read" | "topics:write" | "templates:read" | "templates:write" | "components:read" | "components:write" | "campaigns:read" | "campaigns:write" | "campaigns:send" | "domains:read" | "domains:write" | "emails:read" | "emails:send" | "sms:read" | "sms:send" | "sms:manage" | "sms:purchase" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
133
133
  };
134
134
  type ApiKeyCreated = ApiKey & {
135
+ /** The plaintext secret. Shown exactly once — store it now; it can never be retrieved again. */
135
136
  key: string;
136
137
  };
137
138
  type Batch = {
@@ -140,49 +141,62 @@ type Batch = {
140
141
  count: number;
141
142
  scheduled_at: string | null;
142
143
  created_at: string;
144
+ /** Live child counts keyed by status (e.g. { delivered: 98, failed: 2 }). */
143
145
  status_counts: Record<string, number>;
144
146
  cancelable: number;
145
147
  };
146
148
  type BatchSend = Array<{
149
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
147
150
  from: string;
148
151
  to: string | Array<string>;
149
152
  subject?: string;
150
153
  cc?: string | Array<string>;
151
154
  bcc?: string | Array<string>;
152
155
  reply_to?: string | Array<string>;
156
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
153
157
  in_reply_to?: string;
158
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
154
159
  headers?: Record<string, string>;
155
160
  tags?: Array<{
156
161
  name: string;
157
162
  value: string;
158
163
  }>;
164
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
159
165
  template?: {
160
166
  id: string;
161
167
  variables?: Record<string, string | number>;
162
168
  };
169
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
163
170
  html?: string;
171
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
164
172
  text?: string;
165
173
  open_tracking?: boolean;
166
174
  click_tracking?: boolean;
167
175
  }> | {
168
176
  emails: Array<{
177
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
169
178
  from: string;
170
179
  to: string | Array<string>;
171
180
  subject?: string;
172
181
  cc?: string | Array<string>;
173
182
  bcc?: string | Array<string>;
174
183
  reply_to?: string | Array<string>;
184
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
175
185
  in_reply_to?: string;
186
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
176
187
  headers?: Record<string, string>;
177
188
  tags?: Array<{
178
189
  name: string;
179
190
  value: string;
180
191
  }>;
192
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
181
193
  template?: {
182
194
  id: string;
183
195
  variables?: Record<string, string | number>;
184
196
  };
197
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
185
198
  html?: string;
199
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
186
200
  text?: string;
187
201
  open_tracking?: boolean;
188
202
  click_tracking?: boolean;
@@ -191,6 +205,7 @@ type BatchSend = Array<{
191
205
  };
192
206
  type BatchSendResult = {
193
207
  object: "list";
208
+ /** Handle for GET / cancel on /email/batches/{id}. */
194
209
  batch_id: string;
195
210
  status: "queued" | "scheduled";
196
211
  scheduled_at: string | null;
@@ -284,9 +299,33 @@ type Campaign = {
284
299
  scheduled_at: string | null;
285
300
  variable_fallbacks: Record<string, string>;
286
301
  excluded_contact_ids: Array<string>;
302
+ /** Recipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate. */
287
303
  total_recipients: number;
304
+ /** The audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only. */
305
+ projected_recipients?: {
306
+ total: number;
307
+ reachable: number;
308
+ skipped: number;
309
+ } | null;
288
310
  sent_count: number;
289
311
  failed_count: number;
312
+ pause_reason: {
313
+ code: "user" | "hard_bounce_rate" | "complaint_rate" | "quality_review" | "provider_limit" | "failure_streak" | "sender_unavailable" | "template_unavailable" | "billing" | "not_drained" | "sending_restricted" | "workspace_suspended";
314
+ message: string | null;
315
+ metric: "hard_bounce_rate" | "complaint_rate" | null;
316
+ value: number | null;
317
+ threshold: number | null;
318
+ sample: {
319
+ events: number;
320
+ of: number;
321
+ } | null;
322
+ window: {
323
+ since: string | null;
324
+ } | null;
325
+ decided_by: "floor" | "unit" | null;
326
+ resume: "self_serve" | "review_required" | "account_review" | "resume_slowly" | null;
327
+ paused_at: string | null;
328
+ } | null;
290
329
  created_at: string;
291
330
  updated_at: string;
292
331
  };
@@ -299,6 +338,7 @@ type CampaignCreate = {
299
338
  from: string;
300
339
  subject?: string;
301
340
  preview_text?: string;
341
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`. */
302
342
  scheduled_at?: string;
303
343
  open_tracking?: boolean | null;
304
344
  click_tracking?: boolean | null;
@@ -306,8 +346,12 @@ type CampaignCreate = {
306
346
  excluded_contact_ids?: Array<string>;
307
347
  };
308
348
  type CampaignReschedule = {
349
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; returned in UTC. A time without a timezone is read as UTC (deprecated: include the zone). */
309
350
  scheduled_at: string;
310
351
  };
352
+ type CampaignSend = {
353
+ scheduled_at?: string | null;
354
+ };
311
355
  type CampaignUpdate = {
312
356
  archived?: boolean;
313
357
  topic_id?: string | null;
@@ -315,6 +359,7 @@ type CampaignUpdate = {
315
359
  click_tracking?: boolean | null;
316
360
  variable_fallbacks?: Record<string, string>;
317
361
  excluded_contact_ids?: Array<string>;
362
+ scheduled_at?: string | null;
318
363
  };
319
364
  type Contact = {
320
365
  object: "contact";
@@ -342,6 +387,7 @@ type ContactField = {
342
387
  key: string;
343
388
  label: string;
344
389
  type: "text" | "number" | "boolean" | "date";
390
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
345
391
  default_value: string | null;
346
392
  position: number;
347
393
  created_at: string;
@@ -351,6 +397,7 @@ type ContactFieldCreate = {
351
397
  key: string;
352
398
  label: string;
353
399
  type?: "text" | "number" | "boolean" | "date";
400
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
354
401
  default_value?: string | null;
355
402
  };
356
403
  type ContactFieldRename = {
@@ -360,12 +407,13 @@ type ContactFieldUpdate = {
360
407
  label?: string;
361
408
  type?: "text" | "number" | "boolean" | "date";
362
409
  position?: number;
410
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
363
411
  default_value?: string | null;
364
412
  };
365
413
  type ContactImport = {
366
414
  object: "contact_import";
367
415
  id: string;
368
- status: "pending" | "processing" | "completed" | "failed";
416
+ status: "pending" | "processing" | "completed" | "failed" | "canceled";
369
417
  total: number;
370
418
  imported: number;
371
419
  skipped: number;
@@ -384,11 +432,15 @@ type ContactImportCreate = {
384
432
  first_name?: string;
385
433
  last_name?: string;
386
434
  custom_fields?: Record<string, string | number | boolean | null>;
435
+ /** Create this contact already unsubscribed (`true`, or a string `true`/`1`/`yes`/`y`). One-way: it never clears an opt-out, and an existing contact is skipped entirely. */
436
+ unsubscribed?: boolean | string;
387
437
  }>;
388
438
  };
389
439
  type ContactTopic = {
390
440
  object: "contact_topic";
391
441
  topic_id: string;
442
+ /** The topic's channel: manage it under `/email/topics` or `/sms/topics`. */
443
+ channel: "email" | "sms";
392
444
  subscribed: boolean;
393
445
  status: "subscribed" | "unsubscribed";
394
446
  source: "user" | "manual" | "import" | "api";
@@ -420,6 +472,7 @@ type Domain = {
420
472
  click_tracking: boolean | null;
421
473
  tls: "opportunistic" | "enforced";
422
474
  tracking_subdomain: string | null;
475
+ /** When tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null. */
423
476
  tracking_verified_at: string | null;
424
477
  verified_at: string | null;
425
478
  created_at: string;
@@ -428,6 +481,42 @@ type Domain = {
428
481
  type DomainCreate = {
429
482
  name: string;
430
483
  };
484
+ type DomainDiagnosis = {
485
+ object: "domain_diagnosis";
486
+ domain_id: string;
487
+ domain: string;
488
+ /** The domain's stored status, next to the live diagnosis. */
489
+ status: string;
490
+ checked_at: string;
491
+ /** The last verify check, which this call does not change. */
492
+ last_checked_at?: string | null;
493
+ /** Whether a verify run now would mark the domain verified. */
494
+ would_verify: boolean;
495
+ /** The zone whose nameservers were asked; null when none was found. */
496
+ zone?: string | null;
497
+ nameservers?: Array<{
498
+ host?: string;
499
+ ips?: Array<string>;
500
+ }>;
501
+ /** The email provider's view of the sending identity. */
502
+ provider?: {
503
+ configured?: boolean;
504
+ identity_exists?: boolean | null;
505
+ dkim_status?: string | null;
506
+ mail_from_status?: string | null;
507
+ error?: string | null;
508
+ };
509
+ /** Every expected record, with each nameserver's answer and a `verdict` (`ok`, `partial`, `wrong`, `missing`, `unknown`). */
510
+ records: Array<Record<string, unknown>>;
511
+ /** What is wrong, most serious first, each with the concrete `fix`. */
512
+ findings: Array<{
513
+ code: string;
514
+ severity: "blocking" | "warning" | "info";
515
+ title: string;
516
+ detail: string;
517
+ fix: string;
518
+ }>;
519
+ };
431
520
  type DomainUpdate = {
432
521
  open_tracking?: boolean | null;
433
522
  click_tracking?: boolean | null;
@@ -458,7 +547,9 @@ type EmailPatch = {
458
547
  scheduled_at?: string;
459
548
  };
460
549
  type EmailStats = {
550
+ /** The rolling window, in days. */
461
551
  windowDays: number;
552
+ /** Non-null when the requested window exceeded the plan's log retention and was clamped to this many days (data past the retention horizon is purged). */
462
553
  clampedToRetentionDays?: number | null;
463
554
  totals: {
464
555
  sent: number;
@@ -469,6 +560,7 @@ type EmailStats = {
469
560
  complained: number;
470
561
  failed: number;
471
562
  };
563
+ /** Percentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered. */
472
564
  rates: {
473
565
  delivery: number;
474
566
  open: number;
@@ -479,17 +571,37 @@ type EmailStats = {
479
571
  };
480
572
  type Error$1 = {
481
573
  error: {
574
+ /** Stable machine-readable error code (branch on this, not the message). */
482
575
  code: string;
576
+ /** Human-readable summary. For validation errors it's path-prefixed (e.g. "template.variables.first_name: …"). */
483
577
  message: string;
578
+ /** Present on errors that carry per-field reasons: validation errors (422), a blocked campaign send (409), and a plan that doesn't include a feature (403 `limit_reached` with one entry whose `code` is `feature_not_in_plan` and whose `field` names the feature, e.g. `smsChannel`). One entry per offending field/blocker. */
484
579
  details?: Array<{
580
+ /** Dotted path to the field, e.g. "template.variables.first_name" (empty for a whole-body problem). */
485
581
  field: string;
582
+ /** Machine-readable reason for this entry, when there is one (e.g. `template_not_published` on `template_id` for a blocked SMS campaign send, or `feature_not_in_plan` on `smsChannel` when the plan has no SMS). Absent on plain validation errors. */
583
+ code?: string;
486
584
  message: string;
487
585
  }>;
488
586
  };
489
587
  };
588
+ type Job = {
589
+ object: "job";
590
+ id: string;
591
+ kind: string;
592
+ status: "QUEUED" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELED";
593
+ total: number | null;
594
+ processed: number;
595
+ failed: number;
596
+ error: string | null;
597
+ created_at: string;
598
+ completed_at: string | null;
599
+ };
490
600
  type ReceivedAttachmentUrl = {
491
601
  object: "received_attachment_url";
602
+ /** A signed, expiring URL to download the attachment bytes. */
492
603
  url: string;
604
+ /** ISO 8601 expiry of the signed URL (~5 minutes out). */
493
605
  expires_at: string;
494
606
  };
495
607
  type ReceivedEmail = {
@@ -548,6 +660,7 @@ type Segment = {
548
660
  name: string;
549
661
  description: string | null;
550
662
  type: "static" | "dynamic";
663
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
551
664
  filter: unknown | null;
552
665
  created_at: string;
553
666
  updated_at: string;
@@ -556,6 +669,7 @@ type SegmentCreate = {
556
669
  name: string;
557
670
  description?: string;
558
671
  type?: "static" | "dynamic";
672
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
559
673
  filter?: unknown;
560
674
  };
561
675
  type SegmentMember = {
@@ -571,26 +685,33 @@ type SegmentMemberAdd = {
571
685
  type SegmentUpdate = {
572
686
  name?: string;
573
687
  description?: string | null;
688
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
574
689
  filter?: unknown;
575
690
  };
576
691
  type SendEmail = {
692
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
577
693
  from: string;
578
694
  to: string | Array<string>;
579
695
  subject?: string;
580
696
  cc?: string | Array<string>;
581
697
  bcc?: string | Array<string>;
582
698
  reply_to?: string | Array<string>;
699
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
583
700
  in_reply_to?: string;
701
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
584
702
  headers?: Record<string, string>;
585
703
  tags?: Array<{
586
704
  name: string;
587
705
  value: string;
588
706
  }>;
707
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
589
708
  template?: {
590
709
  id: string;
591
710
  variables?: Record<string, string | number>;
592
711
  };
712
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
593
713
  html?: string;
714
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
594
715
  text?: string;
595
716
  attachments?: Array<{
596
717
  filename: string;
@@ -601,6 +722,7 @@ type SendEmail = {
601
722
  }>;
602
723
  open_tracking?: boolean;
603
724
  click_tracking?: boolean;
725
+ /** Future send time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC (reads return UTC). Up to 90 days ahead, fewer on some plans. A time in the past or under 30 seconds ahead sends immediately, so check the response `status`. */
604
726
  scheduled_at?: string;
605
727
  };
606
728
  type SendResult = {
@@ -608,7 +730,7 @@ type SendResult = {
608
730
  status: "queued" | "scheduled";
609
731
  scheduled_at: string | null;
610
732
  };
611
- type Sms = {
733
+ type Sms$1 = {
612
734
  object: "sms";
613
735
  id: string;
614
736
  to: string;
@@ -617,17 +739,298 @@ type Sms = {
617
739
  status: "queued" | "scheduled" | "sending" | "sent" | "delivered" | "failed" | "suppressed" | "canceled" | "received";
618
740
  type: "transactional" | "marketing";
619
741
  body: string | null;
742
+ /** Billed units. Outbound: segments. Inbound: 1 when the received text was charged (1¢ in the US and Canada), else 0. */
620
743
  segments: number;
744
+ /** Inbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise. */
745
+ in_reply_to: string | null;
746
+ /** Inbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound. */
747
+ received_at: string | null;
748
+ /** Inbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound. */
749
+ looks_like_opt_out: boolean;
621
750
  country: string | null;
622
751
  scheduled_at: string | null;
752
+ /** Legacy free-text error. Prefer `error.code`. */
623
753
  last_error: string | null;
754
+ /** Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise. */
755
+ error: {
756
+ /** Why a message was skipped before reaching the carrier. `out_of_reach`: no sender covers the recipient's country; `unsupported_country`: no compliance rule for the country yet, or SMS to that country is paused for now (every message, transactional included, until it resumes); `no_phone`: the contact has no SMS handle; `opted_out`: STOP / suppression / unreachable; `no_marketing_consent`: marketing without express consent; `quiet_hours_deferred`: delayed to the recipient's local window; `sender_not_active`: the sender lost approval. */
757
+ code: "out_of_reach" | "unsupported_country" | "no_phone" | "opted_out" | "no_marketing_consent" | "quiet_hours_deferred" | "sender_not_active";
758
+ /** Human-readable sentence for `code`. */
759
+ message: string;
760
+ } | null;
761
+ created_at: string;
762
+ };
763
+ type SmsBrand = {
764
+ object: "sms_brand";
765
+ /** Prefixed brand id, e.g. `sbrand_…`. */
766
+ id: string;
767
+ /** Public-facing brand name. */
768
+ name: string;
769
+ /** Registered legal entity name. */
770
+ legal_name: string;
771
+ /** Brand website URL. */
772
+ website: string | null;
773
+ /** Registrable domain derived from the website. The brand contact email must be on this domain. */
774
+ domain: string | null;
775
+ contact_email: string | null;
776
+ /** `incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier. */
777
+ status: "incomplete" | "ready" | "pending" | "action_required" | "verified" | "rejected" | "archived";
778
+ /** Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing. */
779
+ missing: Array<string>;
780
+ /** True when the 10DLC brand registration is approved. */
781
+ ten_dlc_verified: boolean;
782
+ tax_id_on_file: boolean;
783
+ /** Non-released senders on this brand (phone numbers and Sender ID countries, any status). */
784
+ number_count: number;
785
+ /** False once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask. */
786
+ editable: boolean;
787
+ created_at: string;
788
+ };
789
+ type SmsCampaign = {
790
+ object: "sms_campaign";
791
+ id: string;
792
+ name: string;
793
+ status: "draft" | "scheduled" | "sending" | "paused" | "sent" | "canceled" | "failed";
794
+ type: "marketing" | "transactional";
795
+ template_id: string;
796
+ segment_id: string;
797
+ sender_id: string | null;
798
+ topic_id: string | null;
799
+ routing: "automatic" | "fixed" | "pool";
800
+ scheduled_at: string | null;
801
+ hold: {
802
+ reason: "scheduled" | "quiet_hours";
803
+ until: string | null;
804
+ } | null;
805
+ pause_reason: {
806
+ code: "user" | "budget_exhausted" | "plan_lapsed" | "sender_not_active" | "template_unavailable" | "workspace_suspended" | "sending_restricted" | "risk_throttled" | "sms_brand_blocked" | "subscription_inactive" | "not_drained";
807
+ message: string | null;
808
+ paused_at: string | null;
809
+ } | null;
810
+ projected_recipients: {
811
+ total: number;
812
+ reachable: number;
813
+ skipped: number;
814
+ } | null;
815
+ recipient_count: number;
816
+ variable_fallbacks: Record<string, string>;
817
+ excluded_contact_ids: Array<string>;
818
+ started_at: string | null;
819
+ completed_at: string | null;
820
+ canceled_at: string | null;
821
+ created_at: string;
822
+ updated_at: string;
823
+ };
824
+ type SmsCampaignCreate = {
825
+ name: string;
826
+ template_id: string;
827
+ segment_id: string;
828
+ sender_id?: string | null;
829
+ topic_id?: string | null;
830
+ excluded_contact_ids?: Array<string>;
831
+ variable_fallbacks?: Record<string, string>;
832
+ scheduled_at?: string | null;
833
+ };
834
+ type SmsCampaignReschedule = {
835
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`. */
836
+ scheduled_at: string;
837
+ };
838
+ type SmsCampaignSend = {
839
+ scheduled_at?: string | null;
840
+ };
841
+ type SmsCampaignUpdate = {
842
+ archived?: boolean;
843
+ name?: string;
844
+ template_id?: string;
845
+ segment_id?: string;
846
+ sender_id?: string | null;
847
+ topic_id?: string | null;
848
+ excluded_contact_ids?: Array<string>;
849
+ variable_fallbacks?: Record<string, string>;
850
+ scheduled_at?: string | null;
851
+ };
852
+ type SmsCampaignValidation = {
853
+ object: "sms_campaign_validation";
854
+ campaign_id: string;
855
+ can_send: boolean;
856
+ blockers: Array<{
857
+ code: string;
858
+ message: string;
859
+ }>;
860
+ total: number;
861
+ reachable: number;
862
+ skipped: number;
863
+ no_marketing_consent: number;
864
+ quiet_hours_deferred: number;
865
+ skipped_by_reason: Array<{
866
+ reason: string;
867
+ count: number;
868
+ remedy: string;
869
+ }>;
870
+ routing: "automatic" | "fixed" | "pool";
871
+ earliest_start: {
872
+ at: string;
873
+ reason: "quiet_hours";
874
+ countries: Array<string>;
875
+ } | null;
876
+ use_case_mismatch: boolean;
877
+ unresolved_variables: Array<string>;
878
+ /** Per template variable that some recipients lack, missing-for-all first. `missing_for_all`: no recipient has it, so a `variable_fallbacks` default is REQUIRED to send. Otherwise a default is optional and only fills the `missing_count` blanks (it never replaces a recipient's own value); or exclude those contacts. `has_default`: the campaign already sets one. */
879
+ variable_coverage?: Array<{
880
+ name: string;
881
+ missing_count: number;
882
+ eligible: number;
883
+ missing_for_all: boolean;
884
+ has_default: boolean;
885
+ }>;
886
+ };
887
+ type SmsConsent = {
888
+ object: "sms_consent";
889
+ phone: string | null;
890
+ country?: string | null;
891
+ status: string;
892
+ marketing_eligible?: boolean;
893
+ consented_at?: string | null;
894
+ consent_source?: string | null;
895
+ consent_purpose?: string | null;
896
+ history: Array<{
897
+ id: string;
898
+ action: string;
899
+ source: string | null;
900
+ purpose: string | null;
901
+ occurred_at: string;
902
+ evidence_url: string | null;
903
+ disclosure_version: string | null;
904
+ }>;
905
+ };
906
+ type SmsConsentRecord = {
907
+ action: "opt_in" | "opt_out";
908
+ source: "web_form" | "hosted_form" | "keyword" | "qr" | "verbal" | "paper" | "api_import" | "api";
909
+ purpose?: "marketing" | "transactional";
910
+ phone?: string;
911
+ occurred_at?: string;
912
+ evidence_url?: string;
913
+ disclosure_version?: string;
914
+ };
915
+ type SmsConsentRecorded = {
916
+ object: "sms_consent";
917
+ phone: string;
918
+ recorded: {
919
+ id: string;
920
+ action: string;
921
+ source: string | null;
922
+ occurred_at: string;
923
+ } | null;
924
+ };
925
+ type SmsNumber = {
926
+ object: "sms_number";
927
+ /** Prefixed number id, e.g. `snum_…`. */
928
+ id: string;
929
+ /** E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval. */
930
+ phone_number: string | null;
931
+ /** `long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender. */
932
+ type: "toll_free" | "ten_dlc" | "long_code" | "sender_id" | "simulator";
933
+ /** Only `active` numbers can send. */
934
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
935
+ /** Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag. */
936
+ is_default: boolean;
937
+ /** ISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded. */
938
+ country: string | null;
939
+ /** Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs 1¢. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator. */
940
+ two_way: boolean;
941
+ /** ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown. */
942
+ reach: Array<string>;
943
+ /** The brand this number is registered under. */
944
+ brand_id: string | null;
945
+ /** What carriers approved this number to send. Required for approval; submitted with the number. */
946
+ use_case: {
947
+ name: string;
948
+ category: string | null;
949
+ } | null;
950
+ /** Set when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`. */
951
+ action_required_reason: string | null;
952
+ /** Present on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set. */
953
+ sender_id_group: {
954
+ /** The Sender ID string recipients see. */
955
+ name: string;
956
+ /** The brand that owns this Sender ID. */
957
+ brand_id: string | null;
958
+ /** Every country this Sender ID is enabled for, with each country's own status. */
959
+ countries: Array<{
960
+ /** ISO-3166 alpha-2. */
961
+ country: string;
962
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
963
+ }>;
964
+ } | null;
624
965
  created_at: string;
625
966
  };
967
+ type SmsPatch = {
968
+ /** Cancel a `queued` or `scheduled` text. Its reserved credit is refunded. */
969
+ cancel?: true;
970
+ /** Move a `scheduled` text to this future time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC. */
971
+ scheduled_at?: string;
972
+ };
626
973
  type SmsSend = {
974
+ /** Recipient phone number in E.164 format, e.g. `+15551234567`. */
627
975
  to: string;
976
+ /** Optional sender to send from: a number id from `GET /sms/numbers` (`snum_…`), or the E.164 number / Sender ID string itself (e.g. `+18005550100`, `Acme`). Must belong to your workspace, be active, and be able to reach the recipient's country. Otherwise it answers `404 not_found`, `403 sender_not_approved`, or `422 sender_cannot_reach`. Omit to route automatically: a transactional text to someone who texted one of your numbers in the last 30 days goes out from that number, so a reply stays in the same thread on their phone; otherwise Unitpost picks the active sender whose reach covers the recipient's country (10DLC before toll-free for US recipients; the matching Sender ID elsewhere), exactly as campaigns do. */
977
+ from?: string;
978
+ /** Message text. Billing is per segment (160 GSM-7 chars single-segment, 153 per segment concatenated; 70/67 for Unicode). */
628
979
  body: string;
980
+ /** Defaults to `transactional`. Use `marketing` for anything promotional (offers, sales, newsletters): marketing sends require the recipient's prior express consent on record and honor recipient-local quiet hours. Sending promotional text as `transactional` skips both checks and breaks carrier rules. */
629
981
  type?: "transactional" | "marketing";
982
+ /** Time to send at: ISO 8601 with `Z` or a `±hh:mm` offset (e.g. `2026-10-24T02:00:00Z` or `2026-10-24T09:00:00+07:00`), normalized to UTC. Omit to send immediately. A time in the past is not refused: the text goes out right away. */
630
983
  scheduled_at?: string;
984
+ /** Create a contact for this recipient if one doesn't exist yet. Defaults to false. Sends don't modify your contact list. When the recipient is already a contact, the message is attached to them either way. A contact created this way records no consent, so it can't be used for marketing sends. */
985
+ create_contact?: boolean;
986
+ };
987
+ type SmsStats = {
988
+ object: "sms_stats";
989
+ /** The rolling window, in days. */
990
+ window_days: number;
991
+ /** Non-null when the requested window exceeded the plan's log retention and was clamped to this many days. */
992
+ clamped_to_retention_days: number | null;
993
+ totals: {
994
+ /** Queued, scheduled, or being handed to the carrier. */
995
+ queued: number;
996
+ /** Accepted by the carrier, no delivery receipt yet. */
997
+ sent: number;
998
+ /** The carrier confirmed delivery. */
999
+ delivered: number;
1000
+ /** Refused by the carrier or a compliance check after we tried. */
1001
+ failed: number;
1002
+ /** Skipped on purpose before sending (consent, opt-out, reach, quiet hours). Never billed. */
1003
+ suppressed: number;
1004
+ canceled: number;
1005
+ /** Texts received from recipients, including STOP/HELP keywords. */
1006
+ inbound: number;
1007
+ /** Segments billed for outbound texts that reached the carrier. */
1008
+ segments: number;
1009
+ };
1010
+ /** Percentages (one decimal). delivery and failure are vs sent + delivered + failed; suppression is vs those plus suppressed. */
1011
+ rates: {
1012
+ delivery: number;
1013
+ failure: number;
1014
+ suppression: number;
1015
+ };
1016
+ };
1017
+ type SmsTemplate = {
1018
+ object: "sms_template";
1019
+ id: string;
1020
+ name: string;
1021
+ body: string;
1022
+ status: "draft" | "published";
1023
+ created_at: string;
1024
+ updated_at: string;
1025
+ };
1026
+ type SmsTemplateCreate = {
1027
+ name: string;
1028
+ body?: string;
1029
+ };
1030
+ type SmsTemplateUpdate = {
1031
+ name?: string;
1032
+ body?: string;
1033
+ status?: "draft" | "published";
631
1034
  };
632
1035
  type Suppression = {
633
1036
  object: "suppression";
@@ -642,8 +1045,11 @@ type Suppression = {
642
1045
  };
643
1046
  type SuppressionBulkResult = {
644
1047
  object: "list";
1048
+ /** Addresses newly suppressed. */
645
1049
  added: number;
1050
+ /** Addresses already suppressed (no-op). */
646
1051
  skipped: number;
1052
+ /** Deduplicated input count. */
647
1053
  total: number;
648
1054
  };
649
1055
  type SuppressionCreate = {
@@ -658,27 +1064,123 @@ type Template = {
658
1064
  name: string;
659
1065
  subject: string | null;
660
1066
  status: "draft" | "published";
1067
+ /** Which editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body. */
1068
+ editor?: "simple" | "design" | "code";
1069
+ /** The coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`. */
1070
+ kind: "simple" | "designed";
1071
+ /** Inbox preview text: the snippet most inboxes show after the subject. Empty when unset. */
1072
+ preview_text?: string;
661
1073
  html?: string | null;
1074
+ /** A `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows. */
1075
+ tsx?: string | null;
1076
+ /** Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user. */
1077
+ warnings?: Array<string>;
662
1078
  created_at: string;
663
1079
  updated_at: string;
664
1080
  };
1081
+ /** Create a template. The body is EXACTLY ONE of `tsx` (a Design email from our components — the default), `html` (a Code email: raw HTML) or `text` (a Simple, Gmail-style plain email). The spec can't express this exclusivity, so `required` lists only `name`; a request with none or several is rejected with 422. `theme` goes with `tsx` only. */
665
1082
  type TemplateCreate = {
666
1083
  name: string;
667
1084
  subject?: string;
668
- html: string;
1085
+ /** A Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>; no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1086
+ tsx?: string;
1087
+ /** A Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1088
+ html?: string;
1089
+ /** A Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`. */
1090
+ text?: string;
1091
+ /** Page-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style). */
1092
+ theme?: {
1093
+ /** Page backdrop around the email card, e.g. `#f5f5f4`. */
1094
+ background_color?: string;
1095
+ /** The email card's background, e.g. `#ffffff`. */
1096
+ body_color?: string;
1097
+ /** Card width in px (default 600; 560–640 reads best). */
1098
+ content_width?: number;
1099
+ /** Padding inside the card in px. 0 lets full-width sections reach the edges. */
1100
+ body_padding?: number;
1101
+ /** Card corner radius in px. */
1102
+ body_radius?: number;
1103
+ /** A stroke around the card (corners follow `body_radius`); null removes it. */
1104
+ body_border?: {
1105
+ width?: number;
1106
+ style?: "solid" | "dashed" | "dotted";
1107
+ color?: string;
1108
+ } | null;
1109
+ /** Default font stack, e.g. `Inter, -apple-system, 'Segoe UI', Arial, sans-serif`. */
1110
+ font_family?: string;
1111
+ /** Default text color. */
1112
+ text_color?: string;
1113
+ /** Inline link color. */
1114
+ link_color?: string;
1115
+ };
1116
+ /** Inbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>. */
1117
+ preview_text?: string;
669
1118
  category?: "transactional" | "marketing";
670
1119
  };
1120
+ type TemplateTestSend = {
1121
+ to: string;
1122
+ subject?: string;
1123
+ variables?: Record<string, string>;
1124
+ };
1125
+ type TemplateTestSendResult = {
1126
+ object: "template_test_send";
1127
+ /** The test email (`email_…`); retrieve it like any email. */
1128
+ email_id: string;
1129
+ /** The test email's status, usually `queued`. */
1130
+ status: string;
1131
+ /** False when this environment records sends without delivering them. */
1132
+ dispatched: boolean;
1133
+ /** Variables with no sample value, sent as a literal `{{name}}`. */
1134
+ unresolved_variables: Array<string>;
1135
+ };
1136
+ /** Update a template's metadata and/or body. Replace the body with ONE of `tsx` (Design), `html` (Code) or `text` (Simple) — 422 for several. Match the template's current `editor` (design → `tsx`, code → `html`, simple → `text`); another body field switches it, so only do that when the user asked. `editor` alone converts the current body. `theme` restyles a Design template (with or without `tsx`). A whole read sent back is fine: `html`, `tsx` (incl. its `null`) and `editor` that repeat the current read are ignored, so the field you changed is the edit. */
671
1137
  type TemplateUpdate = {
672
1138
  name?: string;
673
1139
  subject?: string | null;
674
1140
  status?: "draft" | "published";
1141
+ /** A Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>; no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1142
+ tsx?: string;
1143
+ /** A Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
675
1144
  html?: string;
1145
+ /** A Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`. */
1146
+ text?: string;
1147
+ /** Page-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style). */
1148
+ theme?: {
1149
+ /** Page backdrop around the email card, e.g. `#f5f5f4`. */
1150
+ background_color?: string;
1151
+ /** The email card's background, e.g. `#ffffff`. */
1152
+ body_color?: string;
1153
+ /** Card width in px (default 600; 560–640 reads best). */
1154
+ content_width?: number;
1155
+ /** Padding inside the card in px. 0 lets full-width sections reach the edges. */
1156
+ body_padding?: number;
1157
+ /** Card corner radius in px. */
1158
+ body_radius?: number;
1159
+ /** A stroke around the card (corners follow `body_radius`); null removes it. */
1160
+ body_border?: {
1161
+ width?: number;
1162
+ style?: "solid" | "dashed" | "dotted";
1163
+ color?: string;
1164
+ } | null;
1165
+ /** Default font stack, e.g. `Inter, -apple-system, 'Segoe UI', Arial, sans-serif`. */
1166
+ font_family?: string;
1167
+ /** Default text color. */
1168
+ text_color?: string;
1169
+ /** Inline link color. */
1170
+ link_color?: string;
1171
+ };
1172
+ /** Inbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>. */
1173
+ preview_text?: string;
1174
+ /** Convert the template to this editor. Alone (no body field) it converts the CURRENT body: simple → design keeps every line; design → code renders it to HTML (looks the same, no longer editable block by block); code → design rebuilds components where the HTML maps and keeps the rest as HTML; design or code → simple flattens to plain lines. What a conversion changes comes back in `warnings`. With a body field it must name that field's editor (`tsx` = design, `html` = code, `text` = simple). Only when the user asked to switch. */
1175
+ editor?: "simple" | "design" | "code";
676
1176
  };
677
1177
  type Topic = {
678
1178
  object: "topic";
679
1179
  id: string;
680
1180
  name: string;
681
1181
  description: string | null;
1182
+ /** Which channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`. */
1183
+ channel: "email" | "sms";
682
1184
  default_opt_in: boolean;
683
1185
  created_at: string;
684
1186
  updated_at: string;
@@ -713,35 +1215,97 @@ type Usage$1 = {
713
1215
  overage_cap_cents: number | null;
714
1216
  email_rate_per_1k_cents: number | null;
715
1217
  } | null;
1218
+ spend: {
1219
+ total_cents: number;
1220
+ email_cents: number;
1221
+ sms_cents: number;
1222
+ sms_carrier_fees_cents: number;
1223
+ other_cents: number;
1224
+ refunds_cents: number;
1225
+ included_cents: number;
1226
+ purchased_credit_cents: number;
1227
+ overage_cents: number;
1228
+ credits_added_cents: number;
1229
+ };
1230
+ sms: {
1231
+ messages: number;
1232
+ segments: number;
1233
+ send_cents: number;
1234
+ received: number;
1235
+ received_cents: number;
1236
+ monthly_fees_cents: number;
1237
+ one_time_fees_cents: number;
1238
+ refunds_cents: number;
1239
+ countries: Array<{
1240
+ country: string;
1241
+ messages: number;
1242
+ segments: number;
1243
+ price_per_segment_cents: number | null;
1244
+ cost_cents: number;
1245
+ }>;
1246
+ };
716
1247
  };
717
1248
  type Webhook = {
718
1249
  object: "webhook";
719
1250
  id: string;
720
1251
  name: string;
721
1252
  url: string;
722
- events: Array<string>;
1253
+ events: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
723
1254
  status: "enabled" | "disabled" | "suspended";
724
1255
  created_at: string;
725
1256
  updated_at: string;
726
1257
  };
727
1258
  type WebhookCreate = {
728
1259
  url: string;
729
- events: Array<string>;
1260
+ events: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
730
1261
  name?: string;
731
1262
  };
732
1263
  type WebhookCreated = Webhook & {
1264
+ /** The HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint. */
733
1265
  signing_secret: string;
734
1266
  };
1267
+ type WebhookDelivery = {
1268
+ object: "webhook_delivery";
1269
+ /** The delivery id (`msg_…`). */
1270
+ id: string;
1271
+ /** The `svix-id` header this delivery's requests carried; retries reuse it, so dedupe on it. */
1272
+ svix_id: string;
1273
+ webhook_id: string;
1274
+ /** The event (`evt_…`). The delivered payload's `event_id` is the same id without the `evt_` prefix. */
1275
+ event_id: string;
1276
+ event_type: string;
1277
+ /** `queued`: held while the endpoint is disabled. `retrying`: an attempt failed and another is scheduled at `next_attempt_at`. `exhausted`: every retry failed. */
1278
+ status: "pending" | "queued" | "retrying" | "succeeded" | "failed" | "exhausted";
1279
+ /** Attempts made so far. */
1280
+ attempt: number;
1281
+ /** Your endpoint's last HTTP status, or null before an attempt or on a network error. */
1282
+ response_status: number | null;
1283
+ error: string | null;
1284
+ scheduled_at: string;
1285
+ next_attempt_at: string | null;
1286
+ delivered_at: string | null;
1287
+ event_created_at: string;
1288
+ /** The event's `data`, as delivered. */
1289
+ data: Record<string, unknown>;
1290
+ };
1291
+ type WebhookSecretRotated = WebhookCreated & {
1292
+ /** Until this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then. */
1293
+ previous_secret_expires_at: string;
1294
+ };
735
1295
  type WebhookTestResult = {
736
1296
  object: "webhook_test";
1297
+ /** Whether the endpoint accepted the probe (2xx). */
737
1298
  delivered: boolean;
1299
+ /** The HTTP status the endpoint returned, or null on a transport error. */
738
1300
  response_status: number | null;
1301
+ /** The sample event type that was sent. */
739
1302
  event_type: string;
1303
+ /** A transport/error message when delivery failed, else null. */
740
1304
  error: string | null;
741
1305
  };
742
1306
  type WebhookUpdate = {
743
1307
  url?: string;
744
- events?: Array<string>;
1308
+ events?: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
745
1309
  name?: string;
746
1310
  status?: "enabled" | "disabled";
747
1311
  };
@@ -757,6 +1321,7 @@ type models_BrandKitList = BrandKitList;
757
1321
  type models_Campaign = Campaign;
758
1322
  type models_CampaignCreate = CampaignCreate;
759
1323
  type models_CampaignReschedule = CampaignReschedule;
1324
+ type models_CampaignSend = CampaignSend;
760
1325
  type models_CampaignUpdate = CampaignUpdate;
761
1326
  type models_Contact = Contact;
762
1327
  type models_ContactCreate = ContactCreate;
@@ -771,9 +1336,11 @@ type models_ContactTopicSet = ContactTopicSet;
771
1336
  type models_ContactUpdate = ContactUpdate;
772
1337
  type models_Domain = Domain;
773
1338
  type models_DomainCreate = DomainCreate;
1339
+ type models_DomainDiagnosis = DomainDiagnosis;
774
1340
  type models_DomainUpdate = DomainUpdate;
775
1341
  type models_EmailPatch = EmailPatch;
776
1342
  type models_EmailStats = EmailStats;
1343
+ type models_Job = Job;
777
1344
  type models_ReceivedAttachmentUrl = ReceivedAttachmentUrl;
778
1345
  type models_ReceivedEmail = ReceivedEmail;
779
1346
  type models_ReceivedEmailSummary = ReceivedEmailSummary;
@@ -784,13 +1351,30 @@ type models_SegmentMemberAdd = SegmentMemberAdd;
784
1351
  type models_SegmentUpdate = SegmentUpdate;
785
1352
  type models_SendEmail = SendEmail;
786
1353
  type models_SendResult = SendResult;
787
- type models_Sms = Sms;
1354
+ type models_SmsBrand = SmsBrand;
1355
+ type models_SmsCampaign = SmsCampaign;
1356
+ type models_SmsCampaignCreate = SmsCampaignCreate;
1357
+ type models_SmsCampaignReschedule = SmsCampaignReschedule;
1358
+ type models_SmsCampaignSend = SmsCampaignSend;
1359
+ type models_SmsCampaignUpdate = SmsCampaignUpdate;
1360
+ type models_SmsCampaignValidation = SmsCampaignValidation;
1361
+ type models_SmsConsent = SmsConsent;
1362
+ type models_SmsConsentRecord = SmsConsentRecord;
1363
+ type models_SmsConsentRecorded = SmsConsentRecorded;
1364
+ type models_SmsNumber = SmsNumber;
1365
+ type models_SmsPatch = SmsPatch;
788
1366
  type models_SmsSend = SmsSend;
1367
+ type models_SmsStats = SmsStats;
1368
+ type models_SmsTemplate = SmsTemplate;
1369
+ type models_SmsTemplateCreate = SmsTemplateCreate;
1370
+ type models_SmsTemplateUpdate = SmsTemplateUpdate;
789
1371
  type models_Suppression = Suppression;
790
1372
  type models_SuppressionBulkResult = SuppressionBulkResult;
791
1373
  type models_SuppressionCreate = SuppressionCreate;
792
1374
  type models_Template = Template;
793
1375
  type models_TemplateCreate = TemplateCreate;
1376
+ type models_TemplateTestSend = TemplateTestSend;
1377
+ type models_TemplateTestSendResult = TemplateTestSendResult;
794
1378
  type models_TemplateUpdate = TemplateUpdate;
795
1379
  type models_Topic = Topic;
796
1380
  type models_TopicCreate = TopicCreate;
@@ -798,12 +1382,27 @@ type models_TopicUpdate = TopicUpdate;
798
1382
  type models_Webhook = Webhook;
799
1383
  type models_WebhookCreate = WebhookCreate;
800
1384
  type models_WebhookCreated = WebhookCreated;
1385
+ type models_WebhookDelivery = WebhookDelivery;
1386
+ type models_WebhookSecretRotated = WebhookSecretRotated;
801
1387
  type models_WebhookTestResult = WebhookTestResult;
802
1388
  type models_WebhookUpdate = WebhookUpdate;
803
1389
  declare namespace models {
804
- export type { models_ApiKey as ApiKey, models_ApiKeyCreate as ApiKeyCreate, models_ApiKeyCreated as ApiKeyCreated, models_Batch as Batch, models_BatchSend as BatchSend, models_BatchSendResult as BatchSendResult, models_BrandKit as BrandKit, models_BrandKitList as BrandKitList, models_Campaign as Campaign, models_CampaignCreate as CampaignCreate, models_CampaignReschedule as CampaignReschedule, models_CampaignUpdate as CampaignUpdate, models_Contact as Contact, models_ContactCreate as ContactCreate, models_ContactField as ContactField, models_ContactFieldCreate as ContactFieldCreate, models_ContactFieldRename as ContactFieldRename, models_ContactFieldUpdate as ContactFieldUpdate, models_ContactImport as ContactImport, models_ContactImportCreate as ContactImportCreate, models_ContactTopic as ContactTopic, models_ContactTopicSet as ContactTopicSet, models_ContactUpdate as ContactUpdate, models_Domain as Domain, models_DomainCreate as DomainCreate, models_DomainUpdate as DomainUpdate, Email$1 as Email, models_EmailPatch as EmailPatch, models_EmailStats as EmailStats, Error$1 as Error, models_ReceivedAttachmentUrl as ReceivedAttachmentUrl, models_ReceivedEmail as ReceivedEmail, models_ReceivedEmailSummary as ReceivedEmailSummary, models_Segment as Segment, models_SegmentCreate as SegmentCreate, models_SegmentMember as SegmentMember, models_SegmentMemberAdd as SegmentMemberAdd, models_SegmentUpdate as SegmentUpdate, models_SendEmail as SendEmail, models_SendResult as SendResult, models_Sms as Sms, models_SmsSend as SmsSend, models_Suppression as Suppression, models_SuppressionBulkResult as SuppressionBulkResult, models_SuppressionCreate as SuppressionCreate, models_Template as Template, models_TemplateCreate as TemplateCreate, models_TemplateUpdate as TemplateUpdate, models_Topic as Topic, models_TopicCreate as TopicCreate, models_TopicUpdate as TopicUpdate, Usage$1 as Usage, models_Webhook as Webhook, models_WebhookCreate as WebhookCreate, models_WebhookCreated as WebhookCreated, models_WebhookTestResult as WebhookTestResult, models_WebhookUpdate as WebhookUpdate };
1390
+ export type { models_ApiKey as ApiKey, models_ApiKeyCreate as ApiKeyCreate, models_ApiKeyCreated as ApiKeyCreated, models_Batch as Batch, models_BatchSend as BatchSend, models_BatchSendResult as BatchSendResult, models_BrandKit as BrandKit, models_BrandKitList as BrandKitList, models_Campaign as Campaign, models_CampaignCreate as CampaignCreate, models_CampaignReschedule as CampaignReschedule, models_CampaignSend as CampaignSend, models_CampaignUpdate as CampaignUpdate, models_Contact as Contact, models_ContactCreate as ContactCreate, models_ContactField as ContactField, models_ContactFieldCreate as ContactFieldCreate, models_ContactFieldRename as ContactFieldRename, models_ContactFieldUpdate as ContactFieldUpdate, models_ContactImport as ContactImport, models_ContactImportCreate as ContactImportCreate, models_ContactTopic as ContactTopic, models_ContactTopicSet as ContactTopicSet, models_ContactUpdate as ContactUpdate, models_Domain as Domain, models_DomainCreate as DomainCreate, models_DomainDiagnosis as DomainDiagnosis, models_DomainUpdate as DomainUpdate, Email$1 as Email, models_EmailPatch as EmailPatch, models_EmailStats as EmailStats, Error$1 as Error, models_Job as Job, models_ReceivedAttachmentUrl as ReceivedAttachmentUrl, models_ReceivedEmail as ReceivedEmail, models_ReceivedEmailSummary as ReceivedEmailSummary, models_Segment as Segment, models_SegmentCreate as SegmentCreate, models_SegmentMember as SegmentMember, models_SegmentMemberAdd as SegmentMemberAdd, models_SegmentUpdate as SegmentUpdate, models_SendEmail as SendEmail, models_SendResult as SendResult, Sms$1 as Sms, models_SmsBrand as SmsBrand, models_SmsCampaign as SmsCampaign, models_SmsCampaignCreate as SmsCampaignCreate, models_SmsCampaignReschedule as SmsCampaignReschedule, models_SmsCampaignSend as SmsCampaignSend, models_SmsCampaignUpdate as SmsCampaignUpdate, models_SmsCampaignValidation as SmsCampaignValidation, models_SmsConsent as SmsConsent, models_SmsConsentRecord as SmsConsentRecord, models_SmsConsentRecorded as SmsConsentRecorded, models_SmsNumber as SmsNumber, models_SmsPatch as SmsPatch, models_SmsSend as SmsSend, models_SmsStats as SmsStats, models_SmsTemplate as SmsTemplate, models_SmsTemplateCreate as SmsTemplateCreate, models_SmsTemplateUpdate as SmsTemplateUpdate, models_Suppression as Suppression, models_SuppressionBulkResult as SuppressionBulkResult, models_SuppressionCreate as SuppressionCreate, models_Template as Template, models_TemplateCreate as TemplateCreate, models_TemplateTestSend as TemplateTestSend, models_TemplateTestSendResult as TemplateTestSendResult, models_TemplateUpdate as TemplateUpdate, models_Topic as Topic, models_TopicCreate as TopicCreate, models_TopicUpdate as TopicUpdate, Usage$1 as Usage, models_Webhook as Webhook, models_WebhookCreate as WebhookCreate, models_WebhookCreated as WebhookCreated, models_WebhookDelivery as WebhookDelivery, models_WebhookSecretRotated as WebhookSecretRotated, models_WebhookTestResult as WebhookTestResult, models_WebhookUpdate as WebhookUpdate };
805
1391
  }
806
1392
 
1393
+ /** Filters for `sms.list` / `sms.listAll`. */
1394
+ type SmsListParams = ListParams & {
1395
+ direction?: "inbound" | "outbound";
1396
+ status?: string;
1397
+ from?: string;
1398
+ to?: string;
1399
+ /** The other party's number: both directions of the conversation. */
1400
+ participant?: string;
1401
+ contact_id?: string;
1402
+ campaign_id?: string;
1403
+ created_after?: string;
1404
+ created_before?: string;
1405
+ };
807
1406
  type Result<T> = Promise<{
808
1407
  data: T | null;
809
1408
  error: UnitpostError | null;
@@ -815,6 +1414,129 @@ declare class Resource {
815
1414
  protected readonly http: HttpClient;
816
1415
  constructor(http: HttpClient);
817
1416
  }
1417
+ declare class Sms extends Resource {
1418
+ /** SMS templates: plain-text bodies with `{{variable}}` placeholders. */
1419
+ readonly templates: SmsTemplates;
1420
+ /** SMS campaigns: a published SMS template sent to a segment. */
1421
+ readonly campaigns: SmsCampaigns;
1422
+ /** SMS subscription topics (independent from email topics). */
1423
+ readonly topics: SmsTopics;
1424
+ constructor(http: HttpClient);
1425
+ /**
1426
+ * Send or schedule an SMS message.
1427
+ *
1428
+ * The recipient must be E.164 (`+15551234567`). Marketing sends require the
1429
+ * recipient's prior express consent on record and honor recipient-local
1430
+ * quiet hours (deferred, never dropped). Billing is per segment. An
1431
+ * `Idempotency-Key` is generated automatically when you don't pass one.
1432
+ */
1433
+ send(body: SmsSend, opts?: SendOptions): Result<Sms$1>;
1434
+ /** Retrieve one SMS message's status and delivery state. */
1435
+ get(id: string): Result<Sms$1>;
1436
+ /**
1437
+ * Cancel a queued/scheduled SMS (`{ cancel: true }` — its reserved credit is
1438
+ * refunded) or move a scheduled one (`{ scheduled_at }`).
1439
+ */
1440
+ update(id: string, body: SmsPatch): Result<Sms$1>;
1441
+ /**
1442
+ * List SMS messages (cursor-paginated, newest first). `participant` returns
1443
+ * the whole conversation with one number: texts you sent them and their
1444
+ * replies.
1445
+ */
1446
+ list(params?: SmsListParams): Result<ListResponse<Sms$1>>;
1447
+ /** Async-iterate every SMS message (same filters as `list`). */
1448
+ listAll(params?: SmsListParams): AsyncGenerator<Sms$1, void, void>;
1449
+ /**
1450
+ * List SMS brands and their setup status.
1451
+ *
1452
+ * A brand is the business identity carriers register before they approve a
1453
+ * phone number, so this is what to poll to answer "is SMS ready yet?":
1454
+ * `status` says whether you or the carrier is the blocker, and `missing`
1455
+ * lists exactly what is still required.
1456
+ *
1457
+ * Read-only — creating a brand is a paid carrier submission and is only
1458
+ * available in the dashboard.
1459
+ */
1460
+ brands(params?: ListParams): Result<ListResponse<SmsBrand>>;
1461
+ /**
1462
+ * List SMS phone numbers.
1463
+ *
1464
+ * Only numbers with `status: "active"` can send. A `ten_dlc` number has no
1465
+ * `phone_number` until carriers approve it, and a `simulator` number only
1466
+ * reaches verified test destinations.
1467
+ *
1468
+ * Read-only — requesting or releasing a number is only available in the
1469
+ * dashboard.
1470
+ */
1471
+ numbers(params?: ListParams): Result<ListResponse<SmsNumber>>;
1472
+ /**
1473
+ * SMS delivery stats over a rolling window: queued, sent, delivered,
1474
+ * failed, suppressed, canceled, inbound and segments billed, with delivery,
1475
+ * failure and suppression rates. No opens or clicks on SMS.
1476
+ *
1477
+ * `days` is the window size (1–365); defaults to 30 server-side.
1478
+ */
1479
+ stats(params?: {
1480
+ days?: number;
1481
+ }): Result<SmsStats>;
1482
+ /** Read a contact's SMS consent state and immutable consent history. */
1483
+ smsConsent(contactId: string): Result<SmsConsent>;
1484
+ /** Record an SMS consent change (opt-in or opt-out) for a contact. */
1485
+ recordSmsConsent(contactId: string, body: SmsConsentRecord): Result<SmsConsentRecorded>;
1486
+ }
1487
+ /**
1488
+ * SMS templates (`/sms/templates`). Draft → published like email templates;
1489
+ * only published templates can be sent by an SMS campaign.
1490
+ */
1491
+ declare class SmsTemplates extends Resource {
1492
+ list(params?: ListParams): Result<ListResponse<SmsTemplate>>;
1493
+ listAll(params?: ListParams): AsyncGenerator<SmsTemplate, void, void>;
1494
+ create(body: SmsTemplateCreate): Result<SmsTemplate>;
1495
+ get(id: string): Result<SmsTemplate>;
1496
+ update(id: string, body: SmsTemplateUpdate): Result<SmsTemplate>;
1497
+ delete(id: string): Result<null>;
1498
+ }
1499
+ /** SMS subscription topics (`/sms/topics`); `delete` archives. */
1500
+ declare class SmsCampaigns extends Resource {
1501
+ list(params?: ListParams): Result<ListResponse<SmsCampaign>>;
1502
+ listAll(params?: ListParams): AsyncGenerator<SmsCampaign, void, void>;
1503
+ /** Create a draft. Omit `sender_id` for automatic routing. */
1504
+ create(body: SmsCampaignCreate): Result<SmsCampaign>;
1505
+ get(id: string): Result<SmsCampaign>;
1506
+ /** Edit a draft (409 once sent or scheduled). */
1507
+ update(id: string, body: SmsCampaignUpdate): Result<SmsCampaign>;
1508
+ /** Archive a draft or finished campaign (cancel an in-flight one first). */
1509
+ delete(id: string): Result<null>;
1510
+ /**
1511
+ * Send now, or pass `{ scheduled_at }` to schedule. A large audience whose
1512
+ * recipient check is still running is refused with `409 preflight_pending`:
1513
+ * poll `validate(id)` until it returns the report, then send again.
1514
+ */
1515
+ send(id: string, body?: SmsCampaignSend): Result<SmsCampaign>;
1516
+ /**
1517
+ * The campaign, already `canceled`. With more than 500 queued texts (202)
1518
+ * they are canceled and refunded in the background.
1519
+ */
1520
+ cancel(id: string): Result<SmsCampaign>;
1521
+ pause(id: string): Result<SmsCampaign>;
1522
+ resume(id: string): Result<SmsCampaign>;
1523
+ reschedule(id: string, body: SmsCampaignReschedule): Result<SmsCampaign>;
1524
+ /**
1525
+ * Who the campaign would reach if sent now (non-mutating). A large audience
1526
+ * is counted in the background: the first call returns that `Job` (202).
1527
+ * Call again until it returns the report; tell them apart with `object`
1528
+ * (`"job"`).
1529
+ */
1530
+ validate(id: string): Result<SmsCampaignValidation | Job>;
1531
+ }
1532
+ declare class SmsTopics extends Resource {
1533
+ list(params?: ListParams): Result<ListResponse<Topic>>;
1534
+ listAll(params?: ListParams): AsyncGenerator<Topic, void, void>;
1535
+ create(body: TopicCreate): Result<Topic>;
1536
+ get(id: string): Result<Topic>;
1537
+ update(id: string, body: TopicUpdate): Result<Topic>;
1538
+ delete(id: string): Result<null>;
1539
+ }
818
1540
  declare class Email extends Resource {
819
1541
  readonly topics: Topics;
820
1542
  readonly campaigns: Campaigns;
@@ -878,6 +1600,7 @@ declare class Contacts extends Resource {
878
1600
  import(body: ContactImportCreate): Result<ContactImport>;
879
1601
  listImports(params?: ListParams): Result<ListResponse<ContactImport>>;
880
1602
  getImport(id: string): Result<ContactImport>;
1603
+ cancelImport(id: string): Result<ContactImport>;
881
1604
  }
882
1605
  declare class ContactFields extends Resource {
883
1606
  list(params?: ListParams): Result<ListResponse<ContactField>>;
@@ -885,8 +1608,26 @@ declare class ContactFields extends Resource {
885
1608
  create(body: ContactFieldCreate): Result<ContactField>;
886
1609
  get(id: string): Result<ContactField>;
887
1610
  update(id: string, body: ContactFieldUpdate): Result<ContactField>;
888
- delete(id: string): Result<null>;
889
- rename(id: string, body: ContactFieldRename): Result<ContactField>;
1611
+ /**
1612
+ * `null` (204) when the field was deleted at once; a `Job` (202) when it
1613
+ * held a value on more than 5,000 contacts and the delete runs in the
1614
+ * background — follow it with `jobs.get(job.id)`.
1615
+ */
1616
+ delete(id: string): Result<null | Job>;
1617
+ /**
1618
+ * The renamed `ContactField` (200), or a `Job` (202) when more than 5,000
1619
+ * contacts hold the field: the key is already renamed and the values move in
1620
+ * the background — follow it with `jobs.get(job.id)`. Tell them apart with
1621
+ * `object` (`"contact_field"` / `"job"`).
1622
+ */
1623
+ rename(id: string, body: ContactFieldRename): Result<ContactField | Job>;
1624
+ }
1625
+ declare class Jobs extends Resource {
1626
+ /**
1627
+ * Retrieve a background job — the `202` answer of an operation too large for
1628
+ * one request. Poll until `status` is `COMPLETED`, `FAILED` or `CANCELED`.
1629
+ */
1630
+ get(id: string): Result<Job>;
890
1631
  }
891
1632
  declare class Segments extends Resource {
892
1633
  list(params?: ListParams): Result<ListResponse<Segment>>;
@@ -920,14 +1661,23 @@ declare class Campaigns extends Resource {
920
1661
  get(id: string): Result<Campaign>;
921
1662
  update(id: string, body: CampaignUpdate): Result<Campaign>;
922
1663
  delete(id: string): Result<null>;
923
- send(id: string): Result<Campaign>;
1664
+ /**
1665
+ * Send a draft. `{}` (the default) arms its saved `scheduled_at` while that
1666
+ * is still ahead, otherwise sends NOW; `{ scheduled_at: "<ISO 8601>" }`
1667
+ * schedules it; `{ scheduled_at: null }` sends now.
1668
+ */
1669
+ send(id: string, body?: CampaignSend): Result<Campaign>;
924
1670
  cancel(id: string): Result<Campaign>;
925
1671
  /** Pause a scheduled/sending campaign; already-sent messages are untouched. */
926
1672
  pause(id: string): Result<Campaign>;
927
1673
  /** Resume a paused campaign; sending continues with the remaining recipients. */
928
1674
  resume(id: string): Result<Campaign>;
929
1675
  reschedule(id: string, body: CampaignReschedule): Result<Campaign>;
930
- /** Non-mutating pre-send validation report. */
1676
+ /**
1677
+ * Non-mutating pre-send validation report. A large audience is counted in
1678
+ * the background: the first call returns that `Job` (202). Call again until
1679
+ * it returns the report.
1680
+ */
931
1681
  validate(id: string): Result<unknown>;
932
1682
  }
933
1683
  declare class Templates extends Resource {
@@ -937,6 +1687,12 @@ declare class Templates extends Resource {
937
1687
  get(id: string): Result<Template>;
938
1688
  update(id: string, body: TemplateUpdate): Result<Template>;
939
1689
  delete(id: string): Result<null>;
1690
+ /**
1691
+ * Send ONE test of the template to `to`, rendered with sample `variables`
1692
+ * exactly as a recipient gets it. Without a verified domain only workspace
1693
+ * members may receive it.
1694
+ */
1695
+ testSend(id: string, body: TemplateTestSend): Result<TemplateTestSendResult>;
940
1696
  }
941
1697
  /** Read-only Brand Kit profiles (voice, colors, pinned `/img/{id}` graphics). */
942
1698
  declare class BrandKits extends Resource {
@@ -958,6 +1714,8 @@ declare class Domains extends Resource {
958
1714
  verify(id: string): Result<Domain & {
959
1715
  checks?: unknown;
960
1716
  }>;
1717
+ /** Explain the domain's DNS: every nameserver's answer per record, and ranked findings with fixes. Read-only. */
1718
+ diagnose(id: string): Result<DomainDiagnosis>;
961
1719
  }
962
1720
  declare class Webhooks extends Resource {
963
1721
  list(params?: ListParams): Result<ListResponse<Webhook>>;
@@ -969,6 +1727,15 @@ declare class Webhooks extends Resource {
969
1727
  delete(id: string): Result<null>;
970
1728
  /** Fire a synchronous sample event at the endpoint. */
971
1729
  test(id: string): Result<WebhookTestResult>;
1730
+ /**
1731
+ * Mint a new signing secret. The response carries it exactly once; the old
1732
+ * secret co-signs deliveries until `previous_secret_expires_at` (24 h).
1733
+ */
1734
+ rotateSecret(id: string): Result<WebhookSecretRotated>;
1735
+ /** The endpoint's delivery log, newest first (cursor-paginated). */
1736
+ listDeliveries(id: string, params?: ListParams): Result<ListResponse<WebhookDelivery>>;
1737
+ /** Async-iterate every delivery of the endpoint. */
1738
+ listAllDeliveries(id: string, params?: ListParams): AsyncGenerator<WebhookDelivery, void, void>;
972
1739
  /**
973
1740
  * Verify a webhook delivery's signature and return the parsed event. Throws
974
1741
  * `WebhookVerificationError` on a missing/invalid/stale signature. Alias of the
@@ -984,8 +1751,12 @@ declare class ApiKeys extends Resource {
984
1751
  delete(id: string): Result<null>;
985
1752
  }
986
1753
  declare class Suppressions extends Resource {
987
- /** List suppressed addresses (your own + read-only platform rows). */
1754
+ /**
1755
+ * List your workspace's suppressed addresses. Unitpost-wide (platform)
1756
+ * blocks are enforced at send time but not listed — `get(email)` explains one.
1757
+ */
988
1758
  list(params?: ListParams & {
1759
+ /** @deprecated Ignored since 2026-10-13: the list is always your own suppressions. */
989
1760
  scope?: "workspace" | "platform";
990
1761
  }): Result<ListResponse<Suppression>>;
991
1762
  /** Async-iterate every suppressed address. */
@@ -1012,8 +1783,14 @@ declare class Usage extends Resource {
1012
1783
 
1013
1784
  declare class Unitpost {
1014
1785
  readonly email: Email;
1786
+ /**
1787
+ * SMS channel. Available on paid plans: on the free plan `send` returns a
1788
+ * 403 with code `limit_reached`; reads keep working.
1789
+ */
1790
+ readonly sms: Sms;
1015
1791
  readonly contacts: Contacts;
1016
1792
  readonly contactFields: ContactFields;
1793
+ readonly jobs: Jobs;
1017
1794
  readonly segments: Segments;
1018
1795
  readonly brandKits: BrandKits;
1019
1796
  readonly webhooks: Webhooks;
@@ -1023,4 +1800,4 @@ declare class Unitpost {
1023
1800
  constructor(apiKeyOrOptions?: string | UnitpostOptions);
1024
1801
  }
1025
1802
 
1026
- export { type ListParams, type ListResponse, models as Models, type Result, SDK_VERSION, type SendOptions, Unitpost, UnitpostError, type UnitpostOptions, type VerifyWebhookArgs, WebhookVerificationError, verifyWebhook };
1803
+ export { type ListParams, type ListResponse, models as Models, type Result, SDK_VERSION, type SendOptions, type SmsListParams, Unitpost, UnitpostError, type UnitpostOptions, type VerifyWebhookArgs, WebhookVerificationError, verifyWebhook };