unitpost 0.4.0 → 0.6.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.cts CHANGED
@@ -1,7 +1,9 @@
1
- declare const SDK_VERSION = "0.4.0";
1
+ declare const SDK_VERSION = "0.6.0";
2
2
  interface ApiFieldError {
3
3
  /** Dotted path to the offending field, e.g. "template.variables.first_name". */
4
4
  field: string;
5
+ /** A machine-readable reason for this entry, e.g. the SMS skip word on `to` (`out_of_reach`). */
6
+ code?: string;
5
7
  message: string;
6
8
  }
7
9
  /** A structured API error. Returned in `{ data, error }`, never thrown by default. */
@@ -11,12 +13,15 @@ declare class UnitpostError extends Error {
11
13
  readonly requestId: string | null;
12
14
  /** Per-field validation problems (present on 422 validation_error). */
13
15
  readonly details: ApiFieldError[];
16
+ /** A page that explains this error, when the API links one (e.g. `sending_paused`). */
17
+ readonly docUrl: string | null;
14
18
  constructor(args: {
15
19
  code: string;
16
20
  message: string;
17
21
  status: number;
18
22
  requestId: string | null;
19
23
  details?: ApiFieldError[];
24
+ docUrl?: string | null;
20
25
  });
21
26
  }
22
27
  interface UnitpostOptions {
@@ -44,6 +49,18 @@ interface UnitpostOptions {
44
49
  /** Injectable sleep (tests). Defaults to a real timer. */
45
50
  sleep?: (ms: number) => Promise<void>;
46
51
  }
52
+ /**
53
+ * What every call resolves to. `warning` is the response's `Unitpost-Warning`
54
+ * header, present only on a success that carried one: something the request
55
+ * left out or ignored without failing, e.g. a recipient on a reserved domain
56
+ * (example.com) that wasn't sent to, or a body field the operation ignored.
57
+ * Show it or log it; the call itself succeeded.
58
+ */
59
+ interface ApiResult<T> {
60
+ data: T | null;
61
+ error: UnitpostError | null;
62
+ warning?: string;
63
+ }
47
64
  interface RequestArgs {
48
65
  method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
49
66
  path: string;
@@ -73,12 +90,16 @@ declare class HttpClient {
73
90
  * is honored (clamped to `maxRetryDelay`); otherwise we use exponential
74
91
  * backoff with full jitter.
75
92
  */
76
- request<T>(args: RequestArgs): Promise<{
77
- data: T | null;
78
- error: UnitpostError | null;
79
- }>;
93
+ request<T>(args: RequestArgs): Promise<ApiResult<T>>;
80
94
  private backoffDelay;
81
95
  private attempt;
96
+ /**
97
+ * PUT bytes to a file's presigned upload URL (`files.upload`), with exactly
98
+ * the headers it was signed with: no API key, and no retries (storage
99
+ * refuses any other length or type). Returns the error, or `null` when
100
+ * storage took the bytes.
101
+ */
102
+ putBytes(url: string, headers: Record<string, string>, body: Uint8Array): Promise<UnitpostError | null>;
82
103
  private buildUrl;
83
104
  }
84
105
 
@@ -115,6 +136,34 @@ declare class WebhookVerificationError extends Error {
115
136
  */
116
137
  declare function verifyWebhook<T = unknown>(args: VerifyWebhookArgs): T;
117
138
 
139
+ type Activity = {
140
+ object: "activity";
141
+ id: string;
142
+ /** What happened, e.g. `contact_created`, `campaign_sent`, `domain_verified`. */
143
+ type: string;
144
+ /** The kind of record it happened to. */
145
+ subject: "contact" | "segment" | "topic" | "field" | "template" | "component" | "campaign" | "email" | "domain" | "sender_email" | "library_image" | "api_key" | "webhook" | "suppression" | "message" | "handle" | "workspace";
146
+ /** The record's id (prefixed where the record has a public id). */
147
+ subject_id: string | null;
148
+ /** The record's name at the time: a contact's email, a segment's name, …; a phone number is masked (`+1••••••7755`). */
149
+ subject_label: string | null;
150
+ contact_id: string | null;
151
+ /** The campaign the change is attributed to (e.g. an unsubscribe through its link). */
152
+ campaign_id: string | null;
153
+ actor: {
154
+ /** Who made the change: a teammate's name or email, `System`, `Carrier`, `Ask Unit`, or null. */
155
+ name: string | null;
156
+ /** For a change made over the API, MCP or Ask Unit: how, and which API key. */
157
+ via: {
158
+ surface: "api" | "mcp" | "unit";
159
+ credential: "api_key" | "oauth" | null;
160
+ api_key_id: string | null;
161
+ } | null;
162
+ };
163
+ /** Detail for the change, varying by `type`: a segment's or topic's name, a status before and after, a renamed field's keys, related ids (`campaign_id`, …). Descriptive keys only: addresses, URLs and error text stay in the dashboard. */
164
+ metadata: Record<string, unknown>;
165
+ created_at: string;
166
+ };
118
167
  type ApiKey = {
119
168
  object: "api_key";
120
169
  id: string;
@@ -129,12 +178,26 @@ type ApiKey = {
129
178
  type ApiKeyCreate = {
130
179
  name: string;
131
180
  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" | "sms:purchase" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
181
+ capabilities?: Array<"contacts:read" | "contacts:write" | "suppressions:read" | "suppressions:write" | "segments:read" | "segments:write" | "topics:read" | "topics:write" | "templates:read" | "templates:write" | "campaigns:read" | "campaigns:write" | "campaigns:send" | "domains:read" | "domains:write" | "emails:read" | "emails:send" | "emails:read_content" | "sms:read" | "sms:send" | "sms:manage" | "sms:purchase" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "branding:write" | "activity:read" | "spend_caps:write" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
133
182
  };
134
183
  type ApiKeyCreated = ApiKey & {
135
184
  /** The plaintext secret. Shown exactly once — store it now; it can never be retrieved again. */
136
185
  key: string;
137
186
  };
187
+ type ApiKeyUsage = {
188
+ object: "api_key_usage";
189
+ /** The key (`key_…`). */
190
+ id: string;
191
+ last_used_at: string | null;
192
+ /** Requests the key made in the last 24 hours, counted up to 100,000: `100001` means more than 100,000. */
193
+ requests_24h: number;
194
+ /** Of those, answered 4xx (`rate_limited_24h` included). Past the cap, these three count the latest 100,001 requests. */
195
+ client_errors_24h: number;
196
+ /** Of those, answered 5xx. */
197
+ server_errors_24h: number;
198
+ /** Of those, answered 429. */
199
+ rate_limited_24h: number;
200
+ };
138
201
  type Batch = {
139
202
  object: "batch";
140
203
  id: string;
@@ -212,11 +275,251 @@ type BatchSendResult = {
212
275
  data: Array<{
213
276
  id: string;
214
277
  }>;
278
+ /** Items that weren't sent, by their index in the request: one whose every `to` address is on a reserved domain (example.com, example.net, example.org), one the sending engine couldn't take, or one the batch never reached (a batch sent with an `Idempotency-Key` stops starting items 5 minutes after its request began). Send just those again in a new request with a new `Idempotency-Key`: the original key replays this answer. */
215
279
  failed: Array<{
216
280
  index: number;
217
281
  error: string;
218
282
  }>;
219
283
  };
284
+ type BrandImport = {
285
+ object: "brand_import";
286
+ id: string;
287
+ /** `preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it. */
288
+ status: "pending" | "running" | "preview_ready" | "completed" | "failed" | "cancelled";
289
+ /** Whether it waits for an accept (false: applied when the crawl lands). */
290
+ review: boolean;
291
+ source: {
292
+ kind: "url" | "text";
293
+ url: string | null;
294
+ };
295
+ /** The profile it fills. */
296
+ brand_kit_id: string | null;
297
+ /** What the import found, once ready. */
298
+ proposal: {
299
+ name: string | null;
300
+ website_url: string | null;
301
+ description: string | null;
302
+ tone: "NEUTRAL" | "FORMAL" | "FRIENDLY" | "PLAYFUL" | null;
303
+ voice_notes: string | null;
304
+ industry: string | null;
305
+ core_pages: Array<{
306
+ url: string;
307
+ title?: string;
308
+ }>;
309
+ extracted: {
310
+ colors?: Array<{
311
+ hex: string;
312
+ label?: string;
313
+ }>;
314
+ logo_urls?: Array<string>;
315
+ background_urls?: Array<string>;
316
+ fonts?: Array<string>;
317
+ };
318
+ memory_facts: Array<{
319
+ key: string;
320
+ content: string;
321
+ }>;
322
+ } | null;
323
+ warnings: Array<string>;
324
+ error: string | null;
325
+ created_at: string;
326
+ updated_at: string;
327
+ completed_at: string | null;
328
+ };
329
+ type BrandImportAccept = {
330
+ /** Apply to this profile instead of the one the import named. */
331
+ brand_kit_id?: string;
332
+ /** The profile's name (default: the one the import found). */
333
+ name?: string;
334
+ /** Also set the email branding's accent from the imported colors (the default profile only). */
335
+ sync_visual?: boolean;
336
+ };
337
+ type BrandImportAccepted = {
338
+ object: "brand_import";
339
+ id: string;
340
+ /** `preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it. */
341
+ status: "pending" | "running" | "preview_ready" | "completed" | "failed" | "cancelled";
342
+ /** Whether it waits for an accept (false: applied when the crawl lands). */
343
+ review: boolean;
344
+ source: {
345
+ kind: "url" | "text";
346
+ url: string | null;
347
+ };
348
+ /** The profile it fills. */
349
+ brand_kit_id: string | null;
350
+ /** What the import found, once ready. */
351
+ proposal: {
352
+ name: string | null;
353
+ website_url: string | null;
354
+ description: string | null;
355
+ tone: "NEUTRAL" | "FORMAL" | "FRIENDLY" | "PLAYFUL" | null;
356
+ voice_notes: string | null;
357
+ industry: string | null;
358
+ core_pages: Array<{
359
+ url: string;
360
+ title?: string;
361
+ }>;
362
+ extracted: {
363
+ colors?: Array<{
364
+ hex: string;
365
+ label?: string;
366
+ }>;
367
+ logo_urls?: Array<string>;
368
+ background_urls?: Array<string>;
369
+ fonts?: Array<string>;
370
+ };
371
+ memory_facts: Array<{
372
+ key: string;
373
+ content: string;
374
+ }>;
375
+ } | null;
376
+ warnings: Array<string>;
377
+ error: string | null;
378
+ created_at: string;
379
+ updated_at: string;
380
+ completed_at: string | null;
381
+ /** The profile as the accept left it. */
382
+ brand_kit: {
383
+ object: "brand_kit";
384
+ id: string;
385
+ name: string;
386
+ is_default: boolean;
387
+ website_url: string | null;
388
+ description: string | null;
389
+ tone: "NEUTRAL" | "FORMAL" | "FRIENDLY" | "PLAYFUL" | null;
390
+ voice_notes: string | null;
391
+ industry: string | null;
392
+ core_pages: Array<{
393
+ url: string;
394
+ title?: string;
395
+ }>;
396
+ extracted: {
397
+ colors?: Array<{
398
+ hex: string;
399
+ label?: string;
400
+ }>;
401
+ logo_urls?: Array<string>;
402
+ background_urls?: Array<string>;
403
+ fonts?: Array<string>;
404
+ };
405
+ graphics: Array<{
406
+ /** The image's bare id (kept for compatibility); `image_id` is its library id. */
407
+ library_image_id: string;
408
+ /** The library image (`img_…`, GET /library-images/{id}). */
409
+ image_id: string;
410
+ /** Put this in a template's `<Image src>`. */
411
+ path: string;
412
+ role: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
413
+ label?: string;
414
+ }>;
415
+ source: string | null;
416
+ updated_at: string | null;
417
+ };
418
+ /** What the accept couldn't bring in (a logo that wouldn't fetch, the graphics cap, a renamed profile). */
419
+ apply_warnings: Array<string>;
420
+ };
421
+ type BrandImportCreate = {
422
+ /** The site to read: an https URL or a bare domain (`acme.com`). */
423
+ url?: string;
424
+ /** Or paste the brand's own words (an about page, a style guide). */
425
+ text?: string;
426
+ /** With `text`: the brand's site, for the profile. */
427
+ website_url?: string | null;
428
+ /** The profile to fill (`bk_…`). Default: the default profile, or a new one when it already has content. */
429
+ brand_kit_id?: string;
430
+ /** `true` stops at the proposal for you to accept (POST …/accept); default `false` applies it when ready. */
431
+ review?: boolean;
432
+ /** Also set the email branding's accent from the imported colors (the default profile only). */
433
+ sync_visual?: boolean;
434
+ };
435
+ type Branding$1 = {
436
+ object: "branding";
437
+ /** The name the footer shows; the workspace's name unless one was set. */
438
+ company_name: string | null;
439
+ company_address: string | null;
440
+ /** The logo emails and the unsubscribe page show: the brand logo, else the workspace image, else none. */
441
+ logo_url: string | null;
442
+ has_brand_logo: boolean;
443
+ colors: {
444
+ background: string | null;
445
+ footer_background: string | null;
446
+ text: string | null;
447
+ accent: string | null;
448
+ button_text: string | null;
449
+ };
450
+ font: string | null;
451
+ /** The stored choice. */
452
+ hide_unitpost_branding: boolean;
453
+ /** Whether recipients see no mark now: the choice, the plan and the account together. */
454
+ unitpost_branding_hidden: boolean;
455
+ /** Whether the plan allows hiding the mark. */
456
+ can_hide_unitpost_branding: boolean;
457
+ unsubscribe_page: {
458
+ title: string | null;
459
+ description: string | null;
460
+ confirm: boolean;
461
+ collect_reason: boolean;
462
+ show_address: boolean;
463
+ show_topics: boolean;
464
+ save_label: string | null;
465
+ global_label: string | null;
466
+ global_note: string | null;
467
+ topics_heading: string | null;
468
+ };
469
+ footer: {
470
+ intro_text: string | null;
471
+ unsubscribe_label: string | null;
472
+ };
473
+ };
474
+ type BrandingUpdate = {
475
+ /** Shown in the footer (`{{company_name}}`). */
476
+ company_name?: string | null;
477
+ /** The postal address every marketing email carries (`{{company_address}}`). */
478
+ company_address?: string | null;
479
+ colors?: {
480
+ /** The page and footer background. */
481
+ background?: string | null;
482
+ /** The footer band, when it differs from the background. */
483
+ footer_background?: string | null;
484
+ text?: string | null;
485
+ /** Links and buttons. */
486
+ accent?: string | null;
487
+ /** Text on accent buttons (default white). */
488
+ button_text?: string | null;
489
+ };
490
+ /** One of: System default, Arial, Helvetica, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New. */
491
+ font?: "System default" | "Arial" | "Helvetica" | "Verdana" | "Tahoma" | "Trebuchet MS" | "Georgia" | "Times New Roman" | "Courier New" | null;
492
+ /** Hide the "Sent with Unitpost" mark. Paid plans only (403 `limit_reached`). */
493
+ hide_unitpost_branding?: boolean;
494
+ unsubscribe_page?: {
495
+ /** The page heading. */
496
+ title?: string | null;
497
+ /** The intro under the heading. */
498
+ description?: string | null;
499
+ /** Ask before unsubscribing from everything. */
500
+ confirm?: boolean;
501
+ /** Offer an optional "why are you leaving?". */
502
+ collect_reason?: boolean;
503
+ /** Show the postal address on the page (the footer always shows it). */
504
+ show_address?: boolean;
505
+ /** Let recipients choose topics on the page. */
506
+ show_topics?: boolean;
507
+ /** The topic-preferences save button. */
508
+ save_label?: string | null;
509
+ /** The unsubscribe-from-everything control. */
510
+ global_label?: string | null;
511
+ /** The note under it. */
512
+ global_note?: string | null;
513
+ /** The heading over the topics. */
514
+ topics_heading?: string | null;
515
+ };
516
+ footer?: {
517
+ /** The line before the unsubscribe link. */
518
+ intro_text?: string | null;
519
+ /** The unsubscribe link's text. */
520
+ unsubscribe_label?: string | null;
521
+ };
522
+ };
220
523
  type BrandKit = {
221
524
  object: "brand_kit";
222
525
  id: string;
@@ -241,13 +544,88 @@ type BrandKit = {
241
544
  fonts?: Array<string>;
242
545
  };
243
546
  graphics: Array<{
547
+ /** The image's bare id (kept for compatibility); `image_id` is its library id. */
244
548
  library_image_id: string;
549
+ /** The library image (`img_…`, GET /library-images/{id}). */
550
+ image_id?: string;
551
+ /** Put this in a template's `<Image src>`. */
552
+ path?: string;
245
553
  role: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
246
554
  label?: string;
247
555
  }>;
248
556
  source: string | null;
249
557
  updated_at: string | null;
250
558
  };
559
+ type BrandKitCreate = {
560
+ /** Unique in the workspace. */
561
+ name: string;
562
+ /** Make it the default profile (the first profile always is). */
563
+ make_default?: boolean;
564
+ };
565
+ type BrandKitGraphicAdd = {
566
+ /** A public https PNG, JPEG, GIF or WebP (fetched once, no redirects; up to 5 MB). */
567
+ url: string;
568
+ /** Default `logo`. */
569
+ role?: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
570
+ label?: string;
571
+ };
572
+ type BrandKitGraphicAdded = {
573
+ object: "brand_kit_graphic";
574
+ brand_kit: {
575
+ object: "brand_kit";
576
+ id: string;
577
+ name: string;
578
+ is_default: boolean;
579
+ website_url: string | null;
580
+ description: string | null;
581
+ tone: "NEUTRAL" | "FORMAL" | "FRIENDLY" | "PLAYFUL" | null;
582
+ voice_notes: string | null;
583
+ industry: string | null;
584
+ core_pages: Array<{
585
+ url: string;
586
+ title?: string;
587
+ }>;
588
+ extracted: {
589
+ colors?: Array<{
590
+ hex: string;
591
+ label?: string;
592
+ }>;
593
+ logo_urls?: Array<string>;
594
+ background_urls?: Array<string>;
595
+ fonts?: Array<string>;
596
+ };
597
+ graphics: Array<{
598
+ /** The image's bare id (kept for compatibility); `image_id` is its library id. */
599
+ library_image_id: string;
600
+ /** The library image (`img_…`, GET /library-images/{id}). */
601
+ image_id: string;
602
+ /** Put this in a template's `<Image src>`. */
603
+ path: string;
604
+ role: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
605
+ label?: string;
606
+ }>;
607
+ source: string | null;
608
+ updated_at: string | null;
609
+ };
610
+ image: {
611
+ object: "library_image";
612
+ id: string;
613
+ /** Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there. */
614
+ path: string;
615
+ /** The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost. */
616
+ url: string;
617
+ filename: string;
618
+ content_type: string;
619
+ /** Bytes. */
620
+ size: number;
621
+ width: number | null;
622
+ height: number | null;
623
+ /** The alt text suggested when the image is inserted. */
624
+ alt: string | null;
625
+ created_at: string;
626
+ updated_at: string;
627
+ };
628
+ };
251
629
  type BrandKitList = {
252
630
  object: "list";
253
631
  data: Array<{
@@ -274,7 +652,12 @@ type BrandKitList = {
274
652
  fonts?: Array<string>;
275
653
  };
276
654
  graphics: Array<{
655
+ /** The image's bare id (kept for compatibility); `image_id` is its library id. */
277
656
  library_image_id: string;
657
+ /** The library image (`img_…`, GET /library-images/{id}). */
658
+ image_id?: string;
659
+ /** Put this in a template's `<Image src>`. */
660
+ path?: string;
278
661
  role: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
279
662
  label?: string;
280
663
  }>;
@@ -283,6 +666,41 @@ type BrandKitList = {
283
666
  }>;
284
667
  default_id: string | null;
285
668
  };
669
+ type BrandKitUpdate = {
670
+ name?: string;
671
+ /** An https URL; `null` or `""` clears it. */
672
+ website_url?: string | null;
673
+ /** What the brand does. */
674
+ description?: string | null;
675
+ tone?: "NEUTRAL" | "FORMAL" | "FRIENDLY" | "PLAYFUL" | null;
676
+ /** Dos and don'ts for writing in this voice. */
677
+ voice_notes?: string | null;
678
+ /** The brand's industry. */
679
+ industry?: string | null;
680
+ /** Replaces the list. */
681
+ core_pages?: Array<{
682
+ url: string;
683
+ title?: string;
684
+ }>;
685
+ /** The palette, logo and background candidates, fonts. Replaces the set. */
686
+ extracted?: {
687
+ colors?: Array<{
688
+ hex: string;
689
+ label?: string;
690
+ }>;
691
+ logo_urls?: Array<string>;
692
+ background_urls?: Array<string>;
693
+ fonts?: Array<string>;
694
+ };
695
+ /** The pinned library images (`img_…`). Replaces the list. */
696
+ graphics?: Array<{
697
+ image_id: string;
698
+ role: "logo" | "logo_light" | "logo_dark" | "mark" | "background" | "other";
699
+ label?: string;
700
+ }>;
701
+ /** On the default profile, also set the email branding's accent from these colors (no change on another profile, or without a usable accent). */
702
+ sync_visual?: boolean;
703
+ };
286
704
  type Campaign = {
287
705
  object: "campaign";
288
706
  id: string;
@@ -310,7 +728,7 @@ type Campaign = {
310
728
  sent_count: number;
311
729
  failed_count: number;
312
730
  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";
731
+ code: "user" | "hard_bounce_rate" | "complaint_rate" | "quality_review" | "provider_limit" | "failure_streak" | "sender_unavailable" | "template_unavailable" | "billing" | "not_drained" | "sending_restricted" | "workspace_suspended" | "sending_paused";
314
732
  message: string | null;
315
733
  metric: "hard_bounce_rate" | "complaint_rate" | null;
316
734
  value: number | null;
@@ -329,6 +747,13 @@ type Campaign = {
329
747
  created_at: string;
330
748
  updated_at: string;
331
749
  };
750
+ type CampaignAffectedRecipient = {
751
+ object: "campaign_affected_recipient";
752
+ email: string;
753
+ contact_id: string | null;
754
+ /** The address doesn't exist (`hard_bounce`), or the person marked it as spam. */
755
+ reason: "hard_bounce" | "complaint";
756
+ };
332
757
  type CampaignCreate = {
333
758
  name: string;
334
759
  template_id: string;
@@ -345,15 +770,83 @@ type CampaignCreate = {
345
770
  variable_fallbacks?: Record<string, string>;
346
771
  excluded_contact_ids?: Array<string>;
347
772
  };
773
+ type CampaignDuplicate = {
774
+ /** Name of the copy. Defaults to the source's name with " (copy)". */
775
+ name?: string;
776
+ };
777
+ type CampaignQualityRemoval = {
778
+ object: "campaign_quality_removal";
779
+ removed: number;
780
+ };
781
+ type CampaignRecipient = {
782
+ object: "campaign_recipient";
783
+ contact_id: string;
784
+ email: string | null;
785
+ name: string | null;
786
+ /** What a send now would do for this member, by the send's own rule. */
787
+ status: "sendable" | "missing_data" | "suppressed" | "excluded";
788
+ /** Why, in plain words; null when sendable. */
789
+ reason: string | null;
790
+ reason_code: "unsubscribed" | "no_email" | "suppression_list" | "topic_unsubscribed" | "excluded" | "missing_data" | null;
791
+ };
348
792
  type CampaignReschedule = {
349
793
  /** 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). */
350
794
  scheduled_at: string;
351
795
  };
796
+ type CampaignReviewRequest = {
797
+ object: "campaign_review_request";
798
+ requested: boolean;
799
+ already_requested: boolean;
800
+ };
352
801
  type CampaignSend = {
353
802
  scheduled_at?: string | null;
354
803
  };
804
+ type CampaignStats = {
805
+ object: "campaign_stats";
806
+ campaign_id: string;
807
+ /** Contacts the campaign was sent to (suppressed addresses never became recipients). */
808
+ recipients: number;
809
+ /** Recipients that didn't receive it, including ones that failed before a message existed. */
810
+ failed_recipients: number;
811
+ /** Contacts left out at send because their address is suppressed; null for campaigns sent before this was counted. */
812
+ suppressed: number | null;
813
+ counts: {
814
+ sent: number;
815
+ delivered: number;
816
+ /** Unique opens. */
817
+ opened: number;
818
+ /** Unique clicks. */
819
+ clicked: number;
820
+ unsubscribed: number;
821
+ bounced: number;
822
+ complained: number;
823
+ failed: number;
824
+ };
825
+ /** Percentages with one decimal (12.3 = 12.3%). null when there is nothing to measure yet, or when that tracking was off. */
826
+ rates: {
827
+ delivery: number | null;
828
+ open: number | null;
829
+ click: number | null;
830
+ unsubscribe: number | null;
831
+ bounce: number | null;
832
+ complaint: number | null;
833
+ };
834
+ tracking: {
835
+ open: boolean | null;
836
+ click: boolean | null;
837
+ };
838
+ /** Live rows, the counts frozen when old messages were cleaned up, or both. */
839
+ source: "live" | "snapshot" | "combined";
840
+ snapshotted_at: string | null;
841
+ };
355
842
  type CampaignUpdate = {
356
843
  archived?: boolean;
844
+ name?: string;
845
+ template_id?: string;
846
+ segment_id?: string;
847
+ from?: string;
848
+ subject?: string | null;
849
+ preview_text?: string | null;
357
850
  topic_id?: string | null;
358
851
  open_tracking?: boolean | null;
359
852
  click_tracking?: boolean | null;
@@ -365,6 +858,7 @@ type Contact = {
365
858
  object: "contact";
366
859
  id: string;
367
860
  email: string | null;
861
+ phone?: string | null;
368
862
  first_name: string | null;
369
863
  last_name: string | null;
370
864
  unsubscribed: boolean;
@@ -374,12 +868,54 @@ type Contact = {
374
868
  created_at: string;
375
869
  updated_at: string;
376
870
  };
871
+ type ContactActivity = {
872
+ object: "contact_activity";
873
+ /** An email (`email_…`) or text (`sms_…`) id; read it with its own get operation. */
874
+ message_id: string;
875
+ /** `email` or `sms`. */
876
+ channel: string;
877
+ direction: "outbound" | "inbound";
878
+ /** An email's subject, or the start of a text. */
879
+ subject: string | null;
880
+ /** The message's `status` as its own object reports it (`GET /email/{id}`, `GET /sms/{id}`). */
881
+ status: string;
882
+ campaign_id: string | null;
883
+ created_at: string;
884
+ sent_at: string | null;
885
+ /** Texts only: why it wasn't delivered, in plain words. */
886
+ error: string | null;
887
+ error_code: string | null;
888
+ };
889
+ type ContactAddress = {
890
+ object: "contact_address";
891
+ /** `email` for an email address, `sms` for a phone number. */
892
+ channel: string;
893
+ /** The email address, or the phone number in E.164. */
894
+ address: string;
895
+ /** The address sends use for this channel. */
896
+ primary: boolean;
897
+ /** `active`, or why it can't be used (e.g. `opted_out`, `bounced`). */
898
+ status: string;
899
+ /** ISO country of a phone number. */
900
+ country: string | null;
901
+ verified_at: string | null;
902
+ /** When SMS consent was recorded (see `/contacts/{id}/sms-consent`). */
903
+ consented_at: string | null;
904
+ consent_source: string | null;
905
+ consent_purpose: string | null;
906
+ /** When the carrier last refused a text to this number because it opted out at the carrier. Not a consent record. */
907
+ carrier_opt_out_at: string | null;
908
+ created_at: string;
909
+ };
377
910
  type ContactCreate = {
378
911
  email: string;
912
+ phone?: string | null;
379
913
  first_name?: string;
380
914
  last_name?: string;
381
915
  unsubscribed?: boolean;
382
916
  custom_fields?: Record<string, string | number | boolean | null>;
917
+ /** `true` updates the contact that already has this email instead of answering `409`: the fields you send are merged onto it (what you leave out is untouched, and `custom_fields` merges key by key), and the response is `200` rather than the `201` of a real create. Default `false`: a duplicate email is a `409`. It is not a way around an opt-out — `unsubscribed: false` on a suppressed address is still refused. */
918
+ update_if_exists?: boolean;
383
919
  };
384
920
  type ContactField = {
385
921
  object: "contact_field";
@@ -416,6 +952,7 @@ type ContactImport = {
416
952
  status: "pending" | "processing" | "completed" | "failed" | "canceled";
417
953
  total: number;
418
954
  imported: number;
955
+ updated: number;
419
956
  skipped: number;
420
957
  failed: number;
421
958
  invalid: Array<{
@@ -423,6 +960,7 @@ type ContactImport = {
423
960
  reason: string;
424
961
  }>;
425
962
  error: string | null;
963
+ update_existing: boolean;
426
964
  created_at: string;
427
965
  updated_at: string;
428
966
  };
@@ -432,9 +970,46 @@ type ContactImportCreate = {
432
970
  first_name?: string;
433
971
  last_name?: string;
434
972
  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. */
973
+ /** Create this contact already unsubscribed (`true`, or a string `true`/`1`/`yes`/`y`). Applies only to a contact the import creates: it never clears an opt-out, and an existing contact's subscription is left as it is, even with `update_existing`. */
436
974
  unsubscribed?: boolean | string;
437
975
  }>;
976
+ /** Update contacts that already exist instead of skipping them. A row whose email belongs to a contact sets the `first_name` and `last_name` it carries (a blank one is ignored) and merges its `custom_fields` key by key: keys the row leaves out keep their values. The contact's subscription is never changed (`unsubscribed` applies only to contacts the import creates). Counted in `updated`; a row that changes nothing is counted in `skipped`. Default `false`: existing contacts are skipped. */
977
+ update_existing?: boolean;
978
+ };
979
+ type ContactSegment = {
980
+ object: "contact_segment";
981
+ segment_id: string;
982
+ name: string;
983
+ /** A dynamic segment's members come from its filter; they can't be added or removed by hand. */
984
+ type: "static" | "dynamic";
985
+ /** Whether this segment's sends reach the contact (a static segment can be opted out of on its own). */
986
+ subscribed: boolean;
987
+ unsubscribed_at: string | null;
988
+ };
989
+ /** Set one custom field on many contacts: `key`, `value` and exactly one of `contact_ids`, `emails` or `segment_id`. */
990
+ type ContactSetField = {
991
+ /** The custom field's key (`plan`). It must exist: create it with POST /contact-fields first. */
992
+ key: string;
993
+ /** The value, typed against the field the way an import types it: a number field takes `42` or `"42"`, a boolean `true` / `"yes"`, a date an ISO 8601 date. `null` clears the field. */
994
+ value: string | number | boolean | null;
995
+ /** Default false: overwrite every value. True: set it only where the contact has no value of its own (the key is missing or null; a contact that shows the field's default has none). Not with `value: null`. */
996
+ only_empty?: boolean;
997
+ /** Contacts of this workspace (`con_…`), up to 1,000. */
998
+ contact_ids?: Array<string>;
999
+ /** Contacts of this workspace by email address, up to 1,000. */
1000
+ emails?: Array<string>;
1001
+ /** Every member of this segment (`seg_…`), however many. Also needs `segments:read`. */
1002
+ segment_id?: string;
1003
+ };
1004
+ type ContactsExport = {
1005
+ /** Free text: email, first and last name, and with 3+ digits the SMS number. */
1006
+ q?: string;
1007
+ status?: "subscribed" | "unsubscribed";
1008
+ phone?: "has" | "none";
1009
+ /** Members of this segment. Also needs `segments:read`. */
1010
+ segment_id?: string;
1011
+ /** With a static `segment_id`: its per-segment opt-out. */
1012
+ segment_subscription?: "subscribed" | "opted_out";
438
1013
  };
439
1014
  type ContactTopic = {
440
1015
  object: "contact_topic";
@@ -445,12 +1020,27 @@ type ContactTopic = {
445
1020
  status: "subscribed" | "unsubscribed";
446
1021
  source: "user" | "manual" | "import" | "api";
447
1022
  };
1023
+ type ContactTopicList = {
1024
+ object: "list";
1025
+ has_more: false;
1026
+ data: Array<ContactTopic>;
1027
+ };
448
1028
  type ContactTopicSet = {
449
1029
  topic_id?: string;
450
1030
  topic?: string;
451
1031
  subscribed: boolean;
452
1032
  };
1033
+ type ContactTopicsUpdate = {
1034
+ /** The preferences to change, up to 50, each topic once. Topics left out keep theirs. */
1035
+ topics: Array<{
1036
+ /** The topic (`top_…`). */
1037
+ topic_id: string;
1038
+ /** `true` to subscribe the contact, `false` to unsubscribe. */
1039
+ subscribed: boolean;
1040
+ }>;
1041
+ };
453
1042
  type ContactUpdate = {
1043
+ phone?: string | null;
454
1044
  first_name?: string | null;
455
1045
  last_name?: string | null;
456
1046
  unsubscribed?: boolean;
@@ -474,6 +1064,35 @@ type Domain = {
474
1064
  tracking_subdomain: string | null;
475
1065
  /** 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. */
476
1066
  tracking_verified_at: string | null;
1067
+ capabilities: {
1068
+ /** Always `enabled`: a domain can't be switched to receive-only. `status` says whether it can send now. */
1069
+ sending: "enabled";
1070
+ /** Whether mail sent to any address at this domain is received (catch-all). Turn it on with `PATCH /email/domains/{id}` once the domain is `verified`; `receiving` says how far setup is. */
1071
+ receiving: "enabled" | "disabled";
1072
+ };
1073
+ /** Receiving setup: the MX record to publish and the last check of it. */
1074
+ receiving: {
1075
+ /** `disabled`: receiving is off. `not_started`: on, but the MX record hasn't been checked yet (call `POST /email/domains/{id}/verify`). `pending`: checked, and either the MX record isn't published, another MX record has an equal or lower priority number, or mail isn't accepted yet. `verified`: mail to any address at the domain is received here. `held_elsewhere`: on, but another workspace has this domain verified, so its mail doesn't come to this one. */
1076
+ status: "disabled" | "not_started" | "pending" | "verified" | "held_elsewhere";
1077
+ /** The MX record to publish for receiving, at the domain's own name. Not part of `records`: publishing it routes ALL mail for the name to Unitpost, so if `checks.other_mx_found` is true the name already gets mail somewhere else (e.g. a mailbox provider). Use a subdomain for receiving instead. */
1078
+ record: {
1079
+ type: string;
1080
+ name: string;
1081
+ value: string;
1082
+ priority?: number;
1083
+ };
1084
+ /** The last MX check, or null before the first one. */
1085
+ checks: {
1086
+ /** Our MX record is published at the name. */
1087
+ mx_found: boolean;
1088
+ /** Our MX record has the lowest priority number at the name, so mail reaches Unitpost. */
1089
+ mx_lowest_priority: boolean;
1090
+ /** Another MX record (another mail provider) is published at the name. */
1091
+ other_mx_found: boolean;
1092
+ } | null;
1093
+ /** When the MX record was last checked. */
1094
+ checked_at: string | null;
1095
+ };
477
1096
  verified_at: string | null;
478
1097
  created_at: string;
479
1098
  updated_at: string;
@@ -522,6 +1141,13 @@ type DomainUpdate = {
522
1141
  click_tracking?: boolean | null;
523
1142
  tls?: "opportunistic" | "enforced";
524
1143
  tracking_subdomain?: string | null;
1144
+ /** Turn receiving on or off: `{ "receiving": "enabled" }` or `{ "receiving": "disabled" }`. */
1145
+ capabilities?: {
1146
+ /** Only `enabled` is accepted: sending can't be turned off for a domain. */
1147
+ sending?: "enabled";
1148
+ /** `enabled` receives mail sent to any address at the domain (it must be `verified`, else 409); `disabled` stops receiving (always allowed). Then publish `receiving.record` and call verify. */
1149
+ receiving?: "enabled" | "disabled";
1150
+ };
525
1151
  };
526
1152
  type Email$1 = {
527
1153
  object: "email";
@@ -541,15 +1167,36 @@ type Email$1 = {
541
1167
  canceled_at: string | null;
542
1168
  last_error: string | null;
543
1169
  created_at: string;
1170
+ /** Cc recipients, as sent. Empty when none. Only on `GET /email/{id}`. */
1171
+ cc?: Array<string>;
1172
+ /** Bcc recipients, as sent. Empty when none. Only on `GET /email/{id}`. */
1173
+ bcc?: Array<string>;
1174
+ /** Reply-To addresses, as sent. Empty when none. Only on `GET /email/{id}`. */
1175
+ reply_to?: Array<string>;
1176
+ /** The send's tags. Empty when none. Only on `GET /email/{id}`. */
1177
+ tags?: Array<{
1178
+ name: string;
1179
+ value: string;
1180
+ }>;
1181
+ };
1182
+ type EmailEvent = {
1183
+ object: "email_event";
1184
+ id: string;
1185
+ /** The event, as webhooks name it (`email.delivered`, `email.bounced`, ...). */
1186
+ type: string;
1187
+ /** When it happened. */
1188
+ created_at: string;
1189
+ /** The event's own detail, under the webhook's field names: `bounce` { type, sub_type, category, diagnostic_code[] } (`category`: hard_bounce, soft_bounce, provider_policy_reject or already_suppressed; only hard_bounce means the address can't receive mail), `complaint` { feedback_type }, `open` { user_agent }, `click` { link, user_agent }, `failed` { reason }, `suppressed` { recipients[], reasons[] { email, reason }, full }, `unsubscribe` { scope, source }. Empty for the rest. */
1190
+ data: Record<string, unknown>;
544
1191
  };
545
1192
  type EmailPatch = {
546
1193
  cancel?: true;
547
1194
  scheduled_at?: string;
548
1195
  };
549
1196
  type EmailStats = {
550
- /** The rolling window, in days. */
1197
+ /** The window, in days (a period's length, rounded up). */
551
1198
  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). */
1199
+ /** Non-null when the window reached past the plan's log retention: counting starts this many days back (data past the retention horizon is purged). */
553
1200
  clampedToRetentionDays?: number | null;
554
1201
  totals: {
555
1202
  sent: number;
@@ -559,22 +1206,196 @@ type EmailStats = {
559
1206
  bounced: number;
560
1207
  complained: number;
561
1208
  failed: number;
1209
+ /** Hard (permanent) bounces: the address doesn't exist or never accepts mail. Counted as the hard-bounce rate that can pause a campaign counts them. */
1210
+ bounced_permanent?: number;
1211
+ /** Soft bounces: everything else in `bounced` (a full mailbox, a message too large, an undetermined bounce). */
1212
+ bounced_transient?: number;
1213
+ /** Sends that skipped a suppressed recipient (`email.suppressed`). */
1214
+ suppressed?: number;
1215
+ /** Unsubscribes from a sent email (`email.unsubscribed`). */
1216
+ unsubscribed?: number;
562
1217
  };
563
- /** Percentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered. */
1218
+ /** Percentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered with that tracking on; unsubscribe vs delivered. */
564
1219
  rates: {
565
1220
  delivery: number;
566
1221
  open: number;
567
1222
  click: number;
568
1223
  bounce: number;
569
1224
  complaint: number;
1225
+ /** Unsubscribes vs delivered (vs sent when nothing was delivered), at most 100. */
1226
+ unsubscribe?: number;
570
1227
  };
1228
+ /** The sending domain counted (`domain_id`), or null for every domain. */
1229
+ domain_id?: string | null;
1230
+ /** Start of the window counted (UTC). */
1231
+ from?: string;
1232
+ /** End of the window counted, exclusive (UTC). */
1233
+ to?: string;
1234
+ /** The send volume per `grain` bucket over `from`–`to`, as the dashboard home charts it; null without `grain`. */
1235
+ series?: {
1236
+ grain: "5m" | "1h" | "1d";
1237
+ time_zone: string;
1238
+ /** Buckets with sends, oldest first; a bucket with none is left out. */
1239
+ buckets: Array<{
1240
+ /** The bucket's start in `time_zone` wall time: `YYYY-MM-DD` for `1d`, `YYYY-MM-DDTHH:MM` for `1h` and `5m`. */
1241
+ bucket: string;
1242
+ /** Emails created in the bucket (sent or attempted). */
1243
+ sends: number;
1244
+ }>;
1245
+ } | null;
571
1246
  };
572
- type Error$1 = {
573
- error: {
574
- /** Stable machine-readable error code (branch on this, not the message). */
575
- code: string;
576
- /** Human-readable summary. For validation errors it's path-prefixed (e.g. "template.variables.first_name: …"). */
577
- message: string;
1247
+ type EmailThread = {
1248
+ object: "email_thread";
1249
+ id: string;
1250
+ subject: string | null;
1251
+ last_message_at: string;
1252
+ last_direction: "inbound" | "outbound";
1253
+ /** The newest received message's opening words; null when the newest message is one you sent. */
1254
+ snippet: string | null;
1255
+ /** The other party: the newest received message's sender. */
1256
+ from: string | null;
1257
+ from_name: string | null;
1258
+ /** Your address it came in on (the newest received message's To). */
1259
+ inbox_address: string | null;
1260
+ message_count: number;
1261
+ has_attachments: boolean;
1262
+ /** A received message was flagged spam or virus, or failed SPF, DKIM or DMARC. */
1263
+ flagged: boolean;
1264
+ /** A reply or forward was sent from this conversation. */
1265
+ replied: boolean;
1266
+ };
1267
+ type EmailThreadDeleted = {
1268
+ object: "email_thread";
1269
+ id: string;
1270
+ deleted: true;
1271
+ /** Received messages erased. */
1272
+ deleted_messages: number;
1273
+ };
1274
+ type EmailThreadDetail = {
1275
+ object: "email_thread";
1276
+ id: string;
1277
+ subject: string | null;
1278
+ last_message_at: string;
1279
+ /** The other party; null when the conversation has no received mail. */
1280
+ sender: {
1281
+ address: string;
1282
+ } | null;
1283
+ /** Older messages exist than the ones in `messages`; read them with `before` = `older_cursor`. */
1284
+ older_hidden: boolean;
1285
+ /** Pass as `before` to read the messages before these (the next page back). Null when nothing older remains. */
1286
+ older_cursor: string | null;
1287
+ /** A reply from here carries the "Sent with Unitpost" line (your plan decides). */
1288
+ sent_with_unitpost: boolean;
1289
+ /** Oldest first. What you sent is metadata only: no body. */
1290
+ messages: Array<{
1291
+ object: "received_email";
1292
+ direction: "inbound";
1293
+ id: string;
1294
+ received_at: string;
1295
+ from: string;
1296
+ from_name: string | null;
1297
+ to: Array<string>;
1298
+ cc: Array<string>;
1299
+ /** Reply-To addresses; answer these before `from` when present. */
1300
+ reply_to: Array<string>;
1301
+ subject: string | null;
1302
+ message_id: string | null;
1303
+ /** Null on a copy of one of your own sends (`sent_by_us`): sent bodies aren't on the API. */
1304
+ text: string | null;
1305
+ /** Inline (`cid:`) images point to short-lived links. Null on a copy of your own send. */
1306
+ html: string | null;
1307
+ verdicts: {
1308
+ spam: string | null;
1309
+ virus: string | null;
1310
+ spf: string | null;
1311
+ dkim: string | null;
1312
+ dmarc: string | null;
1313
+ };
1314
+ size: number;
1315
+ attachments: Array<{
1316
+ object: "received_attachment";
1317
+ id: string;
1318
+ filename: string | null;
1319
+ content_type: string | null;
1320
+ content_disposition: string | null;
1321
+ content_id: string | null;
1322
+ size: number;
1323
+ }>;
1324
+ /** A copy of one of your own sends that came back in to your receiving domain. */
1325
+ sent_by_us: boolean;
1326
+ /** It repeats a message the conversation already shows; the dashboard folds it away. */
1327
+ duplicate: boolean;
1328
+ } | {
1329
+ object: "email";
1330
+ direction: "outbound";
1331
+ id: string;
1332
+ created_at: string;
1333
+ from: string;
1334
+ to: Array<string>;
1335
+ cc: Array<string>;
1336
+ bcc: Array<string>;
1337
+ subject: string;
1338
+ status: "scheduled" | "queued" | "sent" | "delivered" | "bounced" | "complained" | "canceled" | "failed";
1339
+ /** Sent from this conversation; null for an earlier send a reply pulled in. */
1340
+ kind: "reply" | "forward" | null;
1341
+ sent_at: string | null;
1342
+ delivered_at: string | null;
1343
+ opened_at: string | null;
1344
+ clicked_at: string | null;
1345
+ attachments: Array<{
1346
+ filename: string;
1347
+ content_type: string | null;
1348
+ size: number;
1349
+ }>;
1350
+ }>;
1351
+ };
1352
+ type EmailThreadReplyRequest = {
1353
+ /** The received message (`inb_…`) in this conversation to answer or forward. */
1354
+ received_email_id: string;
1355
+ /** `reply` (the sender), `reply_all` (everyone on it), or `forward` (to someone new, with the original's attachments you pick). */
1356
+ mode: "reply" | "reply_all" | "forward";
1357
+ /** One of your sending addresses, e.g. the address the message came in on. */
1358
+ from: string;
1359
+ /** For a reply: the message's `reply_to`, else its `from`. Up to 50. */
1360
+ to: string | Array<string>;
1361
+ /** Copy recipients, up to 50. */
1362
+ cc?: string | Array<string>;
1363
+ /** Blind-copy recipients, up to 50. */
1364
+ bcc?: string | Array<string>;
1365
+ /** Usually `Re: <their subject>` (or `Fwd:`). */
1366
+ subject: string;
1367
+ /** Your words, plain text. The original is quoted under them. */
1368
+ text?: string;
1369
+ /** Your words, HTML. The original is quoted under them. */
1370
+ html?: string;
1371
+ /** Quote the original under a reply (default true; a forward always carries it). A copy of one of your own sends (`sent_by_us`) is never quoted: left out, it defaults to false there, and `true` is a `403`. */
1372
+ include_quote?: boolean;
1373
+ /** Forward only: the original's attachments to carry over (their `id`s). */
1374
+ forward_attachment_ids?: Array<string>;
1375
+ /** Files to attach: `content` (base64) or `path` (an https URL), up to 20 with the carried-over ones. */
1376
+ attachments?: Array<{
1377
+ filename: string;
1378
+ content?: string;
1379
+ path?: string;
1380
+ content_type?: string;
1381
+ content_id?: string;
1382
+ }>;
1383
+ /** Open and click tracking for this message; omitted = the sending domain's default. */
1384
+ tracking?: boolean;
1385
+ };
1386
+ type EmailThreadReplyResult = {
1387
+ object: "email";
1388
+ /** The sent email (`email_…`); read it with `GET /email/{id}`. */
1389
+ id: string;
1390
+ status: "queued" | "scheduled";
1391
+ thread_id: string | null;
1392
+ };
1393
+ type Error$1 = {
1394
+ error: {
1395
+ /** Stable machine-readable error code (branch on this, not the message). */
1396
+ code: string;
1397
+ /** Human-readable summary. For validation errors it's path-prefixed (e.g. "template.variables.first_name: …"). */
1398
+ message: string;
578
1399
  /** 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. */
579
1400
  details?: Array<{
580
1401
  /** Dotted path to the field, e.g. "template.variables.first_name" (empty for a whole-body problem). */
@@ -583,8 +1404,64 @@ type Error$1 = {
583
1404
  code?: string;
584
1405
  message: string;
585
1406
  }>;
1407
+ /** A page that explains this error and what to do, when there is one (today: `sending_paused`). Additive; absent otherwise. */
1408
+ doc_url?: string;
586
1409
  };
587
1410
  };
1411
+ type File = {
1412
+ object: "file";
1413
+ id: string;
1414
+ /** What the file is for: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB). */
1415
+ purpose: "sms_opt_in_evidence" | "sms_document" | "image";
1416
+ /** `ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why). */
1417
+ status: "awaiting_upload" | "ready" | "failed";
1418
+ filename: string;
1419
+ /** The type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared. */
1420
+ content_type: string;
1421
+ size_bytes: number;
1422
+ /** The hex SHA-256 of the bytes once `ready`. */
1423
+ sha256: string | null;
1424
+ failure_reason: string | null;
1425
+ /** An upload session's PUT, in the create response only (null otherwise). */
1426
+ upload: {
1427
+ /** PUT the bytes here, with exactly `headers`, before `expires_at`: `curl -T <file> -H "Content-Type: …" "<url>"`. The URL is a credential for this one file: don't share or log it. */
1428
+ url: string;
1429
+ method: "PUT";
1430
+ /** Send these headers with the PUT. The length and type are signed: any other size or type is refused by storage. */
1431
+ headers: Record<string, string>;
1432
+ /** The URL stops working at this time (15 minutes after the file is created). */
1433
+ expires_at: string;
1434
+ } | null;
1435
+ created_at: string;
1436
+ /** The file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy. */
1437
+ expires_at: string;
1438
+ };
1439
+ type FileCreate = {
1440
+ /** What the file is for, which sets what it may be: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB). The bytes decide the type, never the name or the label. */
1441
+ purpose: "sms_opt_in_evidence" | "sms_document" | "image";
1442
+ /** A public https address to fetch the file from (no redirects, no private addresses, 12 seconds). One of `url`, `data`, or neither (an upload session). */
1443
+ url?: string;
1444
+ /** The bytes, base64 (no `data:` prefix), with `content_type`. Base64 grows bytes by a third, and a request body may be up to 30 MB. A `url` or an upload session carries no bytes in the request. */
1445
+ data?: string;
1446
+ /** Required with `data` and for an upload session (it is signed into the PUT); refused with `url`. */
1447
+ content_type?: "image/png" | "application/pdf" | "image/jpeg" | "image/gif" | "image/webp";
1448
+ /** An upload session only: the exact size of the file you'll PUT, in bytes (signed into the PUT). Within the purpose's maximum. */
1449
+ size_bytes?: number;
1450
+ /** A name for the file (shown on what uses it). Defaults to the URL's last path part, or `file.<ext>`. */
1451
+ filename?: string;
1452
+ };
1453
+ type ImageUpload = {
1454
+ /** A public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`. */
1455
+ url?: string;
1456
+ /** The image bytes, base64 (no `data:` prefix), up to 5 MB of image. Base64 grows bytes by a third, and a request body may be up to 30 MB. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`. */
1457
+ data?: string;
1458
+ /** A file made with `POST /files` and purpose `image` (`file_…`): how an agent hands over a local image without base64 (an upload session), or an image up to 5 MB. Checked by its bytes when it was made, and again here. */
1459
+ file_id?: string;
1460
+ /** Required with `data`; refused with `url` and `file_id` (the server reads the type from the bytes). */
1461
+ content_type?: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
1462
+ /** Shown in the library. Defaults to the URL's file name, or `image`. */
1463
+ filename?: string;
1464
+ };
588
1465
  type Job = {
589
1466
  object: "job";
590
1467
  id: string;
@@ -597,6 +1474,285 @@ type Job = {
597
1474
  created_at: string;
598
1475
  completed_at: string | null;
599
1476
  };
1477
+ type JobDownload = {
1478
+ object: "job_download";
1479
+ job_id: string;
1480
+ /** A signed URL to the file; it expires in 5 minutes. */
1481
+ url: string;
1482
+ filename: string;
1483
+ expires_at: string;
1484
+ };
1485
+ type LibraryImage = {
1486
+ object: "library_image";
1487
+ id: string;
1488
+ /** Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there. */
1489
+ path: string;
1490
+ /** The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost. */
1491
+ url: string;
1492
+ filename: string;
1493
+ content_type: string;
1494
+ /** Bytes. */
1495
+ size: number;
1496
+ width: number | null;
1497
+ height: number | null;
1498
+ /** The alt text suggested when the image is inserted. */
1499
+ alt: string | null;
1500
+ created_at: string;
1501
+ updated_at: string;
1502
+ };
1503
+ type LibraryImageCreate = {
1504
+ /** A public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`. */
1505
+ url?: string;
1506
+ /** The image bytes, base64 (no `data:` prefix), up to 5 MB of image. Base64 grows bytes by a third, and a request body may be up to 30 MB. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`. */
1507
+ data?: string;
1508
+ /** A file made with `POST /files` and purpose `image` (`file_…`): how an agent hands over a local image without base64 (an upload session), or an image up to 5 MB. Checked by its bytes when it was made, and again here. */
1509
+ file_id?: string;
1510
+ /** Required with `data`; refused with `url` and `file_id` (the server reads the type from the bytes). */
1511
+ content_type?: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
1512
+ /** Shown in the library. Defaults to the URL's file name, or `image`. */
1513
+ filename?: string;
1514
+ /** Alt text suggested when the image is inserted. */
1515
+ alt?: string | null;
1516
+ };
1517
+ type LibraryImageUpdate = {
1518
+ /** The new alt text; `null` or `""` clears it. */
1519
+ alt: string | null;
1520
+ };
1521
+ type MintedWorkspaceKey = {
1522
+ object: "api_key";
1523
+ /** `key_…` */
1524
+ id: string;
1525
+ /** The secret, shown once. */
1526
+ key: string;
1527
+ prefix: string;
1528
+ scope: "full" | "sending" | "read_only";
1529
+ capabilities: Array<string>;
1530
+ workspace_id: string;
1531
+ };
1532
+ type OrganizationPlanQuote = {
1533
+ object: "plan_quote";
1534
+ /** `pq_…` */
1535
+ id: string;
1536
+ /** `ws_…` */
1537
+ workspace_id: string;
1538
+ /** The workspace's `external_id` when quoted. */
1539
+ external_id: string | null;
1540
+ /** `open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it. */
1541
+ status: "open" | "confirmed" | "expired";
1542
+ /** `upgrade`: now, charged in full, the period restarts, unused allowance carries over. `downgrade`: at the period end. `lateral`: now. `start`: from free, now. `cancel`: to free, at the period end. `noop`: the plan stays as it is; with a `pending_change`, the confirm cancels it (nothing charged). */
1543
+ kind: "upgrade" | "downgrade" | "lateral" | "start" | "cancel" | "noop";
1544
+ current: OrganizationPlanStop;
1545
+ target: OrganizationPlanStop;
1546
+ /** Charged to the organization's card on confirm: the new monthly price on an upgrade or a start, else 0 (before any discount). An upgrade restarts the billing period, so usage beyond the old plan's allowance this period, if any, is billed on the same invoice and is not in this number. */
1547
+ due_now_cents: number;
1548
+ /** Unused allowance carried into the new period (an upgrade only). */
1549
+ carryover_cents: number;
1550
+ effective: "now" | "period_end";
1551
+ /** When the change takes effect (once confirmed, when it did or will). Null for a `noop`, except one on a plan already set to end, where it is when the plan ends. */
1552
+ effective_at: string | null;
1553
+ expires_at: string;
1554
+ created_at: string;
1555
+ confirmed_at: string | null;
1556
+ /** After a confirm from free (`start`): the organization's card was declined or asked for authentication. The plan starts when this invoice is paid; unpaid, it lapses after about 23 hours, nothing is charged and the workspace stays on Free. Null otherwise. */
1557
+ hosted_invoice_url: string | null;
1558
+ /** A free workspace that pays for itself, started on a paid plan billed to the organization: the confirm moves it onto the organization's billing first. */
1559
+ moves_to_organization: boolean;
1560
+ /** A downgrade already scheduled for the end of the period when the quote was made: the plan and stop it moves to, and when. Null when none is scheduled. With one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan; an upgrade or a lateral move replaces it, another downgrade replaces it, and a cancel to free ends the plan instead. */
1561
+ pending_change: {
1562
+ plan: string;
1563
+ tier_index: number;
1564
+ effective_at: string | null;
1565
+ } | null;
1566
+ /** On create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again. */
1567
+ confirm_token?: string;
1568
+ };
1569
+ type OrganizationPlanQuoteConfirm = {
1570
+ /** The quote's `confirm_token` (`pqct_…`) from its create response. Single use. */
1571
+ confirm_token: string;
1572
+ };
1573
+ type OrganizationPlanQuoteCreate = {
1574
+ /** `free`, or a paid plan the Owner's API rules allow. */
1575
+ plan: string;
1576
+ /** The stop on the paid plan's price ladder (default 0, its lowest price). Ignored for `free`. */
1577
+ tier_index?: number;
1578
+ };
1579
+ type OrganizationPlanStop = {
1580
+ /** `free` or the paid plan's key. */
1581
+ plan: string;
1582
+ /** The stop on the plan's ladder; null for free or a custom plan. */
1583
+ tier_index: number | null;
1584
+ /** The monthly price; 0 for free, null for a custom plan. */
1585
+ price_monthly_cents: number | null;
1586
+ };
1587
+ type OrganizationSharedPlan$1 = {
1588
+ object: "shared_plan";
1589
+ /** Unitpost's team turned the shared plan on for the organization; it is never on by default. */
1590
+ approved: boolean;
1591
+ /** When an Owner or Billing member asked for it (Organization → Billing); null if nobody has. */
1592
+ requested_at: string | null;
1593
+ /** `none` until a plan is bought; then the plan's status. `past_due` keeps its workspaces but takes no new ones; `canceled` once it ended (its workspaces left it). */
1594
+ status: "none" | "active" | "trialing" | "past_due" | "paused" | "canceled";
1595
+ /** The plan's key (`pro` is Starter, `scale` is Growth); null with none. */
1596
+ plan: string | null;
1597
+ /** The stop on the plan's price ladder. */
1598
+ tier_index: number | null;
1599
+ /** The stop's list price a month, before any discount or promotion code. */
1600
+ price_monthly_cents: number | null;
1601
+ period_start: string | null;
1602
+ period_end: string | null;
1603
+ /** Set to end then (the period end); null while it renews. */
1604
+ cancel_at: string | null;
1605
+ /** The allowance its workspaces share each period, in cents of sending (email, SMS, WhatsApp). */
1606
+ allowance_cents: number | null;
1607
+ /** What its workspaces drew this period, including workspaces that left during it. 0 with no plan. */
1608
+ used_cents: number;
1609
+ /** The part of `used_cents` beyond the allowance, billed at the plan's overage rate. */
1610
+ overage_cents: number;
1611
+ /** The overage band: how far past the allowance its workspaces may send in a period. Null: no band. */
1612
+ overage_cap_cents: number | null;
1613
+ /** The allowance and the band are used up (only the allowance while `overage_frozen`): every workspace on the plan stops sending until the period renews or the plan is upgraded. */
1614
+ paused: boolean;
1615
+ /** Unitpost's team paused overage on the plan (a disputed charge): sending stops at the allowance. */
1616
+ overage_frozen: boolean;
1617
+ /** How many workspaces the plan covers (Starter 3, Growth 10, unless Unitpost's team set another number). Before a plan is bought, the number set for the organization, or null for the plan's own. */
1618
+ workspace_limit: number | null;
1619
+ /** How many workspaces are on it now. */
1620
+ workspaces: number;
1621
+ };
1622
+ type OrganizationSharedPlanRemoval = {
1623
+ object: "shared_plan_removal";
1624
+ /** `ws_…` */
1625
+ workspace_id: string;
1626
+ external_id: string | null;
1627
+ /** False when it wasn't on the shared plan: nothing changed. */
1628
+ left: boolean;
1629
+ /** `free`: it is on Free (its Owner's one free workspace). `needs_plan`: it sends again once a plan is bought for it. Null when `left` is false. */
1630
+ drops_to: "free" | "needs_plan" | null;
1631
+ };
1632
+ type OrganizationSharedPlanWorkspace = {
1633
+ object: "shared_plan_workspace";
1634
+ /** `ws_…` */
1635
+ workspace_id: string;
1636
+ /** Your own id for it, if you gave one. */
1637
+ external_id: string | null;
1638
+ name: string;
1639
+ /** What it may draw from the shared plan each period, allowance and overage together. Null: no cap. */
1640
+ cap_cents: number | null;
1641
+ joined_at: string;
1642
+ /** What it drew this period, counted against its cap. */
1643
+ used_cents: number;
1644
+ };
1645
+ type OrganizationSharedPlanWorkspaceAdd = {
1646
+ /** Its cap, in cents a period (0 stops it drawing, null: none). Left out: none on a join, unchanged when it is already on the plan. */
1647
+ cap_cents?: number | null;
1648
+ };
1649
+ type OrganizationSharedPlanWorkspaceUpdate = {
1650
+ /** Its cap, in cents a period: 0 stops it drawing, null removes the cap. */
1651
+ cap_cents: number | null;
1652
+ };
1653
+ type OrganizationWebhookDelivery = WebhookDelivery & {
1654
+ /** The workspace the event happened in (`ws_…`). */
1655
+ workspace_id: string;
1656
+ /** That workspace's `external_id` now (the delivered envelope carried the one at delivery time); null when it has none. */
1657
+ external_id: string | null;
1658
+ };
1659
+ type OrganizationWorkspace = {
1660
+ object: "workspace";
1661
+ /** `ws_…` */
1662
+ id: string;
1663
+ name: string;
1664
+ slug: string;
1665
+ /** Your own id for it, unique in the organization. */
1666
+ external_id: string | null;
1667
+ /** `free`, or the paid plan's key. */
1668
+ plan: string;
1669
+ paid_by: "workspace" | "organization";
1670
+ /** No free allowance: the Owner already has a free workspace, so it sends once a plan is bought. */
1671
+ requires_paid_plan: boolean;
1672
+ /** The workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`. */
1673
+ sms_purchases_cap_cents?: number | null;
1674
+ closed_at: string | null;
1675
+ /** Once closed: the last moment it can be restored, 30 days after `closed_at`. Null while open. */
1676
+ restorable_until: string | null;
1677
+ /** Once closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open. */
1678
+ deletes_at?: string | null;
1679
+ /** On the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`. */
1680
+ shared_plan?: {
1681
+ cap_cents: number | null;
1682
+ joined_at: string;
1683
+ } | null;
1684
+ created_at: string;
1685
+ /** On create only: the card asked for authentication; paying here starts the plan. */
1686
+ hosted_invoice_url?: string | null;
1687
+ };
1688
+ type OrganizationWorkspaceCreate = {
1689
+ name: string;
1690
+ external_id?: string;
1691
+ /** Default: the Owner's default plan, else `free`. A paid plan is billed to the organization's card at once. */
1692
+ plan?: string;
1693
+ /** The paid plan's tier (default 0). Its price must be within the Owner's largest plan price (Organization → API); with none set, only tier 0. */
1694
+ tier_index?: number;
1695
+ /** The monthly SMS purchases cap, in cents, at most the Owner's largest. Above 0 only on a paid plan or the shared plan (billed to the organization). Left out: the Owner's default there, else none; null: none. */
1696
+ sms_purchases_cap_cents?: number | null;
1697
+ /** Make it straight onto the organization's shared plan: it draws on the shared allowance, has no plan of its own and is paid by the organization's card. Needs `organizations:billing`; not with `plan` or `tier_index`. Set a cap afterwards with `PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`. */
1698
+ shared_plan?: boolean;
1699
+ };
1700
+ type OrganizationWorkspaceUpdate = {
1701
+ name?: string;
1702
+ external_id?: string | null;
1703
+ /** The monthly SMS purchases cap, in cents; null clears it. Above 0 only on a workspace the organization pays for, and at most the Owner's largest. */
1704
+ sms_purchases_cap_cents?: number | null;
1705
+ };
1706
+ type OrganizationWorkspaceUsage = {
1707
+ object: "workspace_usage";
1708
+ workspace_id: string;
1709
+ external_id: string | null;
1710
+ name: string;
1711
+ closed_at: string | null;
1712
+ plan: string;
1713
+ period_start: string | null;
1714
+ period_end: string | null;
1715
+ emails: {
1716
+ sent: number;
1717
+ };
1718
+ spend: {
1719
+ total_cents: number;
1720
+ email_cents: number;
1721
+ sms_cents: number;
1722
+ sms_carrier_fees_cents: number;
1723
+ other_cents: number;
1724
+ refunds_cents: number;
1725
+ included_cents: number;
1726
+ purchased_credit_cents: number;
1727
+ overage_cents: number;
1728
+ credits_added_cents: number;
1729
+ };
1730
+ sms: {
1731
+ messages: number;
1732
+ segments: number;
1733
+ send_cents: number;
1734
+ received: number;
1735
+ received_cents: number;
1736
+ monthly_fees_cents: number;
1737
+ one_time_fees_cents: number;
1738
+ refunds_cents: number;
1739
+ countries: Array<{
1740
+ country: string;
1741
+ messages: number;
1742
+ segments: number;
1743
+ price_per_segment_cents: number | null;
1744
+ price_per_segment_cents_decimal: string | null;
1745
+ cost_cents: number;
1746
+ }>;
1747
+ received_countries: Array<{
1748
+ country: string;
1749
+ received: number;
1750
+ segments: number;
1751
+ cost_cents: number;
1752
+ }>;
1753
+ };
1754
+ on_shared_plan?: boolean;
1755
+ };
600
1756
  type ReceivedAttachmentUrl = {
601
1757
  object: "received_attachment_url";
602
1758
  /** A signed, expiring URL to download the attachment bytes. */
@@ -633,6 +1789,23 @@ type ReceivedEmail = {
633
1789
  }>;
634
1790
  received_at: string;
635
1791
  created_at: string;
1792
+ /** The conversation (`thr_…`); null until the message is threaded. */
1793
+ thread_id?: string | null;
1794
+ /** Reply-To addresses: answer these before `from` when present. */
1795
+ reply_to?: Array<string>;
1796
+ /** The headers we keep, by lower-case name: `date`, `in-reply-to`, `references`, `reply-to`, `return-path`, `list-unsubscribe` (when present). */
1797
+ headers?: Record<string, string>;
1798
+ /** A copy of one of your own sends that came back to your receiving domain. Its `text` and `html` are null: sent bodies aren't on the API (they can carry a sign-in or reset link). */
1799
+ sent_by_us?: boolean;
1800
+ };
1801
+ type ReceivedEmailRaw = {
1802
+ object: "received_email_raw";
1803
+ /** A signed, expiring URL to download the original message (.eml, RFC 5322). */
1804
+ url: string;
1805
+ /** ISO 8601 expiry of the signed URL (~5 minutes out). */
1806
+ expires_at: string;
1807
+ /** The message's size in bytes. */
1808
+ size_bytes: number;
636
1809
  };
637
1810
  type ReceivedEmailSummary = {
638
1811
  object: "received_email";
@@ -652,8 +1825,30 @@ type ReceivedEmailSummary = {
652
1825
  size: number;
653
1826
  received_at: string;
654
1827
  created_at: string;
1828
+ /** The conversation (`thr_…`); null until the message is threaded. */
1829
+ thread_id?: string | null;
1830
+ /** Reply-To addresses: answer these before `from` when present. */
1831
+ reply_to?: Array<string>;
655
1832
  attachment_count: number;
656
1833
  };
1834
+ type RequestLog = {
1835
+ object: "request_log";
1836
+ /** The log row (`rlog_…`); page with it as `after` / `before`. */
1837
+ id: string;
1838
+ /** The `x-request-id` the response carried: quote it to support. */
1839
+ request_id: string | null;
1840
+ method: string;
1841
+ /** The path called, without the host and `/api/v1` (e.g. `/email/email_…`); no query string. An email address or phone number in it reads `{email}` / `{phone}`. */
1842
+ path: string;
1843
+ /** The HTTP status answered. */
1844
+ status: number;
1845
+ /** How long the request took to answer. */
1846
+ duration_ms: number | null;
1847
+ /** The API key that called (`key_…`); null for an MCP or CLI sign-in, or a key since deleted. */
1848
+ api_key_id: string | null;
1849
+ user_agent: string | null;
1850
+ created_at: string;
1851
+ };
657
1852
  type Segment = {
658
1853
  object: "segment";
659
1854
  id: string;
@@ -678,10 +1873,72 @@ type SegmentMember = {
678
1873
  subscribed: boolean;
679
1874
  unsubscribed_at: string | null;
680
1875
  };
1876
+ /** Add one contact. */
681
1877
  type SegmentMemberAdd = {
1878
+ /** The contact: its id (`con_…`) or email. */
682
1879
  contact: string;
1880
+ /** The new member's per-segment subscription (default true). A contact that is already a member keeps its own. */
1881
+ subscribed?: boolean;
1882
+ };
1883
+ /** Who to add: exactly one of `contact`, `contact_ids` or `emails`. */
1884
+ type SegmentMemberAddBody = {
1885
+ /** One contact: its id (`con_…`) or email. */
1886
+ contact?: string;
1887
+ /** Many contacts of this workspace by id (`con_…`), up to 1,000. */
1888
+ contact_ids?: Array<string>;
1889
+ /** Many contacts of this workspace by email address, up to 1,000. */
1890
+ emails?: Array<string>;
1891
+ /** A new member's per-segment subscription (default true). A contact that is already a member keeps its own. */
1892
+ subscribed?: boolean;
1893
+ };
1894
+ /** Add many contacts: exactly one of `contact_ids` or `emails`. */
1895
+ type SegmentMembersAdd = {
1896
+ /** Many contacts of this workspace by id (`con_…`), up to 1,000. */
1897
+ contact_ids?: Array<string>;
1898
+ /** Many contacts of this workspace by email address, up to 1,000. */
1899
+ emails?: Array<string>;
1900
+ /** New members' per-segment subscription (default true). A contact that is already a member keeps its own. */
683
1901
  subscribed?: boolean;
684
1902
  };
1903
+ type SegmentMembersAdded = {
1904
+ object: "list";
1905
+ /** Each listed contact's membership, in the order sent (a contact listed twice appears once). */
1906
+ data: Array<{
1907
+ object: "segment_member";
1908
+ contact_id: string;
1909
+ subscribed: boolean;
1910
+ unsubscribed_at: string | null;
1911
+ }>;
1912
+ has_more: false;
1913
+ /** How many of them this call added; the others were already members and kept their state. */
1914
+ added: number;
1915
+ };
1916
+ type SegmentMemberUpdate = {
1917
+ /** `false` opts the contact out of this segment's sends without removing it; `true` opts it back in. */
1918
+ subscribed: boolean;
1919
+ };
1920
+ type SegmentPreview = {
1921
+ object: "segment_preview";
1922
+ /** The saved segment, or null for an unsaved filter. */
1923
+ segment_id: string | null;
1924
+ /** Whether the saved segment is archived (a campaign can't target it); null for an unsaved filter. */
1925
+ archived: boolean | null;
1926
+ /** Contacts that match (or are members). */
1927
+ member_count: number;
1928
+ /** Of those, the ones a campaign would mail: not unsubscribed. 0 means an empty send. */
1929
+ subscribed_count: number;
1930
+ /** Up to 3 of the subscribed set. Empty without `contacts:read`. */
1931
+ sample: Array<{
1932
+ id: string;
1933
+ email: string | null;
1934
+ first_name: string | null;
1935
+ last_name: string | null;
1936
+ }>;
1937
+ };
1938
+ type SegmentPreviewRequest = {
1939
+ /** The filter to count, as a dynamic segment's `filter`. 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. */
1940
+ filter: unknown;
1941
+ };
685
1942
  type SegmentUpdate = {
686
1943
  name?: string;
687
1944
  description?: string | null;
@@ -725,6 +1982,30 @@ type SendEmail = {
725
1982
  /** 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`. */
726
1983
  scheduled_at?: string;
727
1984
  };
1985
+ type Sender = {
1986
+ object: "sender";
1987
+ id: string;
1988
+ domain_id: string;
1989
+ /** `local_part@domain`. */
1990
+ address: string;
1991
+ display_name: string | null;
1992
+ /** The From value to send with: `Display Name <address>`, or the address alone. */
1993
+ from: string;
1994
+ /** `manual` (saved by someone) or `api` (seen on a send through the API). */
1995
+ source: "manual" | "api";
1996
+ created_at: string;
1997
+ updated_at: string;
1998
+ };
1999
+ type SenderCreate = {
2000
+ /** The mailbox to save, on one of your domains (e.g. `hello@mail.acme.com`). Its domain may still be verifying. */
2001
+ address: string;
2002
+ /** Shown as the sender's name (`Acme Support <hello@…>`). */
2003
+ display_name?: string | null;
2004
+ };
2005
+ type SenderUpdate = {
2006
+ /** The new display name; `null` or `""` clears it. */
2007
+ display_name: string | null;
2008
+ };
728
2009
  type SendResult = {
729
2010
  id: string;
730
2011
  status: "queued" | "scheduled";
@@ -739,7 +2020,7 @@ type Sms$1 = {
739
2020
  status: "queued" | "scheduled" | "sending" | "sent" | "delivered" | "failed" | "suppressed" | "canceled" | "received";
740
2021
  type: "transactional" | "marketing";
741
2022
  body: string | null;
742
- /** Billed units. Outbound: segments. Inbound: 1 when the received text was charged (1¢ in the US and Canada), else 0. */
2023
+ /** Billed units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0. */
743
2024
  segments: number;
744
2025
  /** Inbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise. */
745
2026
  in_reply_to: string | null;
@@ -747,9 +2028,10 @@ type Sms$1 = {
747
2028
  received_at: string | null;
748
2029
  /** 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
2030
  looks_like_opt_out: boolean;
2031
+ /** The other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known. */
750
2032
  country: string | null;
751
2033
  scheduled_at: string | null;
752
- /** Legacy free-text error. Prefer `error.code`. */
2034
+ /** The sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text. */
753
2035
  last_error: string | null;
754
2036
  /** Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise. */
755
2037
  error: {
@@ -758,6 +2040,36 @@ type Sms$1 = {
758
2040
  /** Human-readable sentence for `code`. */
759
2041
  message: string;
760
2042
  } | null;
2043
+ /** Set on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook. */
2044
+ failure_code?: "quota_exceeded" | "overage_cap_exceeded" | "subscription_inactive" | "sms_not_in_plan" | "unsupported_country" | "workspace_suspended" | "sms_brand_blocked" | "sender_not_active" | "sender_registration_incomplete" | "sender_action_required" | "sender_use_case_mismatch" | "quiet_hours_unsatisfiable" | "channel_unavailable" | "delivery_exhausted" | "provider_rejected" | "carrier_undelivered" | "suspected_pumping" | null;
2045
+ created_at: string;
2046
+ /** The contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact. */
2047
+ contact_id?: string | null;
2048
+ /** The other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read. */
2049
+ participant_opted_out?: boolean;
2050
+ /** The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts. */
2051
+ tags?: Array<{
2052
+ name: string;
2053
+ value: string;
2054
+ }>;
2055
+ };
2056
+ type SmsAddContact = Record<string, unknown>;
2057
+ type SmsBillableResource = {
2058
+ object: "sms_billable_resource";
2059
+ id: string;
2060
+ /** What the charge is for (a local number, a 10DLC campaign, …). */
2061
+ label: string;
2062
+ resource_type: string;
2063
+ /** For a number, which one. */
2064
+ phone_number: string | null;
2065
+ country: string | null;
2066
+ monthly_price_cents: number;
2067
+ status: string;
2068
+ billing_started_at: string | null;
2069
+ next_charge_at: string | null;
2070
+ /** A past-due number is released after this. */
2071
+ grace_until: string | null;
2072
+ billable_to_customer: boolean;
761
2073
  created_at: string;
762
2074
  };
763
2075
  type SmsBrand = {
@@ -784,8 +2096,165 @@ type SmsBrand = {
784
2096
  number_count: number;
785
2097
  /** 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
2098
  editable: boolean;
2099
+ /** The name the business trades under, when it isn't the legal name. */
2100
+ dba_name?: string | null;
2101
+ /** The one Sender ID the brand sends under abroad (1–11 characters). */
2102
+ sender_id_name?: string | null;
2103
+ /** The brand's industry, in the carriers' words (e.g. `RETAIL`). */
2104
+ vertical?: string | null;
2105
+ /** `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, … */
2106
+ legal_organization_type?: string | null;
2107
+ registration_number_type?: string | null;
2108
+ tax_country?: string | null;
2109
+ stock_symbol?: string | null;
2110
+ stock_exchange?: string | null;
2111
+ /** Who carriers reach about the brand (the email is `contact_email`). */
2112
+ contact?: {
2113
+ first_name: string | null;
2114
+ last_name: string | null;
2115
+ phone: string | null;
2116
+ };
2117
+ /** The registered business address. */
2118
+ address?: {
2119
+ address1: string | null;
2120
+ address2: string | null;
2121
+ city: string | null;
2122
+ state: string | null;
2123
+ zip_code: string | null;
2124
+ iso_country_code: string | null;
2125
+ };
2126
+ /** Moves on every material change; a registration keeps the revision it was submitted with. */
2127
+ revision?: number;
2128
+ archived_at?: string | null;
2129
+ created_at: string;
2130
+ };
2131
+ type SmsBrandCreate = {
2132
+ /** The brand name recipients see. */
2133
+ name: string;
2134
+ /** The brand's website; a bare host gets https://. */
2135
+ website?: string | null;
2136
+ /** An address on the website's domain (carriers check). */
2137
+ contact_email?: string | null;
2138
+ /** The one Sender ID the brand sends under abroad: 1–11 letters, digits or hyphens, with a letter. */
2139
+ sender_id_name?: string | null;
2140
+ /** The industry, in the carriers' words (e.g. `RETAIL`). */
2141
+ vertical?: string | null;
2142
+ /** The exact registered legal name. */
2143
+ legal_name?: string | null;
2144
+ dba_name?: string | null;
2145
+ /** `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, … */
2146
+ legal_organization_type?: string | null;
2147
+ /** The company tax id (EIN in the US). Write-only: stored encrypted, read back as `tax_id_on_file`; it can be replaced, not removed. */
2148
+ tax_id?: string;
2149
+ registration_number_type?: string | null;
2150
+ /** Two-letter ISO country code. */
2151
+ tax_country?: string | null;
2152
+ stock_symbol?: string | null;
2153
+ stock_exchange?: string | null;
2154
+ contact?: {
2155
+ first_name?: string | null;
2156
+ last_name?: string | null;
2157
+ /** E.164, e.g. +12065550142. */
2158
+ phone?: string | null;
2159
+ };
2160
+ address?: {
2161
+ address1?: string | null;
2162
+ address2?: string | null;
2163
+ city?: string | null;
2164
+ /** The state or region code carriers expect (e.g. `WA`). */
2165
+ state?: string | null;
2166
+ zip_code?: string | null;
2167
+ /** Two-letter ISO country code. */
2168
+ iso_country_code?: string | null;
2169
+ };
2170
+ };
2171
+ type SmsBrandDocument = {
2172
+ object: "sms_brand_document";
2173
+ id: string;
2174
+ brand_id: string;
2175
+ kind: "registration_certificate" | "letter_of_authorization" | "proof_of_sender_id_connection" | "signatory_id" | "emirates_id" | "signatory_passport" | "establishment_card" | "power_of_attorney" | "business_license" | "tax_document" | "regulatory_license" | "carrier_registration_form" | "opt_in_screenshot" | "business_number";
2176
+ /** The slot's variant: which carrier or form a letter is addressed to (e.g. `ooredoo`), or null. */
2177
+ carrier: string | null;
2178
+ /** Set when this is one country's own version of a shared document (ADR-0115): it goes to that country only, in place of the shared file. Null for the shared file. */
2179
+ country: string | null;
2180
+ /** What the document is, in words: "Letter of authorization — Ooredoo (Qatar)". */
2181
+ label: string;
2182
+ input: "file" | "text";
2183
+ filename: string | null;
2184
+ content_type: string | null;
2185
+ size_bytes: number | null;
2186
+ /** `business_number` only. */
2187
+ text_value: string | null;
787
2188
  created_at: string;
788
2189
  };
2190
+ type SmsBrandDocumentCreate = {
2191
+ /** The document slot. File kinds: `registration_certificate`, `letter_of_authorization`, `proof_of_sender_id_connection`, `signatory_id`, `emirates_id`, `signatory_passport`, `establishment_card`, `power_of_attorney`, `business_license`, `tax_document`, `regulatory_license`, `carrier_registration_form`, `opt_in_screenshot`. Text kinds: `business_number`. A document in an occupied slot replaces the current one (the old one is kept only while a registration under review pinned it). */
2192
+ kind: "registration_certificate" | "letter_of_authorization" | "proof_of_sender_id_connection" | "signatory_id" | "emirates_id" | "signatory_passport" | "establishment_card" | "power_of_attorney" | "business_license" | "tax_document" | "regulatory_license" | "carrier_registration_form" | "opt_in_screenshot" | "business_number";
2193
+ /** The slot's variant, for documents addressed to one carrier (a letter of authorization for `ooredoo`). A Sender ID refusal names it. */
2194
+ carrier?: string;
2195
+ /** Make this one country's own version of a shared document (ADR-0115): it goes to that country only. Refused for a slot only one country reads. */
2196
+ country?: string;
2197
+ /** A file kind: a file made with `POST /files`, purpose `sms_document` (PDF, PNG or JPEG, up to 3 MB; a slot can take less, e.g. Singapore's letter is a PNG up to 400 KB) or `sms_opt_in_evidence` for `opt_in_screenshot`. */
2198
+ file_id?: string;
2199
+ /** A text kind (`business_number`). */
2200
+ text?: string;
2201
+ };
2202
+ type SmsBrandDocumentDeleted = {
2203
+ object: "sms_brand_document";
2204
+ id: string;
2205
+ deleted: true;
2206
+ /** A registration sent this file to a regulator, so it is kept as the record of what they received (not on the brand any more). */
2207
+ file_kept: boolean;
2208
+ };
2209
+ type SmsBrandDocumentUrl = {
2210
+ object: "sms_brand_document_url";
2211
+ /** A signed link to the file. It is a credential: fetch it now, don't share or log it. */
2212
+ url: string;
2213
+ /** The link stops working at this time (5 minutes). */
2214
+ expires_at: string;
2215
+ };
2216
+ type SmsBrandPatch = {
2217
+ /** The brand name recipients see. */
2218
+ name?: string | null;
2219
+ /** The brand's website; a bare host gets https://. */
2220
+ website?: string | null;
2221
+ /** An address on the website's domain (carriers check). */
2222
+ contact_email?: string | null;
2223
+ /** The one Sender ID the brand sends under abroad: 1–11 letters, digits or hyphens, with a letter. */
2224
+ sender_id_name?: string | null;
2225
+ /** The industry, in the carriers' words (e.g. `RETAIL`). */
2226
+ vertical?: string | null;
2227
+ /** The exact registered legal name. */
2228
+ legal_name?: string | null;
2229
+ dba_name?: string | null;
2230
+ /** `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, … */
2231
+ legal_organization_type?: string | null;
2232
+ /** The company tax id (EIN in the US). Write-only: stored encrypted, read back as `tax_id_on_file`; it can be replaced, not removed. */
2233
+ tax_id?: string;
2234
+ registration_number_type?: string | null;
2235
+ /** Two-letter ISO country code. */
2236
+ tax_country?: string | null;
2237
+ stock_symbol?: string | null;
2238
+ stock_exchange?: string | null;
2239
+ contact?: {
2240
+ first_name?: string | null;
2241
+ last_name?: string | null;
2242
+ /** E.164, e.g. +12065550142. */
2243
+ phone?: string | null;
2244
+ };
2245
+ address?: {
2246
+ address1?: string | null;
2247
+ address2?: string | null;
2248
+ city?: string | null;
2249
+ /** The state or region code carriers expect (e.g. `WA`). */
2250
+ state?: string | null;
2251
+ zip_code?: string | null;
2252
+ /** Two-letter ISO country code. */
2253
+ iso_country_code?: string | null;
2254
+ };
2255
+ /** Archive (`true`) or restore (`false`) the brand; send it alone. */
2256
+ archived?: boolean;
2257
+ };
789
2258
  type SmsCampaign = {
790
2259
  object: "sms_campaign";
791
2260
  id: string;
@@ -803,7 +2272,7 @@ type SmsCampaign = {
803
2272
  until: string | null;
804
2273
  } | null;
805
2274
  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";
2275
+ code: "user" | "budget_exhausted" | "plan_lapsed" | "sender_not_active" | "template_unavailable" | "workspace_suspended" | "sending_restricted" | "risk_throttled" | "sms_brand_blocked" | "subscription_inactive" | "not_drained" | "failure_streak";
807
2276
  message: string | null;
808
2277
  paused_at: string | null;
809
2278
  } | null;
@@ -831,10 +2300,38 @@ type SmsCampaignCreate = {
831
2300
  variable_fallbacks?: Record<string, string>;
832
2301
  scheduled_at?: string | null;
833
2302
  };
2303
+ type SmsCampaignRecipient = {
2304
+ object: "sms_campaign_recipient";
2305
+ /** This recipient row (`rcpt_…`); pass the last one as `after` for the next page. */
2306
+ id: string;
2307
+ contact_id: string | null;
2308
+ /** The number in E.164. */
2309
+ to: string | null;
2310
+ name: string | null;
2311
+ /** The carrier's answer when a text exists, else why none was sent (`skipped`). */
2312
+ status: "delivered" | "sent" | "failed" | "suppressed" | "canceled" | "deferred" | "pending" | "skipped";
2313
+ /** Why it failed or was skipped, in plain words. */
2314
+ reason: string | null;
2315
+ /** The SMS skip reason (`opted_out`, `no_marketing_consent`, …) when there is one. */
2316
+ reason_code: string | null;
2317
+ /** The text (`sms_…`); read it with `GET /sms/{id}`. */
2318
+ message_id: string | null;
2319
+ /** Segments billed. */
2320
+ segments: number | null;
2321
+ created_at: string;
2322
+ };
834
2323
  type SmsCampaignReschedule = {
835
2324
  /** 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
2325
  scheduled_at: string;
837
2326
  };
2327
+ type SmsCampaignResubmit = {
2328
+ /** The messaging program (`prog_…`) holding the corrected use case: fix what carriers flagged there first (PATCH /sms/messaging-programs/{id}), then resubmit from it. Its fee tier must match the campaign's (a low-volume campaign stays low-volume). */
2329
+ messaging_program_id: string;
2330
+ /** A new opt-in screenshot (POST /files, purpose `sms_opt_in_evidence`). Without one, the screenshot carriers already have is sent again. */
2331
+ opt_in_screenshot_file_id?: string;
2332
+ /** Resubmit although nothing changed since carriers sent it back, because the cause was fixed outside Unitpost (the privacy page now loads). Without it an identical resubmission is refused (`registration_unchanged`). */
2333
+ acknowledge_unchanged?: true;
2334
+ };
838
2335
  type SmsCampaignSend = {
839
2336
  scheduled_at?: string | null;
840
2337
  };
@@ -922,54 +2419,390 @@ type SmsConsentRecorded = {
922
2419
  occurred_at: string;
923
2420
  } | null;
924
2421
  };
925
- type SmsNumber = {
926
- object: "sms_number";
927
- /** Prefixed number id, e.g. `snum_…`. */
2422
+ type SmsConsentSetup = {
2423
+ object: "sms_consent_setup";
928
2424
  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;
965
- created_at: string;
2425
+ name: string;
2426
+ /** How people opt in, in the carriers' words (`DIGITAL_FORM`, `TEXT`, …): the values a program's `opt_in_type` takes. */
2427
+ type: string;
2428
+ source_url: string | null;
2429
+ is_public: boolean;
2430
+ requires_authentication: boolean;
2431
+ brand_name: string | null;
2432
+ message_purpose: string | null;
2433
+ frequency_disclosure: string | null;
2434
+ status: string;
2435
+ updated_at: string;
2436
+ };
2437
+ type SmsJoinKeyword = {
2438
+ object: "sms_join_keyword";
2439
+ /** `sjk_…`. */
2440
+ id: string;
2441
+ /** The number (`snum_…`) people text the keyword to. */
2442
+ number_id: string;
2443
+ /** As you wrote it. A text matches it whatever the case and surrounding punctuation. */
2444
+ keyword: string;
2445
+ /** The static segment (`seg_…`) a confirmed texter joins, or null. */
2446
+ segment_id: string | null;
2447
+ /** The SMS topic a confirmed texter is subscribed to, or null. */
2448
+ topic_id: string | null;
2449
+ created_at: string;
2450
+ };
2451
+ type SmsJoinKeywordCreate = {
2452
+ /** One word of 2–20 letters or digits, such as JOIN. STOP, HELP, START, YES and their variants are refused. */
2453
+ keyword: string;
2454
+ /** A static segment (`seg_…`) to add confirmed texters to. */
2455
+ segment_id?: string;
2456
+ /** An SMS topic to subscribe confirmed texters to. */
2457
+ topic_id?: string;
2458
+ };
2459
+ type SmsJoinKeywordCreated = {
2460
+ object: "sms_join_keyword";
2461
+ /** `sjk_…`. */
2462
+ id: string;
2463
+ /** The number (`snum_…`) people text the keyword to. */
2464
+ number_id: string;
2465
+ /** As you wrote it. A text matches it whatever the case and surrounding punctuation. */
2466
+ keyword: string;
2467
+ /** The static segment (`seg_…`) a confirmed texter joins, or null. */
2468
+ segment_id: string | null;
2469
+ /** The SMS topic a confirmed texter is subscribed to, or null. */
2470
+ topic_id: string | null;
2471
+ created_at: string;
2472
+ /** Set when the number's carrier registration doesn't list texting a keyword as a way to opt in: carriers can flag sign-ups its registration didn't declare, so add keyword opt-in to its use case and resubmit. Null otherwise. */
2473
+ registration_warning: string | null;
2474
+ };
2475
+ type SmsJoinKeywordList = {
2476
+ object: "list";
2477
+ data: Array<{
2478
+ object: "sms_join_keyword";
2479
+ /** `sjk_…`. */
2480
+ id: string;
2481
+ /** The number (`snum_…`) people text the keyword to. */
2482
+ number_id: string;
2483
+ /** As you wrote it. A text matches it whatever the case and surrounding punctuation. */
2484
+ keyword: string;
2485
+ /** The static segment (`seg_…`) a confirmed texter joins, or null. */
2486
+ segment_id: string | null;
2487
+ /** The SMS topic a confirmed texter is subscribed to, or null. */
2488
+ topic_id: string | null;
2489
+ created_at: string;
2490
+ }>;
2491
+ has_more: boolean;
2492
+ /** Set when the number's carrier registration doesn't list texting a keyword as a way to opt in: carriers can flag sign-ups its registration didn't declare, so add keyword opt-in to its use case and resubmit. Null otherwise. */
2493
+ registration_warning: string | null;
2494
+ };
2495
+ type SmsMessagingProgram = {
2496
+ name: string;
2497
+ description?: string | null;
2498
+ message_type: "transactional" | "marketing";
2499
+ canonical_purpose?: string | null;
2500
+ frequency_disclosure?: string | null;
2501
+ opt_in_type?: string | null;
2502
+ opt_in_workflow?: string | null;
2503
+ opt_in_confirmation?: string | null;
2504
+ help_message?: string | null;
2505
+ stop_message?: string | null;
2506
+ terms_url?: string | null;
2507
+ privacy_url?: string | null;
2508
+ monthly_volume?: string | null;
2509
+ sample_messages: Array<string>;
2510
+ embedded_links: boolean;
2511
+ embedded_link_sample?: string | null;
2512
+ embedded_phones: boolean;
2513
+ age_gated: boolean;
2514
+ provider_overrides?: {
2515
+ toll_free?: {
2516
+ use_case_category?: string;
2517
+ };
2518
+ ten_dlc?: {
2519
+ use_case?: string;
2520
+ sub_use_cases?: Array<string>;
2521
+ };
2522
+ } | null;
2523
+ recipe_id: string | null;
2524
+ /** A consent setup (`cset_…`) this workspace has. */
2525
+ consent_setup_id?: string | null;
2526
+ object: "sms_messaging_program";
2527
+ id: string;
2528
+ recipe_version: number | null;
2529
+ /** Moves on a material change; registrations keep the revision they copied. */
2530
+ revision: number;
2531
+ /** Whether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check). */
2532
+ readiness: {
2533
+ ready: boolean;
2534
+ missing: Array<string>;
2535
+ };
2536
+ archived_at: string | null;
2537
+ created_at: string;
2538
+ updated_at: string;
2539
+ };
2540
+ type SmsMessagingProgramCreate = {
2541
+ name: string;
2542
+ description?: string | null;
2543
+ message_type?: "transactional" | "marketing";
2544
+ canonical_purpose?: string | null;
2545
+ frequency_disclosure?: string | null;
2546
+ opt_in_type?: string | null;
2547
+ opt_in_workflow?: string | null;
2548
+ opt_in_confirmation?: string | null;
2549
+ help_message?: string | null;
2550
+ stop_message?: string | null;
2551
+ terms_url?: string | null;
2552
+ privacy_url?: string | null;
2553
+ monthly_volume?: string | null;
2554
+ sample_messages?: Array<string>;
2555
+ embedded_links?: boolean;
2556
+ embedded_link_sample?: string | null;
2557
+ embedded_phones?: boolean;
2558
+ age_gated?: boolean;
2559
+ provider_overrides?: {
2560
+ toll_free?: {
2561
+ use_case_category?: string;
2562
+ };
2563
+ ten_dlc?: {
2564
+ use_case?: string;
2565
+ sub_use_cases?: Array<string>;
2566
+ };
2567
+ } | null;
2568
+ /** The compliance recipe the program follows; its version is the recipe's current one. Left out, it's derived from `canonical_purpose`. */
2569
+ recipe_id?: "ACCOUNT_NOTIFICATIONS" | "SECURITY_ALERTS" | "ONE_TIME_PASSCODES" | "ORDER_UPDATES" | "APPOINTMENT_REMINDERS" | "CUSTOMER_SUPPORT" | "MARKETING_PROMOTIONS" | "OTHER_CUSTOM";
2570
+ /** A consent setup (`cset_…`) this workspace has. */
2571
+ consent_setup_id?: string | null;
2572
+ };
2573
+ type SmsMessagingProgramUpdate = {
2574
+ name?: string;
2575
+ description?: string | null;
2576
+ message_type?: "transactional" | "marketing";
2577
+ canonical_purpose?: string | null;
2578
+ frequency_disclosure?: string | null;
2579
+ opt_in_type?: string | null;
2580
+ opt_in_workflow?: string | null;
2581
+ opt_in_confirmation?: string | null;
2582
+ help_message?: string | null;
2583
+ stop_message?: string | null;
2584
+ terms_url?: string | null;
2585
+ privacy_url?: string | null;
2586
+ monthly_volume?: string | null;
2587
+ sample_messages?: Array<string>;
2588
+ embedded_links?: boolean;
2589
+ embedded_link_sample?: string | null;
2590
+ embedded_phones?: boolean;
2591
+ age_gated?: boolean;
2592
+ provider_overrides?: {
2593
+ toll_free?: {
2594
+ use_case_category?: string;
2595
+ };
2596
+ ten_dlc?: {
2597
+ use_case?: string;
2598
+ sub_use_cases?: Array<string>;
2599
+ };
2600
+ } | null;
2601
+ /** The compliance recipe the program follows; its version is the recipe's current one. Left out, it's derived from `canonical_purpose`. */
2602
+ recipe_id?: "ACCOUNT_NOTIFICATIONS" | "SECURITY_ALERTS" | "ONE_TIME_PASSCODES" | "ORDER_UPDATES" | "APPOINTMENT_REMINDERS" | "CUSTOMER_SUPPORT" | "MARKETING_PROMOTIONS" | "OTHER_CUSTOM";
2603
+ /** A consent setup (`cset_…`) this workspace has. */
2604
+ consent_setup_id?: string | null;
2605
+ };
2606
+ type SmsNumber = {
2607
+ object: "sms_number";
2608
+ /** Prefixed number id, e.g. `snum_…`. */
2609
+ id: string;
2610
+ /** E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval. */
2611
+ phone_number: string | null;
2612
+ /** `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. */
2613
+ type: "toll_free" | "ten_dlc" | "long_code" | "sender_id" | "simulator";
2614
+ /** Only `active` numbers can send. */
2615
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
2616
+ /** Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag. */
2617
+ is_default: boolean;
2618
+ /** 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. */
2619
+ country: string | null;
2620
+ /** Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. 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. */
2621
+ two_way: boolean;
2622
+ /** 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. */
2623
+ reach: Array<string>;
2624
+ /** The brand this number is registered under. */
2625
+ brand_id: string | null;
2626
+ /** What carriers approved this number to send. Required for approval; submitted with the number. */
2627
+ use_case: {
2628
+ name: string;
2629
+ category: string | null;
2630
+ } | null;
2631
+ /** 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`. */
2632
+ action_required_reason: string | null;
2633
+ /** What carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159). */
2634
+ feedback?: Array<{
2635
+ /** The carrier's reason code. */
2636
+ reason: string;
2637
+ /** What to fix, in the carrier's words (redacted). */
2638
+ description: string;
2639
+ /** A carrier help page about it, when they gave one. */
2640
+ link: string | null;
2641
+ }> | null;
2642
+ /** 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. */
2643
+ sender_id_group: {
2644
+ /** The Sender ID string recipients see. */
2645
+ name: string;
2646
+ /** The brand that owns this Sender ID. */
2647
+ brand_id: string | null;
2648
+ /** Every country this Sender ID is enabled for, with each country's own status. */
2649
+ countries: Array<{
2650
+ /** ISO-3166 alpha-2. */
2651
+ country: string;
2652
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
2653
+ }>;
2654
+ } | null;
2655
+ created_at: string;
2656
+ };
2657
+ type SmsNumberRelease = {
2658
+ /** Release although campaigns are scheduled on this number or texts are queued through it (the 409 `sender_release_blocked` lists them): those sends fail as "sender not active". An automation that uses the number still blocks the release (`resource_in_use`). */
2659
+ force?: boolean;
2660
+ };
2661
+ type SmsNumberRequest = {
2662
+ object: "sms_number_request";
2663
+ /** The 10DLC campaign (`sreg_…`). */
2664
+ registration_id: string;
2665
+ /** The number (`snum_…`): read its state on GET /sms/numbers. It leases within minutes. */
2666
+ number_id: string;
2667
+ /** False when the campaign's number was already live: nothing was requested. */
2668
+ created: boolean;
2669
+ /** A failed number was brought back (the same row, the same committed fee). */
2670
+ retried: boolean;
2671
+ };
2672
+ type SmsNumberResubmission = {
2673
+ object: "sms_number_resubmission";
2674
+ number_id: string;
2675
+ /** The verification went back to carriers; the number reads `pending` on GET /sms/numbers until they answer. */
2676
+ status: "resubmitted";
2677
+ resubmitted: true;
2678
+ };
2679
+ type SmsNumberRetry = Record<string, unknown>;
2680
+ type SmsOptInRequest = {
2681
+ /** Which of the contact's numbers to text (E.164). Default: its primary number. */
2682
+ phone?: string;
966
2683
  };
967
2684
  type SmsPatch = {
968
- /** Cancel a `queued` or `scheduled` text. Its reserved credit is refunded. */
2685
+ /** Cancel a `queued` or `scheduled` text. Its reserved credit is refunded (a text due in a later billing period has not been charged yet). */
969
2686
  cancel?: true;
970
- /** Move a `scheduled` text to this future time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC. */
2687
+ /** Move a `scheduled` text to this future time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC. A text moved into a later billing period is refunded now and paid when it sends; a text is never charged twice. */
971
2688
  scheduled_at?: string;
972
2689
  };
2690
+ type SmsQuote = {
2691
+ object: "sms_quote";
2692
+ /** The quote (`squote_…`). */
2693
+ id: string;
2694
+ product: "ten_dlc_brand_registration" | "ten_dlc_brand_vetting" | "ten_dlc_campaign" | "ten_dlc_number" | "long_code_number" | "toll_free_number";
2695
+ /** `open` until confirmed or `expires_at`; `ordered` once placed; `pending` while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed, and it settles to `ordered` or `failed` from the billing ledger, so read it again; don't buy the same thing meanwhile); `failed` when the confirm bought nothing (nothing was charged; quote again). */
2696
+ status: "open" | "expired" | "confirming" | "ordered" | "pending" | "failed";
2697
+ /** What is bought, as the dashboard names it. */
2698
+ label: string;
2699
+ brand_id: string | null;
2700
+ /** The registration the order is for (a brand registration, or the campaign whose number it is). */
2701
+ registration_id: string | null;
2702
+ messaging_program_id: string | null;
2703
+ country: string | null;
2704
+ /** Charged at the confirm, from the plan's allowance (one-time fees). */
2705
+ due_now_cents: number;
2706
+ /** Charged when the number leases or carriers approve the campaign, then every month. */
2707
+ monthly_cents: number;
2708
+ currency: "usd";
2709
+ line_items: Array<{
2710
+ fee_code: string;
2711
+ label: string;
2712
+ amount_cents: number;
2713
+ cadence: "one_time" | "monthly";
2714
+ /** When the fee starts: at the confirm, when the number leases, or when carriers approve the campaign. */
2715
+ starts_when: "on_confirmation" | "number_leased" | "campaign_approved";
2716
+ }>;
2717
+ /** This workspace's carrier fees are covered by Unitpost: nothing is charged. */
2718
+ covered_by_unitpost: boolean;
2719
+ /** Confirm before this (quotes last 10 minutes). */
2720
+ expires_at: string;
2721
+ created_at: string;
2722
+ confirmed_at: string | null;
2723
+ /** What the confirmed order made; null until then. */
2724
+ order: {
2725
+ /** The carrier registration the order made (`sreg_…`). */
2726
+ registration_id: string | null;
2727
+ /** The number it ordered (`snum_…`); it leases shortly after. */
2728
+ number_id: string | null;
2729
+ /** The registration's or the number request's status as the order left it. */
2730
+ status: string | null;
2731
+ } | null;
2732
+ /** Only in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote. */
2733
+ confirm_token?: string;
2734
+ };
2735
+ type SmsQuoteConfirm = {
2736
+ /** The quote's confirm token (`sqct_…`), from its create response. Single use. */
2737
+ confirm_token: string;
2738
+ };
2739
+ type SmsQuoteCreate = {
2740
+ /** What to buy. `ten_dlc_brand_registration` registers a brand with US carriers (or resubmits one they sent back; the fee is the resubmission's). `ten_dlc_brand_vetting` vets an approved brand for higher throughput. `ten_dlc_campaign` registers a 10DLC campaign from a messaging program, with its local number, which leases once carriers approve it. `ten_dlc_number` orders the number of an approved campaign that has none (a failed number whose fee is already committed is retried for free: POST /sms/registrations/{id}/number). `long_code_number` orders a local number that needs no registration (`country: "CA"`). `toll_free_number` orders a US toll-free number and files its carrier verification from the brand and a messaging program, with the opt-in evidence as a file (`opt_in_evidence_file_id`). */
2741
+ product: "ten_dlc_brand_registration" | "ten_dlc_brand_vetting" | "ten_dlc_campaign" | "ten_dlc_number" | "long_code_number" | "toll_free_number";
2742
+ /** The SMS brand (`sbrand_…`). */
2743
+ brand_id?: string;
2744
+ /** `ten_dlc_number`: the approved 10DLC campaign registration (`sreg_…`). */
2745
+ registration_id?: string;
2746
+ /** `ten_dlc_campaign`: the messaging program (`prog_…`) the campaign is registered from. */
2747
+ messaging_program_id?: string;
2748
+ /** `long_code_number`: the two-letter country (`CA`). */
2749
+ country?: string;
2750
+ /** `long_code_number`: the number's name in the dashboard. */
2751
+ display_name?: string;
2752
+ /** `ten_dlc_brand_registration`: who at the company follows the registry's email link, on the brand website's domain. Required for a public company, or when carriers ask for it; else the brand's saved one. */
2753
+ brand_verification_email?: string;
2754
+ /** `ten_dlc_brand_registration`, a resubmission: send it anyway although nothing carriers flagged changed, because the cause was fixed outside Unitpost (the website now loads, the registry was updated). Without it, an identical resubmission is refused (`registration_unchanged`, nothing charged). */
2755
+ acknowledge_unchanged?: true;
2756
+ /** `ten_dlc_campaign`: a screenshot of the opt-in (POST /files, purpose `sms_opt_in_evidence`: PNG up to 400 KB). Carriers require one for verbal or printed opt-in, or when the opt-in workflow links to no public page. */
2757
+ opt_in_screenshot_file_id?: string;
2758
+ /** `toll_free_number`: the opt-in evidence carriers review (POST /files, purpose `sms_opt_in_evidence`: a PNG up to 400 KB of the form, page or flow where people agree to receive these texts). */
2759
+ opt_in_evidence_file_id?: string;
2760
+ /** `toll_free_number`: an IRS letter (CP 575, 147C or SS-4) or registry extract showing the legal name and company ID (POST /files, purpose `sms_document`, up to 2 MB). Required when the brand is a government agency. */
2761
+ business_registration_document_file_id?: string;
2762
+ /** `toll_free_number`: the public https page where people opt in (your form or checkout). Goes into the opt-in description carriers read. */
2763
+ consent_source_url?: string;
2764
+ };
2765
+ type SmsRegistration = {
2766
+ object: "sms_registration";
2767
+ id: string;
2768
+ /** `us_ten_dlc_brand`, `us_ten_dlc_campaign`, or a toll-free verification. */
2769
+ type: string;
2770
+ brand_id: string | null;
2771
+ /** The carrier review state: `draft`, `submitted`, `reviewing`, `requires_updates`, `complete`, `closed`, … */
2772
+ status: string;
2773
+ /** The customer must act (the carrier asked for changes). */
2774
+ requires_action: boolean;
2775
+ /** The carrier's reasons when it asks for changes or closes it (`reason`, `description`, `field_path`, `link`). */
2776
+ feedback: Array<Record<string, unknown>> | null;
2777
+ use_case: string | null;
2778
+ message_type: string | null;
2779
+ parent_registration_id: string | null;
2780
+ /** 10DLC campaigns: a number is leased when carriers approve. */
2781
+ auto_provision_number: boolean | null;
2782
+ /** 10DLC campaigns: the number it backs, once one exists. */
2783
+ sender: {
2784
+ id: string;
2785
+ status: string;
2786
+ phone_number: string | null;
2787
+ } | null;
2788
+ /** 10DLC campaigns: one customer-facing state over the campaign and its number. */
2789
+ setup_state: string | null;
2790
+ /** Why an approved campaign's number isn't being leased (e.g. the plan has no carrier resources). */
2791
+ number_withheld_reason: string | null;
2792
+ archived_at: string | null;
2793
+ submitted_at: string | null;
2794
+ completed_at: string | null;
2795
+ created_at: string;
2796
+ };
2797
+ type SmsRegistrationRemove = Record<string, unknown>;
2798
+ type SmsRegistrationReplace = Record<string, unknown>;
2799
+ type SmsRegistrationResubmission = {
2800
+ object: "sms_registration_resubmission";
2801
+ registration_id: string;
2802
+ /** The registration's state after the resubmission (`submitted`, `reviewing`, …); follow it on GET /sms/registrations. */
2803
+ status: string | null;
2804
+ resubmitted: true;
2805
+ };
973
2806
  type SmsSend = {
974
2807
  /** Recipient phone number in E.164 format, e.g. `+15551234567`. */
975
2808
  to: string;
@@ -979,10 +2812,15 @@ type SmsSend = {
979
2812
  body: string;
980
2813
  /** 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. */
981
2814
  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. */
2815
+ /** 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. A time in a later billing period is checked now (plan, price, country) but paid when it sends, from that period's allowance, so this period's balance does not refuse it. If the plan can't cover it then, the text ends `failed` with `failure_code` set (e.g. `quota_exceeded`), and `sms.failed` fires with the same code. */
983
2816
  scheduled_at?: string;
984
2817
  /** 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
2818
  create_contact?: boolean;
2819
+ /** Labels to tell your texts apart later (which customer, feature or agent a text was for): up to 10 `{ name, value }` pairs, each half 1–256 ASCII letters, digits, `_` or `-`, the same rule as email tags. More than 10, or a character outside the rule, is `422 validation_error` and nothing is sent; keep anything more in your own records under the text's `id`. Returned as `tags` on the SMS object and in outbound `sms.*` webhooks; filter the list with `GET /sms?tag=name:value`. */
2820
+ tags?: Array<{
2821
+ name: string;
2822
+ value: string;
2823
+ }>;
986
2824
  };
987
2825
  type SmsStats = {
988
2826
  object: "sms_stats";
@@ -1027,11 +2865,98 @@ type SmsTemplateCreate = {
1027
2865
  name: string;
1028
2866
  body?: string;
1029
2867
  };
2868
+ type SmsTemplateTestSend = {
2869
+ /** A simulator number (`+14254147755` delivers, `+14254147167` fails) or one of GET /sms/test-destinations' verified numbers (E.164). */
2870
+ to: string;
2871
+ /** Values for the template's `{{variables}}`; every one must be filled. */
2872
+ variables?: Record<string, string>;
2873
+ /** Send from this live sender (`snum_…`); default: routed like any text. */
2874
+ sender_id?: string;
2875
+ };
2876
+ type SmsTemplateTestSendResult = {
2877
+ object: "sms_template_test_send";
2878
+ /** The test text (`sms_…`); read it with GET /sms/{id}. */
2879
+ sms_id: string;
2880
+ };
1030
2881
  type SmsTemplateUpdate = {
1031
2882
  name?: string;
1032
2883
  body?: string;
1033
2884
  status?: "draft" | "published";
1034
2885
  };
2886
+ type SmsTemplateUsage = {
2887
+ object: "sms_template_usage";
2888
+ template_id: string;
2889
+ live_campaigns: Array<{
2890
+ id: string;
2891
+ name: string;
2892
+ status: string;
2893
+ }>;
2894
+ live_automations: Array<{
2895
+ id: string;
2896
+ name: string;
2897
+ status: string;
2898
+ }>;
2899
+ pending_sends: number;
2900
+ system_locked: boolean;
2901
+ can_edit_content: boolean;
2902
+ content_blocked_reason: string | null;
2903
+ can_unpublish: boolean;
2904
+ unpublish_blocked_reason: string | null;
2905
+ };
2906
+ type SmsTestDestination = {
2907
+ object: "sms_test_destination";
2908
+ id: string;
2909
+ phone_number: string;
2910
+ /** `pending` until the code texted to it is entered in the dashboard, then `verified`. */
2911
+ status: string;
2912
+ created_at: string;
2913
+ };
2914
+ type SmsTollFreeResubmit = {
2915
+ /** The messaging program (`prog_…`) the corrected use case, samples and opt-in come from; fix what carriers flagged there (or on the brand) first. Defaults to the program the number was registered from. */
2916
+ messaging_program_id?: string;
2917
+ /** New opt-in evidence (POST /files, purpose `sms_opt_in_evidence`). Required when carriers flagged the evidence, unless `reuse_opt_in_evidence`. */
2918
+ opt_in_evidence_file_id?: string;
2919
+ /** Send the evidence on file again although carriers flagged it (it was fixed where it lives, e.g. the page it shows changed). */
2920
+ reuse_opt_in_evidence?: true;
2921
+ /** A new business registration document (POST /files, purpose `sms_document`, up to 2 MB): required when carriers flagged it. */
2922
+ business_registration_document_file_id?: string;
2923
+ /** The public https page where people opt in. */
2924
+ consent_source_url?: string;
2925
+ /** Resubmit fields carriers flagged unchanged, because the cause was fixed outside Unitpost. Without it they're refused (`flagged_fields_unchanged`). */
2926
+ acknowledge_unchanged?: true;
2927
+ };
2928
+ type SpendCaps$1 = {
2929
+ object: "spend_caps";
2930
+ /** SMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count. */
2931
+ sms_purchases: {
2932
+ /** The monthly cap on SMS purchases made with an API key or an app, as set. Null: none, so every API purchase is refused. 0: API purchases off. The cap that applies is the lower of this and `max_cents`. */
2933
+ cap_cents: number | null;
2934
+ /** The most a cap may be set to, and the most any cap counts as (Unitpost's limit, which staff can change). */
2935
+ max_cents: number;
2936
+ /** Counted this period: each API purchase's fee due now plus the first month of a monthly fee, for orders placed, confirming or waiting on the carrier. Failed orders count nothing. */
2937
+ spent_cents: number;
2938
+ /** The start of the UTC calendar month being counted (inclusive). */
2939
+ period_start: string;
2940
+ /** The start of the next UTC month (exclusive). */
2941
+ period_end: string;
2942
+ };
2943
+ /** The workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan. */
2944
+ shared_plan?: {
2945
+ /** What this workspace may draw from the shared plan each period (allowance and overage together), set by its organization. Null: no cap. */
2946
+ cap_cents: number | null;
2947
+ /** What this workspace drew this period (its own sending and SMS, never the other workspaces'). */
2948
+ spent_cents: number;
2949
+ /** The shared plan's current billing period start (inclusive). */
2950
+ period_start: string | null;
2951
+ /** The period end (exclusive). */
2952
+ period_end: string | null;
2953
+ } | null;
2954
+ };
2955
+ type SpendCapsUpdate = {
2956
+ sms_purchases?: {
2957
+ cap_cents: number | null;
2958
+ };
2959
+ };
1035
2960
  type Suppression = {
1036
2961
  object: "suppression";
1037
2962
  id: string;
@@ -1070,9 +2995,13 @@ type Template = {
1070
2995
  kind: "simple" | "designed";
1071
2996
  /** Inbox preview text: the snippet most inboxes show after the subject. Empty when unset. */
1072
2997
  preview_text?: string;
2998
+ /** `marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update. */
2999
+ category?: "transactional" | "marketing";
1073
3000
  html?: string | null;
1074
3001
  /** 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
3002
  tsx?: string | null;
3003
+ /** A `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows. */
3004
+ text?: string | null;
1076
3005
  /** 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
3006
  warnings?: Array<string>;
1078
3007
  created_at: string;
@@ -1082,7 +3011,7 @@ type Template = {
1082
3011
  type TemplateCreate = {
1083
3012
  name: string;
1084
3013
  subject?: 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`. */
3014
+ /** 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>, and <br /> for a line break (a new line in the markup is only a space); 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
3015
  tsx?: string;
1087
3016
  /** 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
3017
  html?: string;
@@ -1117,6 +3046,33 @@ type TemplateCreate = {
1117
3046
  preview_text?: string;
1118
3047
  category?: "transactional" | "marketing";
1119
3048
  };
3049
+ type TemplateDuplicate = {
3050
+ /** The copy's name. Default: the original's with " (copy)". */
3051
+ name?: string;
3052
+ };
3053
+ type TemplateFromLibrary = {
3054
+ /** The gallery email to add (unitpost.com/templates): `welcome`, `email-verification`, `one-time-code`, `magic-link`, `password-reset`, `password-changed`, `security-alert`, `team-invite`, `receipt`, `invoice`, `payment-failed`, `subscription-renewal`, `trial-ending`, `usage-alert`, `subscription-cancelled`, `order-confirmation`, `shipping-confirmation`, `delivery-update`, `booking-confirmation`, `appointment-reminder`, `review-request`, `comment-mention`, `support-reply`, `weekly-report`, `document-to-sign`, `export-ready`, `newsletter`, `daily-brief`, `link-roundup`, `content-digest`, `essay-letter`, `founder-letter`, `community-update`, `monthly-product-update`, `july-newsletter`, `product-announcement`, `product-launch-dark`, `app-release`, `pricing-update`, `waitlist-invite`, `flash-sale`, `discount-offer`, `new-collection`, `back-in-stock`, `abandoned-cart`, `birthday-reward`, `holiday-greeting`, `new-listings`, `seasonal-menu`, `rewards-poster`, `travel-guide`, `event-invite`, `conference-invite`, `webinar-recap`, `webinar-invite`, `onboarding-tips`, `re-engagement`, `feedback-survey`, `referral`, `case-study`, `nonprofit-impact`. */
3055
+ slug: string;
3056
+ /** The template's name. Default: the gallery email's. */
3057
+ name?: string;
3058
+ };
3059
+ type TemplateRender = {
3060
+ object: "template_render";
3061
+ subject: string;
3062
+ /** The HTML a send would carry, footer and branding included. `{{unsubscribe_url}}` is a preview link. */
3063
+ html: string;
3064
+ text: string;
3065
+ /** Variables with no value: they render as a literal {{token}}, and a real send would refuse them. */
3066
+ missing_variables: Array<string>;
3067
+ };
3068
+ type TemplateRenderInput = {
3069
+ /** Values for the template's {{variables}}, as a send's `template.variables`. One with no value stays a literal {{token}} and is listed in `missing_variables`. */
3070
+ variables?: Record<string, string | number>;
3071
+ /** Render this subject instead of the template's. */
3072
+ subject?: string;
3073
+ /** Fill contact fields ({{first_name}}, custom fields) from this contact (`con_…`), as a send to them would. */
3074
+ contact_id?: string;
3075
+ };
1120
3076
  type TemplateTestSend = {
1121
3077
  to: string;
1122
3078
  subject?: string;
@@ -1138,7 +3094,7 @@ type TemplateUpdate = {
1138
3094
  name?: string;
1139
3095
  subject?: string | null;
1140
3096
  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`. */
3097
+ /** 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>, and <br /> for a line break (a new line in the markup is only a space); 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
3098
  tsx?: string;
1143
3099
  /** 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`. */
1144
3100
  html?: string;
@@ -1171,9 +3127,55 @@ type TemplateUpdate = {
1171
3127
  };
1172
3128
  /** Inbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>. */
1173
3129
  preview_text?: string;
3130
+ /** `marketing` or `transactional`, on any editor. A campaign sends only a `marketing` template; a change is a content edit, so it is refused while a live campaign uses the template. With `tsx` it wins over `<Email category>`. */
3131
+ category?: "transactional" | "marketing";
1174
3132
  /** 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
3133
  editor?: "simple" | "design" | "code";
1176
3134
  };
3135
+ type TemplateUsage = {
3136
+ object: "template_usage";
3137
+ template_id: string;
3138
+ /** The campaigns that use it, any status, newest first: the newest 25 (`campaign_count` says how many in all). */
3139
+ campaigns: Array<{
3140
+ id: string;
3141
+ name: string;
3142
+ status: "draft" | "scheduled" | "sending" | "paused" | "sent" | "canceled" | "failed";
3143
+ created_at: string;
3144
+ }>;
3145
+ /** How many campaigns use it in all. */
3146
+ campaign_count: number;
3147
+ /** Emails sent from it, all time. */
3148
+ sent_count: number;
3149
+ /** Scheduled, sending or paused campaigns: they render its current content when they send, so its content is locked. */
3150
+ live_campaigns: Array<{
3151
+ id: string;
3152
+ name: string;
3153
+ status: "draft" | "scheduled" | "sending" | "paused" | "sent" | "canceled" | "failed";
3154
+ }>;
3155
+ /** Active or paused automations whose published version sends it: it can't be unpublished or deleted. */
3156
+ live_automations: Array<{
3157
+ id: string;
3158
+ name: string;
3159
+ status: "active" | "paused";
3160
+ }>;
3161
+ /** Queued or scheduled single sends that render it when they go out. */
3162
+ pending_sends: number;
3163
+ /** A template behind Unitpost's own emails: read-only. */
3164
+ system_locked: boolean;
3165
+ /** Whether an update to its body, subject or category would be accepted now. */
3166
+ can_edit_content: boolean;
3167
+ content_blocked_reason: string | null;
3168
+ /** Whether `status: "draft"` would be accepted now. */
3169
+ can_unpublish: boolean;
3170
+ unpublish_blocked_reason: string | null;
3171
+ };
3172
+ type TemplateVersion = {
3173
+ object: "template_version";
3174
+ /** 1 is the first publish; every publish, and every content save while published, adds one. */
3175
+ version: number;
3176
+ subject: string | null;
3177
+ created_at: string;
3178
+ };
1177
3179
  type Topic = {
1178
3180
  object: "topic";
1179
3181
  id: string;
@@ -1182,6 +3184,10 @@ type Topic = {
1182
3184
  /** Which channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`. */
1183
3185
  channel: "email" | "sms";
1184
3186
  default_opt_in: boolean;
3187
+ /** Contacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count. */
3188
+ subscriber_count?: number;
3189
+ /** Reachable contacts who opted out of this topic. */
3190
+ unsubscribed_count?: number;
1185
3191
  created_at: string;
1186
3192
  updated_at: string;
1187
3193
  };
@@ -1190,6 +3196,15 @@ type TopicCreate = {
1190
3196
  description?: string;
1191
3197
  default_opt_in?: boolean;
1192
3198
  };
3199
+ /** Who to opt out: exactly one of `contact_ids`, `emails` or `segment_id`. */
3200
+ type TopicOptOut = {
3201
+ /** Contacts of this workspace (`con_…`), up to 1,000. */
3202
+ contact_ids?: Array<string>;
3203
+ /** Contacts of this workspace by email address, up to 1,000. */
3204
+ emails?: Array<string>;
3205
+ /** Every member of this segment (`seg_…`), however many. Also needs `segments:read`. */
3206
+ segment_id?: string;
3207
+ };
1193
3208
  type TopicUpdate = {
1194
3209
  name?: string;
1195
3210
  description?: string | null;
@@ -1209,11 +3224,19 @@ type Usage$1 = {
1209
3224
  wallet: {
1210
3225
  allowance_cents: number | null;
1211
3226
  used_cents: number;
3227
+ reserved_cents: number;
3228
+ fee_deficit_cents: number;
3229
+ fee_deficit_settled_cents: number;
1212
3230
  carryover_cents: number;
1213
3231
  purchased_credit_cents: number;
1214
3232
  overage_cents: number;
1215
3233
  overage_cap_cents: number | null;
1216
3234
  email_rate_per_1k_cents: number | null;
3235
+ shared_plan?: {
3236
+ allowance_cents: number | null;
3237
+ cap_cents: number | null;
3238
+ paused: boolean;
3239
+ } | null;
1217
3240
  } | null;
1218
3241
  spend: {
1219
3242
  total_cents: number;
@@ -1241,9 +3264,56 @@ type Usage$1 = {
1241
3264
  messages: number;
1242
3265
  segments: number;
1243
3266
  price_per_segment_cents: number | null;
3267
+ price_per_segment_cents_decimal?: string | null;
3268
+ cost_cents: number;
3269
+ }>;
3270
+ received_countries?: Array<{
3271
+ country: string;
3272
+ received: number;
3273
+ segments: number;
1244
3274
  cost_cents: number;
1245
3275
  }>;
1246
3276
  };
3277
+ limits?: {
3278
+ /** Days sent and received email, events and activity stay readable; null when unlimited or custom. */
3279
+ log_retention_days: number | null;
3280
+ /** Sending domains; null when unlimited or custom. */
3281
+ domains: number | null;
3282
+ /** Team members (seats); null when unlimited or custom. */
3283
+ team_members: number | null;
3284
+ /** Live API keys; null when unlimited or custom. */
3285
+ api_keys: number | null;
3286
+ /** Webhook endpoints; null when unlimited or custom. */
3287
+ webhook_endpoints: number | null;
3288
+ /** Hosted image storage, in MB; null when unlimited or custom. */
3289
+ image_storage_mb: number | null;
3290
+ /** Stored contacts; null when unlimited or custom. */
3291
+ contacts: number | null;
3292
+ /** How far ahead a send or campaign may be scheduled, in days; null means the platform's maximum, 90. */
3293
+ advance_scheduling_days: number | null;
3294
+ /** Automation runs included per period; null when unlimited or custom. */
3295
+ automation_runs_included: number | null;
3296
+ /** Ask Unit credits per period; null when unlimited or custom. */
3297
+ ai_credits: number | null;
3298
+ /** Toll-free numbers held at once; null when unlimited or custom. */
3299
+ sms_toll_free_numbers: number | null;
3300
+ /** Instant local numbers held per country; null when unlimited or custom. */
3301
+ sms_local_numbers_per_country: number | null;
3302
+ };
3303
+ features?: {
3304
+ /** The SMS channel: brands, senders and sends. */
3305
+ sms: boolean;
3306
+ /** Phone numbers and carrier registrations billed from the wallet. */
3307
+ sms_carrier_resources: boolean;
3308
+ /** Receiving email on your domains. */
3309
+ inbound_email: boolean;
3310
+ /** Subscription topics. */
3311
+ topics: boolean;
3312
+ /** Read-only and custom API keys, fine-tuned teammate permissions. */
3313
+ granular_permissions: boolean;
3314
+ /** Removing the Unitpost mark from the footer and unsubscribe page. */
3315
+ remove_branding: boolean;
3316
+ };
1247
3317
  };
1248
3318
  type Webhook = {
1249
3319
  object: "webhook";
@@ -1252,13 +3322,24 @@ type Webhook = {
1252
3322
  url: string;
1253
3323
  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 & {})>;
1254
3324
  status: "enabled" | "disabled" | "suspended";
3325
+ /** `email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it. */
3326
+ include_text?: boolean;
1255
3327
  created_at: string;
1256
3328
  updated_at: string;
3329
+ /** The deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`. */
3330
+ backlog?: {
3331
+ /** Deliveries held while the endpoint was paused or disabled. */
3332
+ queued: number;
3333
+ /** Deliveries that failed or ran out of retries. */
3334
+ failed: number;
3335
+ };
1257
3336
  };
1258
3337
  type WebhookCreate = {
1259
3338
  url: string;
1260
3339
  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 & {})>;
1261
3340
  name?: string;
3341
+ /** `email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it. */
3342
+ include_text?: boolean;
1262
3343
  };
1263
3344
  type WebhookCreated = Webhook & {
1264
3345
  /** 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. */
@@ -1288,6 +3369,22 @@ type WebhookDelivery = {
1288
3369
  /** The event's `data`, as delivered. */
1289
3370
  data: Record<string, unknown>;
1290
3371
  };
3372
+ type WebhookDeliveryReplay = {
3373
+ object: "webhook_delivery_replay";
3374
+ webhook_id: string;
3375
+ delivery_id: string;
3376
+ replayed: true;
3377
+ };
3378
+ type WebhookFlush = {
3379
+ /** Also deliver the `failed` and `exhausted` deliveries again. Default false: only the `queued` ones (held while the webhook was suspended). */
3380
+ include_failed?: boolean;
3381
+ };
3382
+ type WebhookFlushResult = {
3383
+ object: "webhook_flush";
3384
+ webhook_id: string;
3385
+ /** How many deliveries were handed back for delivery (0 when the backlog was empty). */
3386
+ flushed: number;
3387
+ };
1291
3388
  type WebhookSecretRotated = WebhookCreated & {
1292
3389
  /** Until this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then. */
1293
3390
  previous_secret_expires_at: string;
@@ -1308,22 +3405,104 @@ type WebhookUpdate = {
1308
3405
  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 & {})>;
1309
3406
  name?: string;
1310
3407
  status?: "enabled" | "disabled";
3408
+ /** `email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it. */
3409
+ include_text?: boolean;
3410
+ };
3411
+ type Whoami = {
3412
+ object: "whoami";
3413
+ workspace: {
3414
+ /** The workspace's id (`ws_…`). */
3415
+ id: string;
3416
+ name: string;
3417
+ slug: string;
3418
+ };
3419
+ /** The organization the workspace belongs to. A key still reaches only its own workspace. */
3420
+ organization?: {
3421
+ /** The organization's id (`org_…`). */
3422
+ id: string;
3423
+ name: string;
3424
+ };
3425
+ /** Never the secret. */
3426
+ credential: {
3427
+ /** An API key, or a sign-in through OAuth (the CLI, an MCP client). */
3428
+ type: "api_key" | "oauth";
3429
+ /** The API key's id (`key_…`); null for a sign-in. */
3430
+ id: string | null;
3431
+ /** The API key's name; null for a sign-in. */
3432
+ name: string | null;
3433
+ /** The key's non-secret display prefix (e.g. `pk_live_a1b2`); null for a sign-in. */
3434
+ prefix: string | null;
3435
+ /** The preset the key was made with; `capabilities` is what it may do. Null for a sign-in. */
3436
+ scope: "full" | "sending" | "read_only" | null;
3437
+ created_at: string | null;
3438
+ last_used_at: string | null;
3439
+ /** The OAuth app a sign-in came from; null for a key. */
3440
+ client_id: string | null;
3441
+ client_name: string | null;
3442
+ /** The member a sign-in acts for (name, or email); null for a key. */
3443
+ user: string | null;
3444
+ };
3445
+ /** What this credential may do, after every clamp: a call that needs another one answers 403 `insufficient_scope`. */
3446
+ capabilities: Array<string>;
3447
+ rate_limit: {
3448
+ /** Requests per window, shared by every credential of the workspace. */
3449
+ limit: number;
3450
+ /** The window's length, in seconds. */
3451
+ window_seconds: number;
3452
+ };
3453
+ };
3454
+ type Workspace$1 = {
3455
+ object: "workspace";
3456
+ id: string;
3457
+ name: string;
3458
+ slug: string;
3459
+ /** The workspace image (its avatar in the dashboard). */
3460
+ image_url: string | null;
3461
+ };
3462
+ type WorkspaceKeyMint = {
3463
+ name: string;
3464
+ scope?: "full" | "sending" | "read_only";
3465
+ /** Capabilities no scope grants, added to the scope's. `sms:purchase` only on a workspace the organization pays for that has an SMS purchases cap. */
3466
+ opt_in_capabilities?: Array<"sms:purchase">;
3467
+ };
3468
+ type WorkspaceUpdate = {
3469
+ /** The workspace's new name. */
3470
+ name: string;
1311
3471
  };
1312
3472
 
3473
+ type models_Activity = Activity;
1313
3474
  type models_ApiKey = ApiKey;
1314
3475
  type models_ApiKeyCreate = ApiKeyCreate;
1315
3476
  type models_ApiKeyCreated = ApiKeyCreated;
3477
+ type models_ApiKeyUsage = ApiKeyUsage;
1316
3478
  type models_Batch = Batch;
1317
3479
  type models_BatchSend = BatchSend;
1318
3480
  type models_BatchSendResult = BatchSendResult;
3481
+ type models_BrandImport = BrandImport;
3482
+ type models_BrandImportAccept = BrandImportAccept;
3483
+ type models_BrandImportAccepted = BrandImportAccepted;
3484
+ type models_BrandImportCreate = BrandImportCreate;
1319
3485
  type models_BrandKit = BrandKit;
3486
+ type models_BrandKitCreate = BrandKitCreate;
3487
+ type models_BrandKitGraphicAdd = BrandKitGraphicAdd;
3488
+ type models_BrandKitGraphicAdded = BrandKitGraphicAdded;
1320
3489
  type models_BrandKitList = BrandKitList;
3490
+ type models_BrandKitUpdate = BrandKitUpdate;
3491
+ type models_BrandingUpdate = BrandingUpdate;
1321
3492
  type models_Campaign = Campaign;
3493
+ type models_CampaignAffectedRecipient = CampaignAffectedRecipient;
1322
3494
  type models_CampaignCreate = CampaignCreate;
3495
+ type models_CampaignDuplicate = CampaignDuplicate;
3496
+ type models_CampaignQualityRemoval = CampaignQualityRemoval;
3497
+ type models_CampaignRecipient = CampaignRecipient;
1323
3498
  type models_CampaignReschedule = CampaignReschedule;
3499
+ type models_CampaignReviewRequest = CampaignReviewRequest;
1324
3500
  type models_CampaignSend = CampaignSend;
3501
+ type models_CampaignStats = CampaignStats;
1325
3502
  type models_CampaignUpdate = CampaignUpdate;
1326
3503
  type models_Contact = Contact;
3504
+ type models_ContactActivity = ContactActivity;
3505
+ type models_ContactAddress = ContactAddress;
1327
3506
  type models_ContactCreate = ContactCreate;
1328
3507
  type models_ContactField = ContactField;
1329
3508
  type models_ContactFieldCreate = ContactFieldCreate;
@@ -1331,66 +3510,162 @@ type models_ContactFieldRename = ContactFieldRename;
1331
3510
  type models_ContactFieldUpdate = ContactFieldUpdate;
1332
3511
  type models_ContactImport = ContactImport;
1333
3512
  type models_ContactImportCreate = ContactImportCreate;
3513
+ type models_ContactSegment = ContactSegment;
3514
+ type models_ContactSetField = ContactSetField;
1334
3515
  type models_ContactTopic = ContactTopic;
3516
+ type models_ContactTopicList = ContactTopicList;
1335
3517
  type models_ContactTopicSet = ContactTopicSet;
3518
+ type models_ContactTopicsUpdate = ContactTopicsUpdate;
1336
3519
  type models_ContactUpdate = ContactUpdate;
3520
+ type models_ContactsExport = ContactsExport;
1337
3521
  type models_Domain = Domain;
1338
3522
  type models_DomainCreate = DomainCreate;
1339
3523
  type models_DomainDiagnosis = DomainDiagnosis;
1340
3524
  type models_DomainUpdate = DomainUpdate;
3525
+ type models_EmailEvent = EmailEvent;
1341
3526
  type models_EmailPatch = EmailPatch;
1342
3527
  type models_EmailStats = EmailStats;
3528
+ type models_EmailThread = EmailThread;
3529
+ type models_EmailThreadDeleted = EmailThreadDeleted;
3530
+ type models_EmailThreadDetail = EmailThreadDetail;
3531
+ type models_EmailThreadReplyRequest = EmailThreadReplyRequest;
3532
+ type models_EmailThreadReplyResult = EmailThreadReplyResult;
3533
+ type models_File = File;
3534
+ type models_FileCreate = FileCreate;
3535
+ type models_ImageUpload = ImageUpload;
1343
3536
  type models_Job = Job;
3537
+ type models_JobDownload = JobDownload;
3538
+ type models_LibraryImage = LibraryImage;
3539
+ type models_LibraryImageCreate = LibraryImageCreate;
3540
+ type models_LibraryImageUpdate = LibraryImageUpdate;
3541
+ type models_MintedWorkspaceKey = MintedWorkspaceKey;
3542
+ type models_OrganizationPlanQuote = OrganizationPlanQuote;
3543
+ type models_OrganizationPlanQuoteConfirm = OrganizationPlanQuoteConfirm;
3544
+ type models_OrganizationPlanQuoteCreate = OrganizationPlanQuoteCreate;
3545
+ type models_OrganizationPlanStop = OrganizationPlanStop;
3546
+ type models_OrganizationSharedPlanRemoval = OrganizationSharedPlanRemoval;
3547
+ type models_OrganizationSharedPlanWorkspace = OrganizationSharedPlanWorkspace;
3548
+ type models_OrganizationSharedPlanWorkspaceAdd = OrganizationSharedPlanWorkspaceAdd;
3549
+ type models_OrganizationSharedPlanWorkspaceUpdate = OrganizationSharedPlanWorkspaceUpdate;
3550
+ type models_OrganizationWebhookDelivery = OrganizationWebhookDelivery;
3551
+ type models_OrganizationWorkspace = OrganizationWorkspace;
3552
+ type models_OrganizationWorkspaceCreate = OrganizationWorkspaceCreate;
3553
+ type models_OrganizationWorkspaceUpdate = OrganizationWorkspaceUpdate;
3554
+ type models_OrganizationWorkspaceUsage = OrganizationWorkspaceUsage;
1344
3555
  type models_ReceivedAttachmentUrl = ReceivedAttachmentUrl;
1345
3556
  type models_ReceivedEmail = ReceivedEmail;
3557
+ type models_ReceivedEmailRaw = ReceivedEmailRaw;
1346
3558
  type models_ReceivedEmailSummary = ReceivedEmailSummary;
3559
+ type models_RequestLog = RequestLog;
1347
3560
  type models_Segment = Segment;
1348
3561
  type models_SegmentCreate = SegmentCreate;
1349
3562
  type models_SegmentMember = SegmentMember;
1350
3563
  type models_SegmentMemberAdd = SegmentMemberAdd;
3564
+ type models_SegmentMemberAddBody = SegmentMemberAddBody;
3565
+ type models_SegmentMemberUpdate = SegmentMemberUpdate;
3566
+ type models_SegmentMembersAdd = SegmentMembersAdd;
3567
+ type models_SegmentMembersAdded = SegmentMembersAdded;
3568
+ type models_SegmentPreview = SegmentPreview;
3569
+ type models_SegmentPreviewRequest = SegmentPreviewRequest;
1351
3570
  type models_SegmentUpdate = SegmentUpdate;
1352
3571
  type models_SendEmail = SendEmail;
1353
3572
  type models_SendResult = SendResult;
3573
+ type models_Sender = Sender;
3574
+ type models_SenderCreate = SenderCreate;
3575
+ type models_SenderUpdate = SenderUpdate;
3576
+ type models_SmsAddContact = SmsAddContact;
3577
+ type models_SmsBillableResource = SmsBillableResource;
1354
3578
  type models_SmsBrand = SmsBrand;
3579
+ type models_SmsBrandCreate = SmsBrandCreate;
3580
+ type models_SmsBrandDocument = SmsBrandDocument;
3581
+ type models_SmsBrandDocumentCreate = SmsBrandDocumentCreate;
3582
+ type models_SmsBrandDocumentDeleted = SmsBrandDocumentDeleted;
3583
+ type models_SmsBrandDocumentUrl = SmsBrandDocumentUrl;
3584
+ type models_SmsBrandPatch = SmsBrandPatch;
1355
3585
  type models_SmsCampaign = SmsCampaign;
1356
3586
  type models_SmsCampaignCreate = SmsCampaignCreate;
3587
+ type models_SmsCampaignRecipient = SmsCampaignRecipient;
1357
3588
  type models_SmsCampaignReschedule = SmsCampaignReschedule;
3589
+ type models_SmsCampaignResubmit = SmsCampaignResubmit;
1358
3590
  type models_SmsCampaignSend = SmsCampaignSend;
1359
3591
  type models_SmsCampaignUpdate = SmsCampaignUpdate;
1360
3592
  type models_SmsCampaignValidation = SmsCampaignValidation;
1361
3593
  type models_SmsConsent = SmsConsent;
1362
3594
  type models_SmsConsentRecord = SmsConsentRecord;
1363
3595
  type models_SmsConsentRecorded = SmsConsentRecorded;
3596
+ type models_SmsConsentSetup = SmsConsentSetup;
3597
+ type models_SmsJoinKeyword = SmsJoinKeyword;
3598
+ type models_SmsJoinKeywordCreate = SmsJoinKeywordCreate;
3599
+ type models_SmsJoinKeywordCreated = SmsJoinKeywordCreated;
3600
+ type models_SmsJoinKeywordList = SmsJoinKeywordList;
3601
+ type models_SmsMessagingProgram = SmsMessagingProgram;
3602
+ type models_SmsMessagingProgramCreate = SmsMessagingProgramCreate;
3603
+ type models_SmsMessagingProgramUpdate = SmsMessagingProgramUpdate;
1364
3604
  type models_SmsNumber = SmsNumber;
3605
+ type models_SmsNumberRelease = SmsNumberRelease;
3606
+ type models_SmsNumberRequest = SmsNumberRequest;
3607
+ type models_SmsNumberResubmission = SmsNumberResubmission;
3608
+ type models_SmsNumberRetry = SmsNumberRetry;
3609
+ type models_SmsOptInRequest = SmsOptInRequest;
1365
3610
  type models_SmsPatch = SmsPatch;
3611
+ type models_SmsQuote = SmsQuote;
3612
+ type models_SmsQuoteConfirm = SmsQuoteConfirm;
3613
+ type models_SmsQuoteCreate = SmsQuoteCreate;
3614
+ type models_SmsRegistration = SmsRegistration;
3615
+ type models_SmsRegistrationRemove = SmsRegistrationRemove;
3616
+ type models_SmsRegistrationReplace = SmsRegistrationReplace;
3617
+ type models_SmsRegistrationResubmission = SmsRegistrationResubmission;
1366
3618
  type models_SmsSend = SmsSend;
1367
3619
  type models_SmsStats = SmsStats;
1368
3620
  type models_SmsTemplate = SmsTemplate;
1369
3621
  type models_SmsTemplateCreate = SmsTemplateCreate;
3622
+ type models_SmsTemplateTestSend = SmsTemplateTestSend;
3623
+ type models_SmsTemplateTestSendResult = SmsTemplateTestSendResult;
1370
3624
  type models_SmsTemplateUpdate = SmsTemplateUpdate;
3625
+ type models_SmsTemplateUsage = SmsTemplateUsage;
3626
+ type models_SmsTestDestination = SmsTestDestination;
3627
+ type models_SmsTollFreeResubmit = SmsTollFreeResubmit;
3628
+ type models_SpendCapsUpdate = SpendCapsUpdate;
1371
3629
  type models_Suppression = Suppression;
1372
3630
  type models_SuppressionBulkResult = SuppressionBulkResult;
1373
3631
  type models_SuppressionCreate = SuppressionCreate;
1374
3632
  type models_Template = Template;
1375
3633
  type models_TemplateCreate = TemplateCreate;
3634
+ type models_TemplateDuplicate = TemplateDuplicate;
3635
+ type models_TemplateFromLibrary = TemplateFromLibrary;
3636
+ type models_TemplateRender = TemplateRender;
3637
+ type models_TemplateRenderInput = TemplateRenderInput;
1376
3638
  type models_TemplateTestSend = TemplateTestSend;
1377
3639
  type models_TemplateTestSendResult = TemplateTestSendResult;
1378
3640
  type models_TemplateUpdate = TemplateUpdate;
3641
+ type models_TemplateUsage = TemplateUsage;
3642
+ type models_TemplateVersion = TemplateVersion;
1379
3643
  type models_Topic = Topic;
1380
3644
  type models_TopicCreate = TopicCreate;
3645
+ type models_TopicOptOut = TopicOptOut;
1381
3646
  type models_TopicUpdate = TopicUpdate;
1382
3647
  type models_Webhook = Webhook;
1383
3648
  type models_WebhookCreate = WebhookCreate;
1384
3649
  type models_WebhookCreated = WebhookCreated;
1385
3650
  type models_WebhookDelivery = WebhookDelivery;
3651
+ type models_WebhookDeliveryReplay = WebhookDeliveryReplay;
3652
+ type models_WebhookFlush = WebhookFlush;
3653
+ type models_WebhookFlushResult = WebhookFlushResult;
1386
3654
  type models_WebhookSecretRotated = WebhookSecretRotated;
1387
3655
  type models_WebhookTestResult = WebhookTestResult;
1388
3656
  type models_WebhookUpdate = WebhookUpdate;
3657
+ type models_Whoami = Whoami;
3658
+ type models_WorkspaceKeyMint = WorkspaceKeyMint;
3659
+ type models_WorkspaceUpdate = WorkspaceUpdate;
1389
3660
  declare namespace models {
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 };
3661
+ export type { models_Activity as Activity, models_ApiKey as ApiKey, models_ApiKeyCreate as ApiKeyCreate, models_ApiKeyCreated as ApiKeyCreated, models_ApiKeyUsage as ApiKeyUsage, models_Batch as Batch, models_BatchSend as BatchSend, models_BatchSendResult as BatchSendResult, models_BrandImport as BrandImport, models_BrandImportAccept as BrandImportAccept, models_BrandImportAccepted as BrandImportAccepted, models_BrandImportCreate as BrandImportCreate, models_BrandKit as BrandKit, models_BrandKitCreate as BrandKitCreate, models_BrandKitGraphicAdd as BrandKitGraphicAdd, models_BrandKitGraphicAdded as BrandKitGraphicAdded, models_BrandKitList as BrandKitList, models_BrandKitUpdate as BrandKitUpdate, Branding$1 as Branding, models_BrandingUpdate as BrandingUpdate, models_Campaign as Campaign, models_CampaignAffectedRecipient as CampaignAffectedRecipient, models_CampaignCreate as CampaignCreate, models_CampaignDuplicate as CampaignDuplicate, models_CampaignQualityRemoval as CampaignQualityRemoval, models_CampaignRecipient as CampaignRecipient, models_CampaignReschedule as CampaignReschedule, models_CampaignReviewRequest as CampaignReviewRequest, models_CampaignSend as CampaignSend, models_CampaignStats as CampaignStats, models_CampaignUpdate as CampaignUpdate, models_Contact as Contact, models_ContactActivity as ContactActivity, models_ContactAddress as ContactAddress, 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_ContactSegment as ContactSegment, models_ContactSetField as ContactSetField, models_ContactTopic as ContactTopic, models_ContactTopicList as ContactTopicList, models_ContactTopicSet as ContactTopicSet, models_ContactTopicsUpdate as ContactTopicsUpdate, models_ContactUpdate as ContactUpdate, models_ContactsExport as ContactsExport, models_Domain as Domain, models_DomainCreate as DomainCreate, models_DomainDiagnosis as DomainDiagnosis, models_DomainUpdate as DomainUpdate, Email$1 as Email, models_EmailEvent as EmailEvent, models_EmailPatch as EmailPatch, models_EmailStats as EmailStats, models_EmailThread as EmailThread, models_EmailThreadDeleted as EmailThreadDeleted, models_EmailThreadDetail as EmailThreadDetail, models_EmailThreadReplyRequest as EmailThreadReplyRequest, models_EmailThreadReplyResult as EmailThreadReplyResult, Error$1 as Error, models_File as File, models_FileCreate as FileCreate, models_ImageUpload as ImageUpload, models_Job as Job, models_JobDownload as JobDownload, models_LibraryImage as LibraryImage, models_LibraryImageCreate as LibraryImageCreate, models_LibraryImageUpdate as LibraryImageUpdate, models_MintedWorkspaceKey as MintedWorkspaceKey, models_OrganizationPlanQuote as OrganizationPlanQuote, models_OrganizationPlanQuoteConfirm as OrganizationPlanQuoteConfirm, models_OrganizationPlanQuoteCreate as OrganizationPlanQuoteCreate, models_OrganizationPlanStop as OrganizationPlanStop, OrganizationSharedPlan$1 as OrganizationSharedPlan, models_OrganizationSharedPlanRemoval as OrganizationSharedPlanRemoval, models_OrganizationSharedPlanWorkspace as OrganizationSharedPlanWorkspace, models_OrganizationSharedPlanWorkspaceAdd as OrganizationSharedPlanWorkspaceAdd, models_OrganizationSharedPlanWorkspaceUpdate as OrganizationSharedPlanWorkspaceUpdate, models_OrganizationWebhookDelivery as OrganizationWebhookDelivery, models_OrganizationWorkspace as OrganizationWorkspace, models_OrganizationWorkspaceCreate as OrganizationWorkspaceCreate, models_OrganizationWorkspaceUpdate as OrganizationWorkspaceUpdate, models_OrganizationWorkspaceUsage as OrganizationWorkspaceUsage, models_ReceivedAttachmentUrl as ReceivedAttachmentUrl, models_ReceivedEmail as ReceivedEmail, models_ReceivedEmailRaw as ReceivedEmailRaw, models_ReceivedEmailSummary as ReceivedEmailSummary, models_RequestLog as RequestLog, models_Segment as Segment, models_SegmentCreate as SegmentCreate, models_SegmentMember as SegmentMember, models_SegmentMemberAdd as SegmentMemberAdd, models_SegmentMemberAddBody as SegmentMemberAddBody, models_SegmentMemberUpdate as SegmentMemberUpdate, models_SegmentMembersAdd as SegmentMembersAdd, models_SegmentMembersAdded as SegmentMembersAdded, models_SegmentPreview as SegmentPreview, models_SegmentPreviewRequest as SegmentPreviewRequest, models_SegmentUpdate as SegmentUpdate, models_SendEmail as SendEmail, models_SendResult as SendResult, models_Sender as Sender, models_SenderCreate as SenderCreate, models_SenderUpdate as SenderUpdate, Sms$1 as Sms, models_SmsAddContact as SmsAddContact, models_SmsBillableResource as SmsBillableResource, models_SmsBrand as SmsBrand, models_SmsBrandCreate as SmsBrandCreate, models_SmsBrandDocument as SmsBrandDocument, models_SmsBrandDocumentCreate as SmsBrandDocumentCreate, models_SmsBrandDocumentDeleted as SmsBrandDocumentDeleted, models_SmsBrandDocumentUrl as SmsBrandDocumentUrl, models_SmsBrandPatch as SmsBrandPatch, models_SmsCampaign as SmsCampaign, models_SmsCampaignCreate as SmsCampaignCreate, models_SmsCampaignRecipient as SmsCampaignRecipient, models_SmsCampaignReschedule as SmsCampaignReschedule, models_SmsCampaignResubmit as SmsCampaignResubmit, 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_SmsConsentSetup as SmsConsentSetup, models_SmsJoinKeyword as SmsJoinKeyword, models_SmsJoinKeywordCreate as SmsJoinKeywordCreate, models_SmsJoinKeywordCreated as SmsJoinKeywordCreated, models_SmsJoinKeywordList as SmsJoinKeywordList, models_SmsMessagingProgram as SmsMessagingProgram, models_SmsMessagingProgramCreate as SmsMessagingProgramCreate, models_SmsMessagingProgramUpdate as SmsMessagingProgramUpdate, models_SmsNumber as SmsNumber, models_SmsNumberRelease as SmsNumberRelease, models_SmsNumberRequest as SmsNumberRequest, models_SmsNumberResubmission as SmsNumberResubmission, models_SmsNumberRetry as SmsNumberRetry, models_SmsOptInRequest as SmsOptInRequest, models_SmsPatch as SmsPatch, models_SmsQuote as SmsQuote, models_SmsQuoteConfirm as SmsQuoteConfirm, models_SmsQuoteCreate as SmsQuoteCreate, models_SmsRegistration as SmsRegistration, models_SmsRegistrationRemove as SmsRegistrationRemove, models_SmsRegistrationReplace as SmsRegistrationReplace, models_SmsRegistrationResubmission as SmsRegistrationResubmission, models_SmsSend as SmsSend, models_SmsStats as SmsStats, models_SmsTemplate as SmsTemplate, models_SmsTemplateCreate as SmsTemplateCreate, models_SmsTemplateTestSend as SmsTemplateTestSend, models_SmsTemplateTestSendResult as SmsTemplateTestSendResult, models_SmsTemplateUpdate as SmsTemplateUpdate, models_SmsTemplateUsage as SmsTemplateUsage, models_SmsTestDestination as SmsTestDestination, models_SmsTollFreeResubmit as SmsTollFreeResubmit, SpendCaps$1 as SpendCaps, models_SpendCapsUpdate as SpendCapsUpdate, models_Suppression as Suppression, models_SuppressionBulkResult as SuppressionBulkResult, models_SuppressionCreate as SuppressionCreate, models_Template as Template, models_TemplateCreate as TemplateCreate, models_TemplateDuplicate as TemplateDuplicate, models_TemplateFromLibrary as TemplateFromLibrary, models_TemplateRender as TemplateRender, models_TemplateRenderInput as TemplateRenderInput, models_TemplateTestSend as TemplateTestSend, models_TemplateTestSendResult as TemplateTestSendResult, models_TemplateUpdate as TemplateUpdate, models_TemplateUsage as TemplateUsage, models_TemplateVersion as TemplateVersion, models_Topic as Topic, models_TopicCreate as TopicCreate, models_TopicOptOut as TopicOptOut, 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_WebhookDeliveryReplay as WebhookDeliveryReplay, models_WebhookFlush as WebhookFlush, models_WebhookFlushResult as WebhookFlushResult, models_WebhookSecretRotated as WebhookSecretRotated, models_WebhookTestResult as WebhookTestResult, models_WebhookUpdate as WebhookUpdate, models_Whoami as Whoami, Workspace$1 as Workspace, models_WorkspaceKeyMint as WorkspaceKeyMint, models_WorkspaceUpdate as WorkspaceUpdate };
1391
3662
  }
1392
3663
 
1393
- /** Filters for `sms.list` / `sms.listAll`. */
3664
+ /**
3665
+ * Filters for `sms.list` / `sms.listAll`. A `q`, `type` or `sender_id` value
3666
+ * the list can't apply is ignored and named in the `Unitpost-Warning`
3667
+ * response header; `Unitpost-Strict: true` refuses it instead.
3668
+ */
1394
3669
  type SmsListParams = ListParams & {
1395
3670
  direction?: "inbound" | "outbound";
1396
3671
  status?: string;
@@ -1402,11 +3677,175 @@ type SmsListParams = ListParams & {
1402
3677
  campaign_id?: string;
1403
3678
  created_after?: string;
1404
3679
  created_before?: string;
3680
+ /**
3681
+ * Search the message text; 3 or more digits also match either number, as
3682
+ * the dashboard's Messages log searches. At most 200 characters.
3683
+ */
3684
+ q?: string;
3685
+ type?: "transactional" | "marketing";
3686
+ /** A number's `snum_…` id (from `sms.numbers()`): its texts, both directions. */
3687
+ sender_id?: string;
3688
+ /**
3689
+ * Only texts sent with these tags, `name:value`: a comma-separated string
3690
+ * (`"customer:acme,flow:reminders"`) or an array, all of which must match.
3691
+ * Received texts have none.
3692
+ */
3693
+ tag?: string | string[];
1405
3694
  };
1406
- type Result<T> = Promise<{
1407
- data: T | null;
1408
- error: UnitpostError | null;
1409
- }>;
3695
+ /**
3696
+ * Filters for `email.list` / `email.listAll`. A `q`, `source` or `outcome`
3697
+ * value the list can't apply is ignored and named in the `Unitpost-Warning`
3698
+ * response header; `Unitpost-Strict: true` refuses it instead.
3699
+ */
3700
+ type EmailListParams = ListParams & {
3701
+ status?: string;
3702
+ /** Only emails to this recipient address. */
3703
+ to?: string;
3704
+ /** Only emails to this contact (`con_…`). */
3705
+ contact_id?: string;
3706
+ campaign_id?: string;
3707
+ batch_id?: string;
3708
+ created_after?: string;
3709
+ created_before?: string;
3710
+ /**
3711
+ * An exact recipient address, or part of the subject or the sender
3712
+ * (case-insensitive), as the dashboard's Sent table searches. At most 200
3713
+ * characters.
3714
+ */
3715
+ q?: string;
3716
+ /** How the email was sent (`test`: a test send; `reply`: from the inbox). */
3717
+ source?: "api" | "smtp" | "test" | "batch" | "campaign" | "reply";
3718
+ /**
3719
+ * What happened, as a campaign's Emails tab filters (engagement overlaps
3720
+ * delivery; `failed` includes suppressed and canceled). With `campaign_id`:
3721
+ * who opened or clicked that campaign.
3722
+ */
3723
+ outcome?: "delivered" | "opened" | "clicked" | "unsubscribed" | "bounced" | "complained" | "failed" | "pending";
3724
+ };
3725
+ /**
3726
+ * Filters for `workspace.listActivity` / `workspace.listAllActivity`. An
3727
+ * unknown key is a `422`.
3728
+ */
3729
+ type ActivityListParams = ListParams & {
3730
+ /** Only changes to this kind of record. */
3731
+ subject?: Activity["subject"];
3732
+ /** With `subject`: one record's changes (its id, e.g. `dom_…`). */
3733
+ subject_id?: string;
3734
+ /** One contact's timeline (`con_…`). */
3735
+ contact_id?: string;
3736
+ /** A campaign's changes and what it led to, e.g. unsubscribes through it (`cmp_…`). */
3737
+ campaign_id?: string;
3738
+ /** Part of the record's name or the actor's (case-insensitive), at most 200 characters. */
3739
+ q?: string;
3740
+ /** `email`: without the SMS rows. */
3741
+ channel?: "email";
3742
+ };
3743
+ /**
3744
+ * Filters for `logs.list`. An unknown key, or one given twice, is a `422`.
3745
+ */
3746
+ type LogListParams = ListParams & {
3747
+ /** A status code (e.g. `429`) or a class: `2xx`, `3xx`, `4xx` or `5xx`. */
3748
+ status?: number | `${number}` | "2xx" | "3xx" | "4xx" | "5xx";
3749
+ /** Only one API key's calls (`key_…`). */
3750
+ api_key_id?: string;
3751
+ /** Only one HTTP method. */
3752
+ method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
3753
+ /** Only paths starting with this, as in the API reference (e.g. `/email/campaigns`), at most 200 characters. */
3754
+ path_prefix?: string;
3755
+ /** One call, by the `x-request-id` its response carried. */
3756
+ request_id?: string;
3757
+ /** Calls at or after this time (ISO 8601 with `Z` or an offset). */
3758
+ created_after?: string;
3759
+ /** Calls before this time (ISO 8601 with `Z` or an offset). */
3760
+ created_before?: string;
3761
+ };
3762
+ /**
3763
+ * Filters for `suppressions.list` / `suppressions.listAll`. The list ignored
3764
+ * them before, so a value it can't apply is ignored and named in the
3765
+ * `Unitpost-Warning` response header (the list answers as without it);
3766
+ * `Unitpost-Strict: true` refuses it instead.
3767
+ */
3768
+ type SuppressionListParams = ListParams & {
3769
+ /** Part of the email address (case-insensitive), at most 200 characters. */
3770
+ q?: string;
3771
+ /** Only suppressions with this reason. */
3772
+ reason?: "bounce" | "complaint" | "unsubscribe" | "manual" | "import" | "api";
3773
+ /** Only suppressions created at or after this time (ISO 8601 with `Z` or an offset). */
3774
+ created_after?: string;
3775
+ /** Only suppressions created before this time (ISO 8601 with `Z` or an offset). */
3776
+ created_before?: string;
3777
+ /** @deprecated Ignored since 2026-10-13: the list is always your own suppressions. */
3778
+ scope?: "workspace" | "platform";
3779
+ };
3780
+ /**
3781
+ * Filters for `webhooks.listDeliveries` / `webhooks.listAllDeliveries`. The
3782
+ * log ignored them before, so a value it can't apply is ignored and named in
3783
+ * the `Unitpost-Warning` response header (the list answers as without it);
3784
+ * `Unitpost-Strict: true` refuses it instead.
3785
+ */
3786
+ type WebhookDeliveryListParams = ListParams & {
3787
+ /**
3788
+ * One or more delivery statuses, comma-separated: `pending`, `queued`,
3789
+ * `retrying`, `succeeded`, `failed`, `exhausted` (e.g. `"failed,exhausted"`).
3790
+ */
3791
+ status?: string;
3792
+ /** Only deliveries of this event type, e.g. `email.bounced`. */
3793
+ event_type?: string;
3794
+ };
3795
+ /**
3796
+ * The window for `email.stats`: the last `days`, or a period (`from` / `to`).
3797
+ * A value the API can't apply is ignored and named in the `Unitpost-Warning`
3798
+ * response header; `Unitpost-Strict: true` refuses it instead.
3799
+ */
3800
+ type EmailStatsParams = {
3801
+ /** Window size in days (1–365); defaults to 30 server-side. */
3802
+ days?: number;
3803
+ /** Start of a period, with `to`, instead of `days` (ISO 8601 with `Z` or an offset; not in the future). */
3804
+ from?: string;
3805
+ /**
3806
+ * End of the period, exclusive: at most 365 days after `from`; with
3807
+ * `grain`, at most 6 hours (`5m`), 3 days (`1h`) or 93 days (`1d`).
3808
+ */
3809
+ to?: string;
3810
+ /** With `from` and `to`: also return `series`, the send volume per bucket. */
3811
+ grain?: "5m" | "1h" | "1d";
3812
+ /** With `grain`: the IANA time zone the buckets are keyed in (default `UTC`). */
3813
+ tz?: string;
3814
+ /** Count only emails sent from this sending domain (`dom_…`). */
3815
+ domain_id?: string;
3816
+ };
3817
+ /** Filters for `contacts.list` / `contacts.listAll`. */
3818
+ type ContactListParams = ListParams & {
3819
+ /** Search email, first and last name; 3 or more digits also match the SMS number. */
3820
+ q?: string;
3821
+ /** The contact-level marketing opt-out. */
3822
+ status?: "subscribed" | "unsubscribed";
3823
+ /** `has`: contacts with an SMS number; `none`: without one. */
3824
+ phone?: "has" | "none";
3825
+ /** Only members of this segment. */
3826
+ segment_id?: string;
3827
+ /** With a static `segment_id`: subscribed to, or opted out of, that segment's sends. */
3828
+ segment_subscription?: "subscribed" | "opted_out";
3829
+ };
3830
+ /** `files.list` filters. */
3831
+ type FileListParams = ListParams & {
3832
+ /** Only the files made for this purpose. */
3833
+ purpose?: File["purpose"];
3834
+ };
3835
+ /** What `files.upload` sends: a local `path` or the bytes in `data`. */
3836
+ interface FileUploadInput {
3837
+ /** A local file to read (Node's `fs`). Give this or `data`. */
3838
+ path?: string;
3839
+ /** The bytes, when you already hold them (a `Buffer` works). Give this or `path`. */
3840
+ data?: Uint8Array;
3841
+ /** What the file is for, which sets what it may be and how big. */
3842
+ purpose: FileCreate["purpose"];
3843
+ /** The file's type. The API checks it against the bytes. */
3844
+ contentType: NonNullable<FileCreate["content_type"]>;
3845
+ /** A name for the file. Defaults to `path`'s base name. */
3846
+ filename?: string;
3847
+ }
3848
+ type Result<T> = Promise<ApiResult<T>>;
1410
3849
  interface SendOptions {
1411
3850
  idempotencyKey?: string;
1412
3851
  }
@@ -1421,6 +3860,18 @@ declare class Sms extends Resource {
1421
3860
  readonly campaigns: SmsCampaigns;
1422
3861
  /** SMS subscription topics (independent from email topics). */
1423
3862
  readonly topics: SmsTopics;
3863
+ /** Messaging programs: what a sender registration says your texts are for. */
3864
+ readonly messagingPrograms: SmsMessagingPrograms;
3865
+ /** The verified numbers a template test may text. */
3866
+ readonly testDestinations: SmsTestDestinations;
3867
+ /** Where and how people opt in to your texts. */
3868
+ readonly consentSetups: SmsConsentSetups;
3869
+ /** What the workspace pays for SMS every month. */
3870
+ readonly billing: SmsBilling;
3871
+ /** Carrier registrations, their review state, and fixing what carriers sent back. */
3872
+ readonly registrations: SmsRegistrations;
3873
+ /** Buy carrier resources: price an order, then confirm it. */
3874
+ readonly quotes: SmsQuotes;
1424
3875
  constructor(http: HttpClient);
1425
3876
  /**
1426
3877
  * Send or schedule an SMS message.
@@ -1433,6 +3884,18 @@ declare class Sms extends Resource {
1433
3884
  send(body: SmsSend, opts?: SendOptions): Result<Sms$1>;
1434
3885
  /** Retrieve one SMS message's status and delivery state. */
1435
3886
  get(id: string): Result<Sms$1>;
3887
+ /**
3888
+ * Make the sender of a received text a contact, or file the text under the
3889
+ * contact that already has the number. Phone only: no name and no consent
3890
+ * (texting a number isn't consent to marketing). Every earlier text with
3891
+ * that number that no contact holds is filed under the contact too, so
3892
+ * `contact_id` reads it from then on. Answers the contact: `201` when it is
3893
+ * new, `200` when it existed, so a retry is safe. It counts against the
3894
+ * plan's contacts (`403 limit_reached` when full), and a number that texted
3895
+ * STOP stays opted out. A text you sent is refused (`409`). Needs
3896
+ * `contacts:write` and `sms:read`.
3897
+ */
3898
+ addContact(id: string): Result<Contact>;
1436
3899
  /**
1437
3900
  * Cancel a queued/scheduled SMS (`{ cancel: true }` — its reserved credit is
1438
3901
  * refunded) or move a scheduled one (`{ scheduled_at }`).
@@ -1454,21 +3917,121 @@ declare class Sms extends Resource {
1454
3917
  * `status` says whether you or the carrier is the blocker, and `missing`
1455
3918
  * lists exactly what is still required.
1456
3919
  *
1457
- * Read-only — creating a brand is a paid carrier submission and is only
1458
- * available in the dashboard.
3920
+ * Create and edit a brand with `createBrand` / `updateBrand` (free).
3921
+ * Registering it with carriers is a paid order: `sms.quotes.create` prices
3922
+ * it, `sms.quotes.confirm` places it. Needs `sms:read`.
1459
3923
  */
1460
3924
  brands(params?: ListParams): Result<ListResponse<SmsBrand>>;
1461
3925
  /**
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.
3926
+ * Create a brand (201): the business identity carriers register before
3927
+ * they approve a number. A draft may be partial (only `name` is required);
3928
+ * `missing` says what is still needed. Free, with no carrier call; one brand
3929
+ * per website domain (`409`). The tax id is write-only: stored encrypted,
3930
+ * read back as `tax_id_on_file`. Registering the brand with carriers is a
3931
+ * paid order through `sms.quotes`. Needs `sms:manage`. Pass an
3932
+ * `idempotencyKey` so a retry never makes a second brand; one is generated
3933
+ * when you don't.
3934
+ */
3935
+ createBrand(body: SmsBrandCreate, opts?: SendOptions): Result<SmsBrand>;
3936
+ /** One brand with every field you can edit, its `status` and `missing` list. Needs `sms:read`. */
3937
+ getBrand(id: string): Result<SmsBrand>;
3938
+ /**
3939
+ * Edit a brand: only the fields you send change, `null` clears an optional
3940
+ * one; send `{ archived }` alone to archive or restore it. The tax id is
3941
+ * write-only. A locked brand (`editable: false`: carriers are reviewing or
3942
+ * approved it, or it has numbers) refuses carrier-field edits with
3943
+ * `409 brand_locked`, `details` naming each field, except those a
3944
+ * correction request opened. Needs `sms:manage`.
3945
+ */
3946
+ updateBrand(id: string, body: SmsBrandPatch): Result<SmsBrand>;
3947
+ /**
3948
+ * A brand's documents (`sdoc_` ids): the files and numbers a country's
3949
+ * carriers ask for, one per slot (`kind`, plus `carrier` / `country` for a
3950
+ * variant). Needs `sms:read`.
3951
+ */
3952
+ listBrandDocuments(brandId: string): Result<ListResponse<SmsBrandDocument>>;
3953
+ /**
3954
+ * Add a document to a brand's slot (201): a file kind takes `file_id` (a
3955
+ * file from `files.create` / `files.upload`, purpose `sms_document`, or
3956
+ * `sms_opt_in_evidence` for `opt_in_screenshot`), a text kind takes `text`.
3957
+ * A document in an occupied slot replaces the current one. Needs
3958
+ * `sms:manage`. Pass an `idempotencyKey` so a retry adds one document; one
3959
+ * is generated when you don't.
3960
+ */
3961
+ addBrandDocument(brandId: string, body: SmsBrandDocumentCreate, opts?: SendOptions): Result<SmsBrandDocument>;
3962
+ /** One brand document. Needs `sms:read`. */
3963
+ getBrandDocument(brandId: string, documentId: string): Result<SmsBrandDocument>;
3964
+ /** Remove a brand document from its slot. Needs `sms:manage`. */
3965
+ removeBrandDocument(brandId: string, documentId: string): Result<SmsBrandDocumentDeleted>;
3966
+ /**
3967
+ * A 5-minute signed link to a file document's bytes. The link is a bearer
3968
+ * credential: fetch it yourself, don't log or share it. An identity
3969
+ * document needs `sms:manage`; the rest `sms:read`.
3970
+ */
3971
+ brandDocumentUrl(brandId: string, documentId: string): Result<SmsBrandDocumentUrl>;
3972
+ /**
3973
+ * List SMS phone numbers.
3974
+ *
3975
+ * Only numbers with `status: "active"` can send. A `ten_dlc` number has no
3976
+ * `phone_number` until carriers approve it, and a `simulator` number only
3977
+ * reaches verified test destinations.
1467
3978
  *
1468
- * Read-only — requesting or releasing a number is only available in the
1469
- * dashboard.
3979
+ * Order a number through `sms.quotes`; release one with `releaseNumber`.
1470
3980
  */
1471
3981
  numbers(params?: ListParams): Result<ListResponse<SmsNumber>>;
3982
+ /**
3983
+ * One number, or one country of a Sender ID (`snum_…`), as `numbers()`
3984
+ * reads it: its status, what carriers sent back (`feedback`) and its use
3985
+ * case. Read a resubmit, a retry or a release back with it. Needs
3986
+ * `sms:read`.
3987
+ */
3988
+ getNumber(numberId: string): Result<SmsNumber>;
3989
+ /**
3990
+ * Release a number, or one country of a Sender ID, back to the carrier.
3991
+ * PERMANENT: it stops sending at once, reads `released` from then on and
3992
+ * can't be had back; its monthly fee ends with it (no proration), and a
3993
+ * 10DLC number's campaign registration goes with it. Refused while an
3994
+ * automation uses it (`409 resource_in_use`) and, unless `force: true`,
3995
+ * while campaigns are scheduled on it or texts are queued through it
3996
+ * (`409 sender_release_blocked`, counts in `error.blockers`). Releasing a
3997
+ * released number answers it. Needs `sms:manage`. Pass an `idempotencyKey`
3998
+ * so a retry releases once; one is generated when you don't.
3999
+ */
4000
+ releaseNumber(numberId: string, body?: SmsNumberRelease, opts?: SendOptions): Result<SmsNumber>;
4001
+ /**
4002
+ * Resubmit a toll-free verification carriers sent back (free): fix what
4003
+ * the number's `feedback` names, then send the new evidence
4004
+ * (`opt_in_evidence_file_id`, or `reuse_opt_in_evidence`), a
4005
+ * `business_registration_document_file_id`, `consent_source_url`, or
4006
+ * `acknowledge_unchanged`. Needs `sms:manage`. Pass an `idempotencyKey` so
4007
+ * a retry resubmits once; one is generated when you don't.
4008
+ */
4009
+ resubmitNumber(numberId: string, body: SmsTollFreeResubmit, opts?: SendOptions): Result<SmsNumberResubmission>;
4010
+ /**
4011
+ * Text-to-join: the words people can text this number (`snum_…`) to sign
4012
+ * up. `registration_warning` is set when the number's carrier registration
4013
+ * doesn't list keyword opt-in, so carriers could flag the sign-ups. Needs
4014
+ * `sms:read`.
4015
+ */
4016
+ listJoinKeywords(numberId: string): Result<SmsJoinKeywordList>;
4017
+ /**
4018
+ * Add a join keyword to a number. A text that is exactly this word (any
4019
+ * case) gets the double opt-in request ("Reply YES to get … texts"); the
4020
+ * YES records marketing consent, makes the texter a contact if they aren't
4021
+ * one, and adds them to `segment_id` (a static segment) and/or `topic_id`
4022
+ * (an SMS topic). A keyword is never consent by itself and never lifts a
4023
+ * STOP. STOP, HELP, START, YES and their variants are refused; at most 10
4024
+ * per number, and only on numbers people can text back. Answers the keyword
4025
+ * with `registration_warning`: `201` when added, `200` when the same keyword
4026
+ * with the same settings is already there, so a retry is safe (the same
4027
+ * word with other settings is `409`). Needs `sms:manage`.
4028
+ */
4029
+ addJoinKeyword(numberId: string, body: SmsJoinKeywordCreate): Result<SmsJoinKeywordCreated>;
4030
+ /**
4031
+ * Remove a join keyword (`sjk_…`): it stops answering. People who already
4032
+ * joined keep their consent, contact and memberships. Needs `sms:manage`.
4033
+ */
4034
+ removeJoinKeyword(numberId: string, keywordId: string): Result<null>;
1472
4035
  /**
1473
4036
  * SMS delivery stats over a rolling window: queued, sent, delivered,
1474
4037
  * failed, suppressed, canceled, inbound and segments billed, with delivery,
@@ -1483,6 +4046,12 @@ declare class Sms extends Resource {
1483
4046
  smsConsent(contactId: string): Result<SmsConsent>;
1484
4047
  /** Record an SMS consent change (opt-in or opt-out) for a contact. */
1485
4048
  recordSmsConsent(contactId: string, body: SmsConsentRecord): Result<SmsConsentRecorded>;
4049
+ /**
4050
+ * Text the contact a request to reply YES to confirm marketing texts. It
4051
+ * sends a real text, so pass an `idempotencyKey` to make a retry safe; one is
4052
+ * generated when you don't.
4053
+ */
4054
+ requestSmsOptIn(contactIdOrEmail: string, body?: SmsOptInRequest, opts?: SendOptions): Result<Sms$1>;
1486
4055
  }
1487
4056
  /**
1488
4057
  * SMS templates (`/sms/templates`). Draft → published like email templates;
@@ -1495,6 +4064,23 @@ declare class SmsTemplates extends Resource {
1495
4064
  get(id: string): Result<SmsTemplate>;
1496
4065
  update(id: string, body: SmsTemplateUpdate): Result<SmsTemplate>;
1497
4066
  delete(id: string): Result<null>;
4067
+ /**
4068
+ * What uses the template, and whether a change would be accepted now: its
4069
+ * live campaigns and automations, queued texts, and `can_edit_content` /
4070
+ * `can_unpublish` with the reason when not. Read it before an edit or a
4071
+ * delete. Needs `templates:read`.
4072
+ */
4073
+ usage(id: string): Result<SmsTemplateUsage>;
4074
+ /**
4075
+ * Send ONE test text of the template to `to`, which must be a simulator
4076
+ * number (`+14254147755` delivers, `+14254147167` fails) or a verified
4077
+ * number from `sms.testDestinations.list()` (any other is a `403`). Every `{{variable}}`
4078
+ * needs a value in `variables` (`422`). It goes from `sender_id`, or is
4079
+ * routed by the destination's country. It is a real text, billed like any.
4080
+ * Needs `sms:send`. Pass an `idempotencyKey` so a retry never texts twice;
4081
+ * one is generated when you don't.
4082
+ */
4083
+ testSend(id: string, body: SmsTemplateTestSend, opts?: SendOptions): Result<SmsTemplateTestSendResult>;
1498
4084
  }
1499
4085
  /** SMS subscription topics (`/sms/topics`); `delete` archives. */
1500
4086
  declare class SmsCampaigns extends Resource {
@@ -1520,6 +4106,15 @@ declare class SmsCampaigns extends Resource {
1520
4106
  cancel(id: string): Result<SmsCampaign>;
1521
4107
  pause(id: string): Result<SmsCampaign>;
1522
4108
  resume(id: string): Result<SmsCampaign>;
4109
+ /** Move a scheduled campaign back to draft so it can be edited; clears its send time. */
4110
+ unschedule(id: string): Result<SmsCampaign>;
4111
+ /**
4112
+ * Copy a campaign into a new draft (201). Pass an `idempotencyKey` so a
4113
+ * retry returns the same copy; one is generated when you don't.
4114
+ */
4115
+ duplicate(id: string, body?: {
4116
+ name?: string;
4117
+ }, opts?: SendOptions): Result<SmsCampaign>;
1523
4118
  reschedule(id: string, body: SmsCampaignReschedule): Result<SmsCampaign>;
1524
4119
  /**
1525
4120
  * Who the campaign would reach if sent now (non-mutating). A large audience
@@ -1528,6 +4123,21 @@ declare class SmsCampaigns extends Resource {
1528
4123
  * (`"job"`).
1529
4124
  */
1530
4125
  validate(id: string): Result<SmsCampaignValidation | Job>;
4126
+ /**
4127
+ * How each recipient fared: the carrier's answer for a text that went out
4128
+ * (`delivered`, `sent`, `failed`, …), or why none was sent (`skipped`, with
4129
+ * `reason_code`). Newest first, cursor-paginated on `id`; `q` matches digits
4130
+ * of the number. `skipped_by_reason` counts skipped recipients over the
4131
+ * whole campaign.
4132
+ */
4133
+ listRecipients(id: string, params?: ListParams & {
4134
+ q?: string;
4135
+ }): Result<ListResponse<SmsCampaignRecipient> & {
4136
+ skipped_by_reason?: {
4137
+ reason: string;
4138
+ count: number;
4139
+ }[];
4140
+ }>;
1531
4141
  }
1532
4142
  declare class SmsTopics extends Resource {
1533
4143
  list(params?: ListParams): Result<ListResponse<Topic>>;
@@ -1536,12 +4146,186 @@ declare class SmsTopics extends Resource {
1536
4146
  get(id: string): Result<Topic>;
1537
4147
  update(id: string, body: TopicUpdate): Result<Topic>;
1538
4148
  delete(id: string): Result<null>;
4149
+ /**
4150
+ * Opt many contacts out of this SMS topic as a background job (202, the
4151
+ * `Job`): `{ contact_ids }` or `{ emails }` (up to 1,000) or
4152
+ * `{ segment_id }` (every member). Follow it with `jobs.get(id)`. Pass an
4153
+ * `idempotencyKey` so a retry answers the same job; one is generated when
4154
+ * you don't. There is no bulk opt-in.
4155
+ */
4156
+ optOut(id: string, body: TopicOptOut, opts?: SendOptions): Result<Job>;
4157
+ }
4158
+ /**
4159
+ * Messaging programs (`/sms/messaging-programs`): what a sender registration
4160
+ * says your texts are for, how people opt in, the help and stop replies and
4161
+ * sample messages. A registration copies the program when it is submitted, so
4162
+ * a later edit never changes one. Reads need `sms:read`; the writes need
4163
+ * `sms:manage`, which FULL keys have and SENDING keys don't. Submitting a
4164
+ * registration is a paid order through `sms.quotes`.
4165
+ */
4166
+ declare class SmsMessagingPrograms extends Resource {
4167
+ /**
4168
+ * Your programs, newest first, cursor-paginated (`limit`, `after`,
4169
+ * `before`); `{ archived: true }` includes archived ones.
4170
+ */
4171
+ list(params?: ListParams & {
4172
+ archived?: boolean;
4173
+ }): Result<ListResponse<SmsMessagingProgram>>;
4174
+ /**
4175
+ * Create a program (201; `name` is required). Each field is checked by the
4176
+ * carriers' rules: lengths, help and stop replies that are a sentence and
4177
+ * not just a keyword, links to a real web address. Pass an
4178
+ * `idempotencyKey` so a retry never makes a second one; one is generated
4179
+ * when you don't.
4180
+ */
4181
+ create(body: SmsMessagingProgramCreate, opts?: SendOptions): Result<SmsMessagingProgram>;
4182
+ /** One program, archived ones too. */
4183
+ get(id: string): Result<SmsMessagingProgram>;
4184
+ /**
4185
+ * Edit a program: only the fields you send change, `null` clears one, and
4186
+ * the result must still pass the carriers' rules. `revision` moves on a
4187
+ * material change. An archived program is a `409`: `duplicate` it to keep
4188
+ * editing.
4189
+ */
4190
+ update(id: string, body: SmsMessagingProgramUpdate): Result<SmsMessagingProgram>;
4191
+ /** Archive a program. Registrations that copied it keep their copy. */
4192
+ delete(id: string): Result<null>;
4193
+ /**
4194
+ * Copy a program (an archived one too) into a new editable one named
4195
+ * "… (copy)" at revision 1 (201). It sends no body. Pass an
4196
+ * `idempotencyKey` so a retry returns the same copy; one is generated when
4197
+ * you don't.
4198
+ */
4199
+ duplicate(id: string, opts?: SendOptions): Result<SmsMessagingProgram>;
4200
+ }
4201
+ /**
4202
+ * Test numbers (`/sms/test-destinations`): the numbers a template test may
4203
+ * text besides the simulator, `pending` until the code texted to one is
4204
+ * entered, then `verified`. Adding and verifying one stays in the dashboard
4205
+ * (Phone numbers → Testing), because it proves the phone is yours. `list`
4206
+ * needs `sms:read`; `delete` needs `sms:manage`.
4207
+ */
4208
+ declare class SmsTestDestinations extends Resource {
4209
+ /** Your test numbers, newest first, cursor-paginated (`limit`, `after`, `before`). */
4210
+ list(params?: ListParams): Result<ListResponse<SmsTestDestination>>;
4211
+ /** Remove a test number; template tests can no longer text it. */
4212
+ delete(id: string): Result<null>;
4213
+ }
4214
+ /**
4215
+ * Consent setups (`/sms/consent-setups`): where and how people opt in to your
4216
+ * texts, the form or page and the brand and purpose it discloses. A messaging
4217
+ * program points at one with `consent_setup_id`. Needs `sms:read`.
4218
+ */
4219
+ declare class SmsConsentSetups extends Resource {
4220
+ /**
4221
+ * Your consent setups except archived ones, newest first, cursor-paginated
4222
+ * (`limit`, `after`, `before`).
4223
+ */
4224
+ list(params?: ListParams): Result<ListResponse<SmsConsentSetup>>;
4225
+ }
4226
+ /** SMS billing (`/sms/billing`). Needs `sms:read`; buying goes through `sms.quotes`. */
4227
+ declare class SmsBilling extends Resource {
4228
+ /**
4229
+ * What the workspace pays for SMS every month: each number and 10DLC
4230
+ * campaign, its monthly price, status and next charge, and for a past-due
4231
+ * number the date it is released (`grace_until`). Newest first,
4232
+ * cursor-paginated (`limit`, `after`, `before`).
4233
+ */
4234
+ listResources(params?: ListParams): Result<ListResponse<SmsBillableResource>>;
4235
+ }
4236
+ /**
4237
+ * Carrier purchases (`/sms/quotes`): register a 10DLC brand, vet it, register
4238
+ * a campaign, order a number. Each is two calls: `create` prices the order
4239
+ * and binds what it buys, `confirm` places it at the price you showed.
4240
+ */
4241
+ declare class SmsQuotes extends Resource {
4242
+ /**
4243
+ * Price an order (201). The quote binds the action and what it buys, and
4244
+ * returns `due_now_cents`, `monthly_cents`, `line_items` and a single-use
4245
+ * `confirm_token` (only in this response). It lasts 10 minutes and charges
4246
+ * nothing. Needs `sms:manage`.
4247
+ */
4248
+ create(body: SmsQuoteCreate): Result<SmsQuote>;
4249
+ /** One quote: its price, status and, once confirmed, what the order made. Needs `sms:read`. */
4250
+ get(id: string): Result<SmsQuote>;
4251
+ /**
4252
+ * Place the quoted order and charge it. Show the person the quote's price
4253
+ * and get their yes first. Needs `sms:purchase`, which a key or app has
4254
+ * only when a member who holds it ticked it, and the owner's monthly cap for
4255
+ * SMS purchases by API. A changed price or content answers `409`: quote
4256
+ * again. If you don't pass `idempotencyKey`, one is generated so a retry
4257
+ * can't buy twice; pass your own to replay the same answer later.
4258
+ */
4259
+ confirm(id: string, body: SmsQuoteConfirm, opts?: SendOptions): Result<SmsQuote>;
4260
+ }
4261
+ /**
4262
+ * Carrier registrations (`/sms/registrations`): 10DLC brand and campaign
4263
+ * registrations and toll-free verifications, with their review state and the
4264
+ * carrier's feedback. Submitting one is a purchase through `sms.quotes`;
4265
+ * fixing a campaign carriers sent back is `resubmit`, a failed number whose
4266
+ * fee is paid is `requestNumber`, taking down a 10DLC setup is `remove`, and
4267
+ * archiving an approved brand registration to register it again is
4268
+ * `replace`. Reads need `sms:read`, the writes `sms:manage`.
4269
+ */
4270
+ declare class SmsRegistrations extends Resource {
4271
+ /**
4272
+ * Your registrations, newest first, cursor-paginated (`limit`, `after`,
4273
+ * `before`). A 10DLC campaign also carries the number it backs (`sender`)
4274
+ * and one `setup_state`.
4275
+ */
4276
+ list(params?: ListParams): Result<ListResponse<SmsRegistration>>;
4277
+ /**
4278
+ * One registration (`sreg_…`), as `list()` reads it. Read a resubmit, a
4279
+ * removal or a replacement back with it.
4280
+ */
4281
+ get(registrationId: string): Result<SmsRegistration>;
4282
+ /**
4283
+ * Remove a 10DLC setup: take down a campaign registration
4284
+ * (`us_ten_dlc_campaign`) that has no active number. The carrier
4285
+ * registration is deleted, the campaign's monthly fee ends (no proration)
4286
+ * and the registration reads `archived_at` from then on. A campaign with a
4287
+ * number answers `409 resource_in_use` (release the number first with
4288
+ * `sms.releaseNumber`); one under carrier review answers `409 conflict`.
4289
+ * Pass an `idempotencyKey` so a retry removes once; one is generated when
4290
+ * you don't.
4291
+ */
4292
+ remove(registrationId: string, body?: SmsRegistrationRemove, opts?: SendOptions): Result<SmsRegistration>;
4293
+ /**
4294
+ * Replace an approved 10DLC brand registration (`us_ten_dlc_brand`):
4295
+ * archive it so the brand can be registered again (corrected legal
4296
+ * details, a new owner of the EIN). The brand unlocks for
4297
+ * `sms.updateBrand`, and the new registration is a quote and its confirm
4298
+ * (`ten_dlc_brand_registration`). Nothing changes at the carrier and
4299
+ * nothing is charged here. Refused while a number on the brand isn't
4300
+ * released or a 10DLC setup on it isn't removed (`409 resource_in_use`,
4301
+ * with `dependents`). Pass an `idempotencyKey` so a retry replaces once;
4302
+ * one is generated when you don't.
4303
+ */
4304
+ replace(registrationId: string, body?: SmsRegistrationReplace, opts?: SendOptions): Result<SmsRegistration>;
4305
+ /**
4306
+ * Resubmit a 10DLC campaign carriers sent back (free), after fixing what
4307
+ * its feedback names: an optional `opt_in_screenshot_file_id`, or
4308
+ * `acknowledge_unchanged` when the fix was made outside Unitpost. Pass an
4309
+ * `idempotencyKey` so a retry resubmits once; one is generated when you
4310
+ * don't.
4311
+ */
4312
+ resubmit(registrationId: string, body: SmsCampaignResubmit, opts?: SendOptions): Result<SmsRegistrationResubmission>;
4313
+ /**
4314
+ * Request a campaign's number again after it failed, when its fee is
4315
+ * already committed (free). A number the fee doesn't cover answers `409
4316
+ * quote_required`: order it through `sms.quotes` (`ten_dlc_number`). Pass
4317
+ * an `idempotencyKey` so a retry requests one number; one is generated when
4318
+ * you don't.
4319
+ */
4320
+ requestNumber(registrationId: string, body?: SmsNumberRetry, opts?: SendOptions): Result<SmsNumberRequest>;
1539
4321
  }
1540
4322
  declare class Email extends Resource {
1541
4323
  readonly topics: Topics;
1542
4324
  readonly campaigns: Campaigns;
1543
4325
  readonly templates: Templates;
1544
4326
  readonly domains: Domains;
4327
+ /** Inbox conversations: list, read, delete and reply. */
4328
+ readonly threads: EmailThreads;
1545
4329
  constructor(http: HttpClient);
1546
4330
  /**
1547
4331
  * Send or schedule a transactional email.
@@ -1564,33 +4348,67 @@ declare class Email extends Resource {
1564
4348
  getBatch(id: string): Result<Batch>;
1565
4349
  /** Cancel every still-cancelable message in a batch. */
1566
4350
  cancelBatch(id: string): Result<Batch>;
4351
+ /**
4352
+ * Your batch sends, newest first (cursor-paginated), as the dashboard's
4353
+ * Batches tab lists them. Each row is the same live rollup `getBatch`
4354
+ * returns: how many emails it holds, when it's scheduled, a count per
4355
+ * delivery status and how many are still cancelable.
4356
+ */
4357
+ listBatches(params?: ListParams): Result<ListResponse<Batch>>;
1567
4358
  /** List sent/scheduled emails (cursor-paginated). */
1568
- list(params?: ListParams & {
1569
- status?: string;
1570
- campaign_id?: string;
1571
- batch_id?: string;
1572
- }): Result<ListResponse<Email$1>>;
1573
- /** Async-iterate every sent/scheduled email. */
1574
- listAll(params?: ListParams): AsyncGenerator<Email$1, void, void>;
1575
- /** Retrieve a sent or scheduled email. */
4359
+ list(params?: EmailListParams): Result<ListResponse<Email$1>>;
4360
+ /** Async-iterate every sent/scheduled email (same filters as `list`). */
4361
+ listAll(params?: EmailListParams): AsyncGenerator<Email$1, void, void>;
4362
+ /** Retrieve a sent or scheduled email, with its `cc`, `bcc`, `reply_to` and `tags`. */
1576
4363
  get(id: string): Result<Email$1>;
4364
+ /**
4365
+ * One sent email's delivery events, oldest first, as the dashboard's email
4366
+ * detail shows the timeline. Each event carries its detail in `data` under
4367
+ * the webhook's names (`data.bounce.diagnostic_code`, `data.click.link`,
4368
+ * `data.complaint.feedback_type`, ...). Cursor-paginated: `after` /
4369
+ * `before` take an `emev_` id. Needs `emails:read`.
4370
+ */
4371
+ listEvents(id: string, params?: ListParams): Result<ListResponse<EmailEvent>>;
1577
4372
  /** Cancel or reschedule a scheduled/queued email. */
1578
4373
  update(id: string, body: EmailPatch): Result<Email$1>;
1579
4374
  /**
1580
- * Deliverability / engagement stats over a rolling window.
4375
+ * Send a `failed` email again on the same `id`, as the dashboard's Retry
4376
+ * does. Only a one-off send whose failure was temporary is retried: a
4377
+ * campaign recipient, a template test, a suppressed or rejected send, or a
4378
+ * content error is a `409` saying why (send a new email instead). It passes
4379
+ * the same checks as a new send: the sending domain, your plan and quota.
4380
+ * It sends no body; follow the email with `get`.
1581
4381
  *
1582
- * `days` is the window size (1–365); defaults to 30 server-side.
4382
+ * It sends real email, so if you don't pass `idempotencyKey` the SDK
4383
+ * generates one, which makes an auto-retry safe. Pass your own to dedupe
4384
+ * across separate `retry()` calls.
1583
4385
  */
1584
- stats(params?: {
1585
- days?: number;
1586
- }): Result<EmailStats>;
4386
+ retry(id: string, opts?: SendOptions): Result<Email$1>;
4387
+ /**
4388
+ * Deliverability / engagement stats over a rolling window or a period.
4389
+ *
4390
+ * `days` is the window size (1–365); defaults to 30 server-side. Or count a
4391
+ * period with `from` and `to`; add `grain` (and `tz`) for `series`, the send
4392
+ * volume per bucket. `domain_id` counts one sending domain. A value the API
4393
+ * can't apply is ignored and named in the `Unitpost-Warning` response
4394
+ * header; `Unitpost-Strict: true` refuses it instead.
4395
+ */
4396
+ stats(params?: EmailStatsParams): Result<EmailStats>;
1587
4397
  receivedList(params?: ListParams): Result<ListResponse<ReceivedEmailSummary>>;
1588
4398
  receivedGet(id: string): Result<ReceivedEmail>;
1589
4399
  receivedAttachmentUrl(id: string, attachmentId: string): Result<ReceivedAttachmentUrl>;
4400
+ /**
4401
+ * A signed URL to download the received message's original MIME (`.eml`),
4402
+ * valid for about 5 minutes (`expires_at`), with its `size_bytes`. A body
4403
+ * over 256 KB isn't inlined on `receivedGet` (its `text` and `html` are
4404
+ * `null`), so this is how to read it. A copy of one of your own sends
4405
+ * (`sent_by_us`) is a `403`. Needs `emails:read`.
4406
+ */
4407
+ receivedRaw(id: string): Result<ReceivedEmailRaw>;
1590
4408
  }
1591
4409
  declare class Contacts extends Resource {
1592
- list(params?: ListParams): Result<ListResponse<Contact>>;
1593
- listAll(params?: ListParams): AsyncGenerator<Contact, void, void>;
4410
+ list(params?: ContactListParams): Result<ListResponse<Contact>>;
4411
+ listAll(params?: ContactListParams): AsyncGenerator<Contact, void, void>;
1594
4412
  create(body: ContactCreate): Result<Contact>;
1595
4413
  /** Retrieve by contact id or email. */
1596
4414
  get(idOrEmail: string): Result<Contact>;
@@ -1601,6 +4419,41 @@ declare class Contacts extends Resource {
1601
4419
  listImports(params?: ListParams): Result<ListResponse<ContactImport>>;
1602
4420
  getImport(id: string): Result<ContactImport>;
1603
4421
  cancelImport(id: string): Result<ContactImport>;
4422
+ /** Re-run a failed import from its stored rows (202); rows already added are skipped. */
4423
+ retryImport(id: string): Result<ContactImport>;
4424
+ /** The contact's email addresses and phone numbers, with each one's status (one page, never `has_more`). */
4425
+ addresses(idOrEmail: string): Result<ListResponse<ContactAddress>>;
4426
+ /** The contact's most recent emails and texts, newest first (`limit` 1–100, default 25; no cursor). */
4427
+ activity(idOrEmail: string, params?: {
4428
+ limit?: number;
4429
+ }): Result<ListResponse<ContactActivity>>;
4430
+ /**
4431
+ * The segments the contact is in, with its per-segment opt-out (not
4432
+ * paginated). To add the contact to a static segment or remove it, use
4433
+ * `segments.addMember` / `segments.removeMember`.
4434
+ */
4435
+ listSegments(idOrEmail: string): Result<ListResponse<ContactSegment>>;
4436
+ /**
4437
+ * Export contacts to a CSV file (202), as the Contacts page's Export does:
4438
+ * every contact, or the ones the filters match (`q`, `status`, `phone`,
4439
+ * `segment_id`, `segment_subscription`, as on `list`). It runs as a
4440
+ * background job: follow it with `jobs.get(job.id)`, then fetch the file
4441
+ * with `jobs.download(job.id)`. One export runs at a time: another while it
4442
+ * runs is a `409` `job_in_progress`. `segment_id` also needs `segments:read`.
4443
+ */
4444
+ export(body?: ContactsExport): Result<Job>;
4445
+ /**
4446
+ * Set one custom field to the same value on many contacts, as the Contacts
4447
+ * page's Set field does, as a background job (202, the `Job`): `key`,
4448
+ * `value` (typed against the field; `null` clears it), optional
4449
+ * `only_empty`, and exactly one of `contact_ids` or `emails` (up to 1,000,
4450
+ * each a contact of this workspace) or `segment_id` (every member, however
4451
+ * many; also needs `segments:read`). Each contact whose value changes gets
4452
+ * `contact.updated`; consent is never touched. Follow it with
4453
+ * `jobs.get(id)`. Pass an `idempotencyKey` so a retry answers the same job;
4454
+ * one is generated when you don't.
4455
+ */
4456
+ setField(body: ContactSetField, opts?: SendOptions): Result<Job>;
1604
4457
  }
1605
4458
  declare class ContactFields extends Resource {
1606
4459
  list(params?: ListParams): Result<ListResponse<ContactField>>;
@@ -1623,11 +4476,38 @@ declare class ContactFields extends Resource {
1623
4476
  rename(id: string, body: ContactFieldRename): Result<ContactField | Job>;
1624
4477
  }
1625
4478
  declare class Jobs extends Resource {
4479
+ /**
4480
+ * Your background jobs, newest first (cursor-paginated), as Settings → Bulk
4481
+ * operations lists them: the kinds an API operation starts that your key
4482
+ * may read. Filter with `status` or `kind` (`"contacts.export"`,
4483
+ * `"contact_field.delete"`, …).
4484
+ */
4485
+ list(params?: ListParams & {
4486
+ status?: Job["status"];
4487
+ kind?: string;
4488
+ }): Result<ListResponse<Job>>;
1626
4489
  /**
1627
4490
  * Retrieve a background job — the `202` answer of an operation too large for
1628
4491
  * one request. Poll until `status` is `COMPLETED`, `FAILED` or `CANCELED`.
1629
4492
  */
1630
4493
  get(id: string): Result<Job>;
4494
+ /**
4495
+ * Stop a queued or running job. A running job stops after the part in
4496
+ * flight; the work already done stays. A kind that can't stop half-way (a
4497
+ * custom-field rename) is a `409` saying why. It sends no body.
4498
+ */
4499
+ cancel(id: string): Result<Job>;
4500
+ /**
4501
+ * Resume a `FAILED` job from where it stopped (202): nothing it already
4502
+ * processed runs again. Any other status is a `409`. It sends no body.
4503
+ */
4504
+ retry(id: string): Result<Job>;
4505
+ /**
4506
+ * A finished job's file (a contacts export's CSV) as a signed `url` that
4507
+ * expires in 5 minutes: fetch it right away, and call `download` again for a
4508
+ * fresh one. A job that isn't `COMPLETED`, or a kind with no file, is a `409`.
4509
+ */
4510
+ download(id: string): Result<JobDownload>;
1631
4511
  }
1632
4512
  declare class Segments extends Resource {
1633
4513
  list(params?: ListParams): Result<ListResponse<Segment>>;
@@ -1637,10 +4517,48 @@ declare class Segments extends Resource {
1637
4517
  update(id: string, body: SegmentUpdate): Result<Segment>;
1638
4518
  delete(id: string): Result<null>;
1639
4519
  listMembers(id: string, params?: ListParams): Result<ListResponse<SegmentMember>>;
1640
- /** Add a contact (by id or email) to the segment. Idempotent. */
4520
+ /**
4521
+ * Add a contact (by id or email, `{ contact }`) to the segment, which
4522
+ * answers its membership; or many at once (`{ contact_ids }` or
4523
+ * `{ emails }`, up to 1,000, all checked first), which answers each listed
4524
+ * contact's membership and `added`. Idempotent: an existing member keeps
4525
+ * its state.
4526
+ */
4527
+ addMember(id: string, body: SegmentMembersAdd & ({
4528
+ contact_ids: string[];
4529
+ } | {
4530
+ emails: string[];
4531
+ })): Result<SegmentMembersAdded>;
1641
4532
  addMember(id: string, body: SegmentMemberAdd): Result<SegmentMember>;
4533
+ addMember(id: string, body: SegmentMemberAddBody): Result<SegmentMember | SegmentMembersAdded>;
1642
4534
  /** Remove a contact (by id or email) from the segment. */
1643
4535
  removeMember(id: string, contact: string): Result<null>;
4536
+ /**
4537
+ * Opt a member (by id or email) out of this segment's sends without
4538
+ * removing it (`{ subscribed: false }`), or back in, as the members table's
4539
+ * toggle does. It stays a member. A dynamic segment has no per-segment
4540
+ * opt-out (`422`).
4541
+ */
4542
+ updateMember(id: string, contact: string, body: SegmentMemberUpdate): Result<SegmentMember>;
4543
+ /**
4544
+ * How many contacts a saved segment reaches: its members, the subscribed
4545
+ * set a campaign would mail (`0` means a campaign would send nothing), and a
4546
+ * sample (which also needs `contacts:read`).
4547
+ */
4548
+ preview(id: string): Result<SegmentPreview>;
4549
+ /**
4550
+ * Count an unsaved dynamic filter before you create the segment, as the
4551
+ * segment dialog's live count does: how many contacts match, how many of
4552
+ * them a campaign would mail, and a sample (which also needs
4553
+ * `contacts:read`). Nothing is saved.
4554
+ */
4555
+ previewFilter(body: SegmentPreviewRequest): Result<SegmentPreview>;
4556
+ /**
4557
+ * The workspace's managed "All subscribed contacts" segment, the
4558
+ * dashboard's "Everyone subscribed" campaign target: made the first time you
4559
+ * ask (201), the same segment after that (200). It sends no body.
4560
+ */
4561
+ allContacts(): Result<Segment>;
1644
4562
  }
1645
4563
  declare class Topics extends Resource {
1646
4564
  list(params?: ListParams): Result<ListResponse<Topic>>;
@@ -1649,10 +4567,29 @@ declare class Topics extends Resource {
1649
4567
  get(id: string): Result<Topic>;
1650
4568
  update(id: string, body: TopicUpdate): Result<Topic>;
1651
4569
  delete(id: string): Result<null>;
4570
+ /**
4571
+ * Opt many contacts out of this topic as a background job (202, the `Job`):
4572
+ * `{ contact_ids }` or `{ emails }` (up to 1,000, each a contact of this
4573
+ * workspace) or `{ segment_id }` (every member, however many). Each is
4574
+ * opted out as `setTopic` would, with its webhook only when it was
4575
+ * subscribed. Follow it with `jobs.get(id)`. Pass an `idempotencyKey` so a
4576
+ * retry answers the same job; one is generated when you don't. There is no
4577
+ * bulk opt-in.
4578
+ */
4579
+ optOut(id: string, body: TopicOptOut, opts?: SendOptions): Result<Job>;
1652
4580
  /** List a contact's effective topic subscriptions. */
1653
4581
  listTopics(contactId: string, params?: ListParams): Result<ListResponse<ContactTopic>>;
1654
4582
  /** Set a contact's preference for one topic. */
1655
4583
  setTopic(contactId: string, body: ContactTopicSet): Result<ContactTopic>;
4584
+ /**
4585
+ * Change a contact's preferences for several topics in one call
4586
+ * (`{ topics: [{ topic_id, subscribed }] }`, up to 50, each topic once);
4587
+ * topics left out keep theirs. Every topic is checked before any is set (an
4588
+ * unknown one is a 404 and nothing changes). Answers the resolved
4589
+ * preferences in the order sent (`{ object: "list", has_more: false, data }`).
4590
+ * Idempotent.
4591
+ */
4592
+ updateTopics(contactId: string, body: ContactTopicsUpdate): Result<ContactTopicList>;
1656
4593
  }
1657
4594
  declare class Campaigns extends Resource {
1658
4595
  list(params?: ListParams): Result<ListResponse<Campaign>>;
@@ -1672,6 +4609,15 @@ declare class Campaigns extends Resource {
1672
4609
  pause(id: string): Result<Campaign>;
1673
4610
  /** Resume a paused campaign; sending continues with the remaining recipients. */
1674
4611
  resume(id: string): Result<Campaign>;
4612
+ /** Move a scheduled campaign back to draft so it can be edited; clears its send time. */
4613
+ unschedule(id: string): Result<Campaign>;
4614
+ /**
4615
+ * Copy a campaign into a new draft (201). Pass an `idempotencyKey` so a
4616
+ * retry returns the same copy; one is generated when you don't.
4617
+ */
4618
+ duplicate(id: string, body?: {
4619
+ name?: string;
4620
+ }, opts?: SendOptions): Result<Campaign>;
1675
4621
  reschedule(id: string, body: CampaignReschedule): Result<Campaign>;
1676
4622
  /**
1677
4623
  * Non-mutating pre-send validation report. A large audience is counted in
@@ -1679,6 +4625,51 @@ declare class Campaigns extends Resource {
1679
4625
  * it returns the report.
1680
4626
  */
1681
4627
  validate(id: string): Result<unknown>;
4628
+ /**
4629
+ * The campaign's results: delivered, unique opens and clicks, unsubscribes,
4630
+ * bounces, complaints and their rates. Every rate is `null` until something
4631
+ * was sent; open and click rates are `null` when that tracking was off.
4632
+ */
4633
+ stats(id: string): Result<CampaignStats>;
4634
+ /**
4635
+ * `stats` for up to 100 campaigns in one read (1–100 ids). An id that isn't
4636
+ * one of this workspace's email campaigns is left out of `data`, never an
4637
+ * error; `has_more` is always false.
4638
+ */
4639
+ listStats(ids: string[]): Result<ListResponse<CampaignStats>>;
4640
+ /**
4641
+ * Who the campaign would reach if sent now, member by member: `sendable`,
4642
+ * `missing_data`, `suppressed` or `excluded`, with the reason. Pass the
4643
+ * page's `next_cursor` as `after` for the next page (rows carry no `id`).
4644
+ * A page can hold fewer rows than `limit` while `has_more` is true.
4645
+ */
4646
+ listRecipients(id: string, params?: {
4647
+ status?: "all" | "sendable" | "missing_data" | "suppressed" | "excluded";
4648
+ /** Rows per page (1–100, default 50). */
4649
+ limit?: number;
4650
+ /** The previous page's `next_cursor`. */
4651
+ after?: string;
4652
+ }): Result<ListResponse<CampaignRecipient> & {
4653
+ next_cursor?: string | null;
4654
+ }>;
4655
+ /**
4656
+ * After an automatic quality pause: the recipients whose message
4657
+ * hard-bounced or drew a spam complaint. They're already suppressed; this is
4658
+ * for cleaning the source list. Up to 10,000; `has_more` says it was cut there.
4659
+ */
4660
+ listAffected(id: string): Result<ListResponse<CampaignAffectedRecipient>>;
4661
+ /**
4662
+ * After an automatic quality pause: take the flagged contacts out of the
4663
+ * campaign's static segment (needs `segments:write` too; a filter segment is
4664
+ * a `409`). A repeat removes nothing. It doesn't resume the campaign.
4665
+ */
4666
+ removeAffected(id: string): Result<CampaignQualityRemoval>;
4667
+ /**
4668
+ * Ask for the review a campaign needs before it can resume after a repeat
4669
+ * quality pause (`resume` answers `409 review_required` until then). A
4670
+ * repeat answers `already_requested: true` and notifies no one.
4671
+ */
4672
+ requestReview(id: string): Result<CampaignReviewRequest>;
1682
4673
  }
1683
4674
  declare class Templates extends Resource {
1684
4675
  list(params?: ListParams): Result<ListResponse<Template>>;
@@ -1689,12 +4680,113 @@ declare class Templates extends Resource {
1689
4680
  delete(id: string): Result<null>;
1690
4681
  /**
1691
4682
  * 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.
4683
+ * exactly as a recipient gets it. Once a sending domain is verified it may
4684
+ * go to anyone; until then only to a member of your workspace.
1694
4685
  */
1695
4686
  testSend(id: string, body: TemplateTestSend): Result<TemplateTestSendResult>;
4687
+ /**
4688
+ * The `subject`, `html` and `text` a send of this template would carry,
4689
+ * with your footer and branding, filled from `variables` (and from a
4690
+ * contact's fields with `contact_id`). It sends and stores nothing, so it
4691
+ * takes no idempotency key. `missing_variables` lists the variables left
4692
+ * without a value: they render as a literal `{{token}}`, and a real send
4693
+ * would refuse them. The body is optional: `{}` renders with no variables.
4694
+ * Needs `templates:read`, and has its own per-workspace rate limit.
4695
+ */
4696
+ render(id: string, body?: TemplateRenderInput): Result<TemplateRender>;
4697
+ /**
4698
+ * Copy a template into a new draft (201): its name (with " (copy)", or your
4699
+ * `name`), subject, editor and body carry over; its status, versions and
4700
+ * usage don't. Pass an `idempotencyKey` so a retry returns the same copy;
4701
+ * one is generated when you don't.
4702
+ */
4703
+ duplicate(id: string, body?: TemplateDuplicate, opts?: SendOptions): Result<Template>;
4704
+ /**
4705
+ * Add one of the gallery's ready-made emails (unitpost.com/templates) to
4706
+ * your workspace as a draft Design template (201). `slug` names it; the ones
4707
+ * marked for paid plans answer `403 limit_reached` on the free plan. Pass an
4708
+ * `idempotencyKey` so a retry returns the same template; one is generated
4709
+ * when you don't.
4710
+ */
4711
+ fromLibrary(body: TemplateFromLibrary, opts?: SendOptions): Result<Template>;
4712
+ /**
4713
+ * What uses the template, and whether a change would be accepted now: the
4714
+ * campaigns that reference it, its live campaigns and automations, queued
4715
+ * sends, and `can_edit_content` / `can_unpublish` with the reason when not.
4716
+ * Read it before an edit or a delete: a content edit is refused while a
4717
+ * live campaign renders the template, and a delete while any campaign uses
4718
+ * it.
4719
+ */
4720
+ usage(id: string): Result<TemplateUsage>;
4721
+ /**
4722
+ * The template's history, newest first: a version is added on every publish
4723
+ * and on every content save while it's published. It pages by version
4724
+ * number: pass the last row's `version` (an integer, not an id) as `after`.
4725
+ * There is no `before`.
4726
+ */
4727
+ listVersions(id: string, params?: {
4728
+ /** Rows per page (1–100, default 20). */
4729
+ limit?: number;
4730
+ /** The last `version` of the previous page. */
4731
+ after?: number;
4732
+ }): Result<ListResponse<TemplateVersion>>;
4733
+ /**
4734
+ * Put a version's subject and body back, as the editor's History → Restore
4735
+ * does. It is an update, so a system template, or one a live campaign
4736
+ * renders, is refused with a `409` naming why (`usage` says so up front).
4737
+ * On a published template the restore adds a new version; history is never
4738
+ * rewritten. It sends no body.
4739
+ */
4740
+ restoreVersion(id: string, version: number): Result<Template>;
1696
4741
  }
1697
- /** Read-only Brand Kit profiles (voice, colors, pinned `/img/{id}` graphics). */
4742
+ /**
4743
+ * Inbox conversations (`/email/threads`, `thr_…`): each received message and
4744
+ * the replies and forwards sent from it are one conversation, as Emails →
4745
+ * Received shows them.
4746
+ */
4747
+ declare class EmailThreads extends Resource {
4748
+ /**
4749
+ * Every conversation (Spam included), newest activity first. `q` searches
4750
+ * the subject, the sender and the opening words. Pass the page's
4751
+ * `next_cursor` as `after` for the next page (not the last row's `id`).
4752
+ */
4753
+ list(params?: {
4754
+ q?: string;
4755
+ /** Rows per page (1–100, default 50). */
4756
+ limit?: number;
4757
+ /** The previous page's `next_cursor`. */
4758
+ after?: string;
4759
+ }): Result<ListResponse<EmailThread> & {
4760
+ next_cursor?: string | null;
4761
+ }>;
4762
+ /**
4763
+ * One conversation, oldest message first: what you received (with bodies)
4764
+ * and what you sent from it (status and recipients, no body).
4765
+ */
4766
+ get(id: string): Result<EmailThreadDetail>;
4767
+ /**
4768
+ * Delete a conversation for good: its received messages are erased; replies
4769
+ * and forwards sent from it stay on your sent emails. It can't be undone.
4770
+ */
4771
+ delete(id: string): Result<EmailThreadDeleted>;
4772
+ /**
4773
+ * Reply, reply all or forward one received message of the conversation
4774
+ * (`received_email_id`): your `text`/`html` go on top and the original is
4775
+ * quoted under them. It sends now and marks the conversation read.
4776
+ *
4777
+ * It sends real email, so if you don't pass `idempotencyKey` the SDK
4778
+ * generates one, which makes an auto-retry safe. Pass your own to dedupe
4779
+ * across separate `reply()` calls.
4780
+ */
4781
+ reply(id: string, body: EmailThreadReplyRequest, opts?: SendOptions): Result<EmailThreadReplyResult>;
4782
+ }
4783
+ /**
4784
+ * Brand Kit profiles (voice, colors, pinned `/img/{id}` graphics), and the
4785
+ * imports that fill them from a website or the brand's own words. The reads
4786
+ * (`list`, `get`, `getImport`) need `templates:read`; the writes
4787
+ * and starting, accepting or canceling an import need `branding:write`, which
4788
+ * no key preset grants: tick it on the key.
4789
+ */
1698
4790
  declare class BrandKits extends Resource {
1699
4791
  /** List profiles (max 5). Optional `name` filters by display name. */
1700
4792
  list(params?: {
@@ -1702,6 +4794,61 @@ declare class BrandKits extends Resource {
1702
4794
  }): Result<BrandKitList>;
1703
4795
  /** Retrieve one profile by `bk_…` id. */
1704
4796
  get(id: string): Result<BrandKit>;
4797
+ /**
4798
+ * Create an empty profile (201); `name` is unique in the workspace. The
4799
+ * first profile, or one with `make_default`, becomes the default. At most
4800
+ * five profiles (`403 limit_reached`). Fill it with `update` or `import`.
4801
+ */
4802
+ create(body: BrandKitCreate): Result<BrandKit>;
4803
+ /**
4804
+ * Edit a profile: only the fields you send change, a list replaces the
4805
+ * list, and `null` or `""` clears a text field. `graphics` pins library
4806
+ * images by `image_id` (`img_…`). `sync_visual` on the default profile also
4807
+ * sets the email branding's accent from its colors.
4808
+ */
4809
+ update(id: string, body: BrandKitUpdate): Result<BrandKit>;
4810
+ /**
4811
+ * Delete a profile. When it was the default, the oldest remaining profile
4812
+ * becomes the default. The last profile can't be deleted (`409`): `reset`
4813
+ * it instead. Its pinned images stay in the library.
4814
+ */
4815
+ delete(id: string): Result<null>;
4816
+ /**
4817
+ * Clear a profile's content (voice, colors, graphics, pages), keeping its
4818
+ * name and whether it's the default. It sends no body.
4819
+ */
4820
+ reset(id: string): Result<BrandKit>;
4821
+ /** Make a profile the default: the one agents write with unless told otherwise. It sends no body. */
4822
+ setDefault(id: string): Result<BrandKit>;
4823
+ /**
4824
+ * Add a graphic (201) from a public https image `url` (fetched once, no
4825
+ * redirects): it goes into the image library, counted against its storage,
4826
+ * and is pinned with its `role` (default `logo`). To pin an image already in
4827
+ * the library, `update` the profile's `graphics`.
4828
+ */
4829
+ addGraphic(id: string, body: BrandKitGraphicAdd): Result<BrandKitGraphicAdded>;
4830
+ /**
4831
+ * Build a profile from a website (`url`, or a bare domain) or the brand's
4832
+ * own words (`text`). It runs in the background, usually under a minute
4833
+ * (202): follow it with `getImport`. By default the result is applied when
4834
+ * it lands, to `brand_kit_id`, else the default profile, or a new one when
4835
+ * the default already has content. With `review: true` it stops at a
4836
+ * proposal (`preview_ready`) for `acceptImport`; one review import is open
4837
+ * at a time, and a new one replaces it.
4838
+ */
4839
+ import(body: BrandImportCreate): Result<BrandImport>;
4840
+ /** One import: its status, the proposal once it's ready, warnings and any error. */
4841
+ getImport(id: string): Result<BrandImport>;
4842
+ /**
4843
+ * Apply a review import's proposal (`preview_ready`) to a profile: voice,
4844
+ * colors and pages, and its logos and backgrounds brought into the image
4845
+ * library and pinned. The body is optional: `brand_kit_id` applies it to
4846
+ * another profile, `name` names it. To change other fields, accept and then
4847
+ * `update`.
4848
+ */
4849
+ acceptImport(id: string, body?: BrandImportAccept): Result<BrandImportAccepted>;
4850
+ /** Discard a review import's proposal or stop its crawl. It sends no body. */
4851
+ cancelImport(id: string): Result<BrandImport>;
1705
4852
  }
1706
4853
  declare class Domains extends Resource {
1707
4854
  list(params?: ListParams): Result<ListResponse<Domain>>;
@@ -1716,12 +4863,43 @@ declare class Domains extends Resource {
1716
4863
  }>;
1717
4864
  /** Explain the domain's DNS: every nameserver's answer per record, and ranked findings with fixes. Read-only. */
1718
4865
  diagnose(id: string): Result<DomainDiagnosis>;
4866
+ /**
4867
+ * Your saved From addresses, as the domain page lists them and the
4868
+ * dashboard's From pickers offer them: each a mailbox on one of your
4869
+ * domains, with its display name and `from`, the value to send with.
4870
+ * `domain_id` keeps one domain's. A sender can send once its domain can.
4871
+ */
4872
+ listSenders(params?: ListParams & {
4873
+ domain_id?: string;
4874
+ }): Result<ListResponse<Sender>>;
4875
+ /**
4876
+ * Save a From address on one of your domains (201); the domain may still be
4877
+ * verifying. A mailbox already saved on that domain is a `409`, so a retry
4878
+ * never saves it twice.
4879
+ */
4880
+ createSender(body: SenderCreate): Result<Sender>;
4881
+ /** One saved From address. */
4882
+ getSender(id: string): Result<Sender>;
4883
+ /**
4884
+ * Change a sender's display name (`null` or `""` clears it), the only field
4885
+ * that changes: a different mailbox is a new sender.
4886
+ */
4887
+ updateSender(id: string, body: SenderUpdate): Result<Sender>;
4888
+ /**
4889
+ * Remove a saved From address from the pickers. Templates and campaigns that
4890
+ * send from it keep their From.
4891
+ */
4892
+ deleteSender(id: string): Result<null>;
1719
4893
  }
1720
4894
  declare class Webhooks extends Resource {
1721
4895
  list(params?: ListParams): Result<ListResponse<Webhook>>;
1722
4896
  listAll(params?: ListParams): AsyncGenerator<Webhook, void, void>;
1723
4897
  /** Create an endpoint. The response includes `signing_secret` exactly once. */
1724
4898
  create(body: WebhookCreate): Result<WebhookCreated>;
4899
+ /**
4900
+ * One endpoint, with its `backlog`: the deliveries `flush` would send
4901
+ * (`queued` while it was paused, and `failed`).
4902
+ */
1725
4903
  get(id: string): Result<Webhook>;
1726
4904
  update(id: string, body: WebhookUpdate): Result<Webhook>;
1727
4905
  delete(id: string): Result<null>;
@@ -1732,35 +4910,87 @@ declare class Webhooks extends Resource {
1732
4910
  * secret co-signs deliveries until `previous_secret_expires_at` (24 h).
1733
4911
  */
1734
4912
  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>;
4913
+ /**
4914
+ * The endpoint's delivery log, newest first (cursor-paginated). Narrow it
4915
+ * with `status` (comma-separated, e.g. `"failed,exhausted"`) and
4916
+ * `event_type` (e.g. `email.bounced`).
4917
+ */
4918
+ listDeliveries(id: string, params?: WebhookDeliveryListParams): Result<ListResponse<WebhookDelivery>>;
4919
+ /** Async-iterate every delivery of the endpoint (same filters as `listDeliveries`). */
4920
+ listAllDeliveries(id: string, params?: WebhookDeliveryListParams): AsyncGenerator<WebhookDelivery, void, void>;
4921
+ /**
4922
+ * Deliver one event to the endpoint again (202), as the dashboard's Replay
4923
+ * does. The same event goes out with the same id, so a receiver that
4924
+ * dedupes on it treats the replay as the delivery it already has. The
4925
+ * webhook must be enabled: a disabled or suspended one is a `409`
4926
+ * (re-enable it with `update` first). Find deliveries with
4927
+ * `listDeliveries`. It sends no body.
4928
+ */
4929
+ replayDelivery(id: string, deliveryId: string): Result<WebhookDeliveryReplay>;
4930
+ /**
4931
+ * Deliver the backlog (202): the deliveries held while the webhook was
4932
+ * suspended (`queued`), as the dashboard's "Retry queued" does. With
4933
+ * `include_failed: true`, also the ones that failed for good (`failed`,
4934
+ * `exhausted`). The webhook must be enabled: a disabled or suspended one is
4935
+ * a `409` (re-enable it with `update` first); re-enabling never delivers the
4936
+ * backlog on its own. `flushed` counts the deliveries handed back.
4937
+ */
4938
+ flush(id: string, body?: WebhookFlush): Result<WebhookFlushResult>;
1739
4939
  /**
1740
4940
  * Verify a webhook delivery's signature and return the parsed event. Throws
1741
4941
  * `WebhookVerificationError` on a missing/invalid/stale signature. Alias of the
1742
- * top-level `verifyWebhook` for a Resend-style `unitpost.webhooks.verify(...)`.
4942
+ * top-level `verifyWebhook`, callable as `unitpost.webhooks.verify(...)`.
1743
4943
  */
1744
4944
  verify<T = unknown>(args: VerifyWebhookArgs): T;
1745
4945
  }
1746
4946
  declare class ApiKeys extends Resource {
4947
+ /**
4948
+ * The workspace's API keys (prefix, scope, capabilities, last use; never
4949
+ * the secret). With an API key or an MCP sign-in it needs `apikeys:read`,
4950
+ * which no key preset includes.
4951
+ */
1747
4952
  list(params?: ListParams): Result<ListResponse<ApiKey>>;
1748
4953
  listAll(params?: ListParams): AsyncGenerator<ApiKey, void, void>;
1749
4954
  /** Create a key. The response includes the plaintext `key` exactly once. */
1750
4955
  create(body: ApiKeyCreate): Result<ApiKeyCreated>;
1751
4956
  delete(id: string): Result<null>;
4957
+ /**
4958
+ * One key's last 24 hours: how many requests it made, how many were
4959
+ * answered 4xx, 5xx or 429, and when it was last used. Check it before you
4960
+ * revoke a key (is anything still calling with it?) or when an
4961
+ * integration's calls fail. Needs `apikeys:read`, which no key preset
4962
+ * includes.
4963
+ */
4964
+ usage(id: string): Result<ApiKeyUsage>;
4965
+ }
4966
+ /**
4967
+ * The workspace's API request log: one row per call. Needs `apikeys:read`,
4968
+ * which no key preset includes.
4969
+ */
4970
+ declare class Logs extends Resource {
4971
+ /**
4972
+ * Your workspace's API request log, newest first (cursor-paginated, `rlog_`
4973
+ * ids): each call's `method`, `path`, `status`, time taken (`duration_ms`),
4974
+ * the API key that made it (`api_key_id`) and its `x-request-id`
4975
+ * (`request_id`: quote it to support). Never the caller's IP and never a
4976
+ * body. Narrow it with `status` (a code, or a class such as `4xx`),
4977
+ * `api_key_id`, `method`, `path_prefix` (e.g. `/email`), `request_id` and a
4978
+ * `created_after` / `created_before` range; an unknown filter is a `422`.
4979
+ * Rows are kept 30 days. Needs `apikeys:read`, which no key preset
4980
+ * includes, and has its own per-workspace rate limit.
4981
+ */
4982
+ list(params?: LogListParams): Result<ListResponse<RequestLog>>;
1752
4983
  }
1753
4984
  declare class Suppressions extends Resource {
1754
4985
  /**
1755
4986
  * List your workspace's suppressed addresses. Unitpost-wide (platform)
1756
4987
  * blocks are enforced at send time but not listed — `get(email)` explains one.
4988
+ * Narrow it with `q` (part of the address), `reason` and a `created_after`
4989
+ * / `created_before` range.
1757
4990
  */
1758
- list(params?: ListParams & {
1759
- /** @deprecated Ignored since 2026-10-13: the list is always your own suppressions. */
1760
- scope?: "workspace" | "platform";
1761
- }): Result<ListResponse<Suppression>>;
1762
- /** Async-iterate every suppressed address. */
1763
- listAll(params?: ListParams): AsyncGenerator<Suppression, void, void>;
4991
+ list(params?: SuppressionListParams): Result<ListResponse<Suppression>>;
4992
+ /** Async-iterate every suppressed address (same filters as `list`). */
4993
+ listAll(params?: SuppressionListParams): AsyncGenerator<Suppression, void, void>;
1764
4994
  /**
1765
4995
  * Suppress one address (`{ email }`) or many (`{ emails: [...] }`). Idempotent
1766
4996
  * — re-suppressing an existing address is a no-op. The bulk form resolves to a
@@ -1772,6 +5002,158 @@ declare class Suppressions extends Resource {
1772
5002
  /** Un-suppress an address by id or email. Idempotent on the email form. */
1773
5003
  delete(idOrEmail: string): Result<null>;
1774
5004
  }
5005
+ /**
5006
+ * Files (`/files`, `file_` ids): bytes handed to the API for one `purpose`,
5007
+ * which an operation then takes by `file_id` (a brand document, the SMS
5008
+ * opt-in evidence on a quote or resubmission, a library image, the logo).
5009
+ * A file is private, metadata-only on the API, and expires 24 hours after it
5010
+ * is created; what uses it keeps its own copy. `sms_*` purposes need
5011
+ * `sms:manage`, `image` needs `templates:write` or `branding:write` (ADR-0159).
5012
+ */
5013
+ declare class Files extends Resource {
5014
+ /** The workspace's unexpired files, newest first (cursor-paginated; `purpose` filters). */
5015
+ list(params?: FileListParams): Result<ListResponse<File>>;
5016
+ /**
5017
+ * Create a file (201) one of three ways: a public https `url` (fetched
5018
+ * once, no redirects, no private addresses), base64 `data` with its
5019
+ * `content_type` (up to about 4 MB), or neither, with `content_type` and
5020
+ * `size_bytes`: an upload session, whose `upload` says where to PUT the
5021
+ * bytes (`files.upload` does all of this for a local file). The bytes
5022
+ * decide the type. Pass an `idempotencyKey` so a retry makes one file; one
5023
+ * is generated when you don't.
5024
+ */
5025
+ create(body: FileCreate, opts?: SendOptions): Result<File>;
5026
+ /**
5027
+ * One file's metadata (never its bytes). Reading an `awaiting_upload` file
5028
+ * checks its upload, which makes it `ready` or `failed`.
5029
+ */
5030
+ get(id: string): Result<File>;
5031
+ /** Delete a file before it expires. What already used it keeps its copy. */
5032
+ delete(id: string): Result<null>;
5033
+ /**
5034
+ * Upload a local file or bytes and return the file, checked. Up to 3 MB it
5035
+ * is sent inline (base64 `data`); a larger one opens an upload session,
5036
+ * PUTs the bytes to its `upload.url` with exactly `upload.headers`, then
5037
+ * reads the file back, so the answer is `ready` or `failed`. The
5038
+ * `idempotencyKey` (generated when you don't pass one) is the create's.
5039
+ */
5040
+ upload(input: FileUploadInput, opts?: SendOptions): Result<File>;
5041
+ }
5042
+ /**
5043
+ * The workspace's image library: the images a template embeds. Each image's
5044
+ * `path` (`/img/…`) is what a template's `<Image src>` (or `<img src>`) takes;
5045
+ * `url` is its public address. Reads need `templates:read`, writes
5046
+ * `templates:write`.
5047
+ */
5048
+ declare class LibraryImages extends Resource {
5049
+ /** The library, newest first (cursor-paginated). */
5050
+ list(params?: ListParams): Result<ListResponse<LibraryImage>>;
5051
+ /** Async-iterate every image in the library. */
5052
+ listAll(params?: ListParams): AsyncGenerator<LibraryImage, void, void>;
5053
+ /**
5054
+ * Add an image (201) from a public https `url` (fetched once, no redirects,
5055
+ * no private addresses) or base64 `data` with its `content_type`: PNG,
5056
+ * JPEG, GIF or WebP up to 5 MB, counted against the plan's image storage
5057
+ * (`403 limit_reached`). Pass an `idempotencyKey` so a retried upload stores
5058
+ * one image; one is generated when you don't.
5059
+ */
5060
+ create(body: LibraryImageCreate, opts?: SendOptions): Result<LibraryImage>;
5061
+ get(id: string): Result<LibraryImage>;
5062
+ /** Change the alt text the image suggests when it's inserted (`null` or `""` clears it). */
5063
+ update(id: string, body: LibraryImageUpdate): Result<LibraryImage>;
5064
+ /**
5065
+ * Remove an image from the library. While a template, a campaign or sent
5066
+ * mail uses it, the answer is a `409` `resource_in_use` naming them
5067
+ * (`details`). `{ force: true }` (sent as `?force=true`) deletes it anyway:
5068
+ * those emails then show a broken image wherever it isn't cached yet.
5069
+ */
5070
+ delete(id: string, params?: {
5071
+ force?: boolean;
5072
+ }): Result<null>;
5073
+ }
5074
+ /**
5075
+ * The look marketing emails' footer and the hosted unsubscribe page share, as
5076
+ * Settings → Brand shows it. Reading it needs `templates:read`; the writes
5077
+ * need `branding:write`, which no key preset grants: tick it on the key.
5078
+ */
5079
+ declare class Branding extends Resource {
5080
+ /** Colors, font, company name and postal address, the unsubscribe page, the footer, the logo; `null` means the default. */
5081
+ get(): Result<Branding$1>;
5082
+ /**
5083
+ * Change branding: only the fields you send change, and `null` restores a
5084
+ * default. Hiding the "Sent with Unitpost" mark needs a paid plan
5085
+ * (`403 limit_reached`).
5086
+ */
5087
+ update(body: BrandingUpdate): Result<Branding$1>;
5088
+ /** Replace the logo, from a public https `url` or base64 `data` (PNG, JPEG, GIF or WebP, up to 5 MB). */
5089
+ setLogo(body: ImageUpload): Result<Branding$1>;
5090
+ /** Clear the brand logo (the workspace image shows instead, else none). It sends no body and answers the branding. */
5091
+ removeLogo(): Result<Branding$1>;
5092
+ }
5093
+ /**
5094
+ * The calling credential (`whoami`, which any valid credential may read), the
5095
+ * activity log (`listActivity`, which needs `activity:read`), and the
5096
+ * workspace's name and image. `update`, `setImage` and `removeImage` need
5097
+ * `branding:write`. No key preset grants either capability: tick it on the
5098
+ * key. Deleting the workspace stays in the dashboard.
5099
+ */
5100
+ declare class Workspace extends Resource {
5101
+ /**
5102
+ * Who is calling: the workspace, the credential (an API key or an OAuth
5103
+ * sign-in, never its secret), its `capabilities` and the workspace's rate
5104
+ * limit. Call it first to see what the credential may do: a call that needs
5105
+ * a capability it lacks answers `403 insufficient_scope`. It needs no
5106
+ * capability: any valid credential may read it.
5107
+ */
5108
+ whoami(): Result<Whoami>;
5109
+ /**
5110
+ * The workspace activity log, newest first (cursor-paginated, `act_` ids):
5111
+ * what changed, when, who changed it (`actor.name`: a teammate, `System`,
5112
+ * `Ask Unit`) and, for a change made over the API, MCP or Ask Unit, how
5113
+ * (`actor.via`, with the API key). The rows the dashboard's Activity page
5114
+ * and each record's timeline show. Narrow it with `subject` (and
5115
+ * `subject_id`), `contact_id`, `campaign_id`, `q` and `channel: "email"`;
5116
+ * an unknown filter is a `422`. Needs `activity:read`, which no key preset
5117
+ * includes: the log names your teammates.
5118
+ */
5119
+ listActivity(params?: ActivityListParams): Result<ListResponse<Activity>>;
5120
+ /** Async-iterate every activity row (same filters as `listActivity`). */
5121
+ listAllActivity(params?: ActivityListParams): AsyncGenerator<Activity, void, void>;
5122
+ /** Rename the workspace. */
5123
+ update(body: WorkspaceUpdate): Result<Workspace$1>;
5124
+ /**
5125
+ * Replace the workspace image (its avatar in the dashboard, and the email
5126
+ * logo when there's no brand logo), from a public https `url` or base64
5127
+ * `data` (PNG, JPEG, GIF or WebP, up to 5 MB).
5128
+ */
5129
+ setImage(body: ImageUpload): Result<Workspace$1>;
5130
+ /** Clear the workspace image. It sends no body and answers the workspace. */
5131
+ removeImage(): Result<Workspace$1>;
5132
+ }
5133
+ /**
5134
+ * The workspace's monthly spend caps and what each counted this UTC calendar
5135
+ * month. `sms_purchases` caps the SMS carrier purchases API keys and apps
5136
+ * confirm (`sms.quotes.confirm`). Reading needs `sms:read`, `sms:purchase` or
5137
+ * `spend_caps:write`; `update()` needs `spend_caps:write`, which no key preset
5138
+ * includes and only the workspace owner can give a key.
5139
+ */
5140
+ declare class SpendCaps extends Resource {
5141
+ /**
5142
+ * `{ object: "spend_caps", sms_purchases: { cap_cents, max_cents,
5143
+ * spent_cents, period_start, period_end } }`. A `cap_cents` of `null` means
5144
+ * none, so every API purchase is refused with `403 api_spend_cap_not_set`;
5145
+ * the cap that applies is the lower of `cap_cents` and `max_cents`.
5146
+ */
5147
+ get(): Result<SpendCaps$1>;
5148
+ /**
5149
+ * Set caps: `{ sms_purchases: { cap_cents } }` in whole cents (>= 0), or
5150
+ * `null` to clear it. Only the caps you send change. A workspace its
5151
+ * organization pays for answers `403 billed_by_organization`: its
5152
+ * organization sets the cap with `sms_purchases_cap_cents` on the
5153
+ * organization's workspace update.
5154
+ */
5155
+ update(body: SpendCapsUpdate): Result<SpendCaps$1>;
5156
+ }
1775
5157
  declare class Usage extends Resource {
1776
5158
  /**
1777
5159
  * Retrieve the current billing-period usage snapshot: plan, period window,
@@ -1793,11 +5175,201 @@ declare class Unitpost {
1793
5175
  readonly jobs: Jobs;
1794
5176
  readonly segments: Segments;
1795
5177
  readonly brandKits: BrandKits;
5178
+ /** The image library templates embed (`/img/…` paths). */
5179
+ readonly libraryImages: LibraryImages;
5180
+ /** Files handed to the API for one purpose, used by `file_id` (`upload()` sends a local file). */
5181
+ readonly files: Files;
5182
+ /** The email footer and unsubscribe page look. Writes need `branding:write` (on no key preset). */
5183
+ readonly branding: Branding;
5184
+ /** Who is calling (`whoami`, any credential), the activity log (`listActivity`, needs `activity:read`, on no key preset), and the workspace's name and image; the writes need `branding:write` (on no key preset). */
5185
+ readonly workspace: Workspace;
1796
5186
  readonly webhooks: Webhooks;
1797
5187
  readonly apiKeys: ApiKeys;
5188
+ /** The API request log (`list()`, needs `apikeys:read`, on no key preset). */
5189
+ readonly logs: Logs;
1798
5190
  readonly suppressions: Suppressions;
1799
5191
  readonly usage: Usage;
5192
+ /** Monthly spend caps (`get()`, `update()`); `update()` needs `spend_caps:write`, on no key preset. */
5193
+ readonly spendCaps: SpendCaps;
1800
5194
  constructor(apiKeyOrOptions?: string | UnitpostOptions);
1801
5195
  }
1802
5196
 
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 };
5197
+ interface UnitpostOrganizationOptions extends Omit<UnitpostOptions, "apiKey"> {
5198
+ /** Organization key (`ok_live_…`). Defaults to `process.env.UNITPOST_ORG_KEY`. */
5199
+ apiKey?: string;
5200
+ /** The organization's id (`org_…`). Defaults to `process.env.UNITPOST_ORGANIZATION_ID`. */
5201
+ organizationId?: string;
5202
+ }
5203
+ /** Filters for `workspaces.list` / `workspaces.listAll`. */
5204
+ type OrganizationWorkspaceListParams = ListParams & {
5205
+ /** Only the workspace you gave this id (`external_id`). */
5206
+ external_id?: string;
5207
+ };
5208
+ /** Filters for `webhooks.listDeliveries` / `webhooks.listAllDeliveries`: the workspace endpoint's, plus which workspace. */
5209
+ type OrganizationWebhookDeliveryListParams = WebhookDeliveryListParams & {
5210
+ /** Only deliveries about this workspace (`ws_…`). */
5211
+ workspace_id?: string;
5212
+ /** Only deliveries about the workspace you gave this id. */
5213
+ external_id?: string;
5214
+ };
5215
+ /** Filters for `usage.list` / `usage.listAll`. */
5216
+ type OrganizationUsageListParams = {
5217
+ /** `current` (default), or an ISO 8601 instant: each workspace's billing period containing it. */
5218
+ period?: string;
5219
+ /** Only the workspace you gave this id. */
5220
+ external_id?: string;
5221
+ /** Workspaces per page, 1–25 (default 10). */
5222
+ limit?: number;
5223
+ /** Next page: the last row's `workspace_id`. */
5224
+ after?: string;
5225
+ /** Previous page: the first row's `workspace_id`. Not with `after`. */
5226
+ before?: string;
5227
+ };
5228
+ declare class UnitpostOrganization {
5229
+ /** The organization every call acts on (`org_…`). */
5230
+ readonly organizationId: string;
5231
+ /** The organization's workspaces: list, create, get, update, close, restore. */
5232
+ readonly workspaces: OrganizationWorkspaces;
5233
+ /** Keys for one of the organization's workspaces: `create` mints one (the secret is in that answer only). */
5234
+ readonly workspaceKeys: OrganizationWorkspaceKeys;
5235
+ /** The organization's webhook endpoints: events from every workspace it owns, each with `workspace_id` and `external_id`. */
5236
+ readonly webhooks: OrganizationWebhooks;
5237
+ /** Usage per workspace for a billing period (`list`). */
5238
+ readonly usage: OrganizationUsage;
5239
+ /** A plan change for one workspace the organization pays for: quote, read, confirm. */
5240
+ readonly planQuotes: OrganizationPlanQuotes;
5241
+ /** The organization's shared plan: read it, and add, cap or remove the workspaces on it. */
5242
+ readonly sharedPlan: OrganizationSharedPlan;
5243
+ constructor(options?: UnitpostOrganizationOptions);
5244
+ }
5245
+ declare class OrganizationResource {
5246
+ protected readonly http: HttpClient;
5247
+ protected readonly organizationId: string;
5248
+ constructor(http: HttpClient, organizationId: string);
5249
+ }
5250
+ declare class OrganizationWorkspaces extends OrganizationResource {
5251
+ /** The organization's workspaces, newest first (cursor-paginated). Needs `organizations:read`. */
5252
+ list(params?: OrganizationWorkspaceListParams): Result<ListResponse<OrganizationWorkspace>>;
5253
+ /** Async-iterate every workspace of the organization (same filters as `list`). */
5254
+ listAll(params?: OrganizationWorkspaceListParams): AsyncGenerator<OrganizationWorkspace, void, void>;
5255
+ /**
5256
+ * Create a workspace (201). Its Owner is the key's creator. An
5257
+ * Idempotency-Key is generated when you don't pass one, so a retry can't
5258
+ * make two. Needs `organizations:write`.
5259
+ */
5260
+ create(body: OrganizationWorkspaceCreate, opts?: SendOptions): Result<OrganizationWorkspace>;
5261
+ /** One workspace (`ws_…`). Needs `organizations:read`. */
5262
+ get(workspaceId: string): Result<OrganizationWorkspace>;
5263
+ /** Rename it, set its `external_id` or its SMS purchases cap. Needs `organizations:write`. */
5264
+ update(workspaceId: string, body: OrganizationWorkspaceUpdate): Result<OrganizationWorkspace>;
5265
+ /**
5266
+ * Close it: it stops sending at once. It can be restored for 30 days
5267
+ * (`restorable_until`); unless restored, it is deleted once those 30 days
5268
+ * are over and 7 days have passed since the end of the billing period it
5269
+ * closed in, whichever is later (`deletes_at`). Closing twice changes
5270
+ * nothing. Needs `organizations:write`.
5271
+ */
5272
+ close(workspaceId: string): Result<OrganizationWorkspace>;
5273
+ /** Restore a closed workspace within its 30 days. Needs `organizations:write`. */
5274
+ restore(workspaceId: string): Result<OrganizationWorkspace>;
5275
+ }
5276
+ declare class OrganizationWorkspaceKeys extends OrganizationResource {
5277
+ /**
5278
+ * Mint a workspace key (201) for one of the organization's workspaces. The
5279
+ * answer holds the secret (`key`) once; use it with `new Unitpost(key)`.
5280
+ * Needs `organizations:write`.
5281
+ */
5282
+ create(workspaceId: string, body: WorkspaceKeyMint): Result<MintedWorkspaceKey>;
5283
+ }
5284
+ declare class OrganizationWebhooks extends OrganizationResource {
5285
+ /** The organization's webhook endpoints. Needs `organizations:read`. */
5286
+ list(params?: ListParams): Result<ListResponse<Webhook>>;
5287
+ /** Async-iterate every webhook endpoint of the organization. Needs `organizations:read`. */
5288
+ listAll(params?: ListParams): AsyncGenerator<Webhook, void, void>;
5289
+ /** Create an endpoint. The answer has `signing_secret` exactly once. Needs `organizations:write`. */
5290
+ create(body: WebhookCreate): Result<WebhookCreated>;
5291
+ /** One endpoint (`wh_…`). Needs `organizations:read`. */
5292
+ get(webhookId: string): Result<Webhook>;
5293
+ update(webhookId: string, body: WebhookUpdate): Result<Webhook>;
5294
+ delete(webhookId: string): Result<null>;
5295
+ /** Mint a new signing secret; the answer carries it exactly once. */
5296
+ rotateSecret(webhookId: string): Result<WebhookSecretRotated>;
5297
+ /** Fire a sample event at the endpoint. */
5298
+ test(webhookId: string): Result<WebhookTestResult>;
5299
+ /**
5300
+ * The endpoint's delivery log, newest first; each row names its
5301
+ * `workspace_id` and `external_id`. Needs `organizations:write` (the rows
5302
+ * carry each event's data, so `organizations:read` alone is a 403).
5303
+ */
5304
+ listDeliveries(webhookId: string, params?: OrganizationWebhookDeliveryListParams): Result<ListResponse<OrganizationWebhookDelivery>>;
5305
+ /** Async-iterate the endpoint's whole delivery log (same filters as `listDeliveries`). Needs `organizations:write`. */
5306
+ listAllDeliveries(webhookId: string, params?: OrganizationWebhookDeliveryListParams): AsyncGenerator<OrganizationWebhookDelivery, void, void>;
5307
+ /** Deliver one event to the endpoint again (202). */
5308
+ replayDelivery(webhookId: string, deliveryId: string): Result<WebhookDeliveryReplay>;
5309
+ /** Deliver the backlog (202); `include_failed: true` adds the ones that failed for good. */
5310
+ flush(webhookId: string, body?: WebhookFlush): Result<WebhookFlushResult>;
5311
+ /** Verify a delivery's signature and return the parsed event (the top-level `verifyWebhook`). */
5312
+ verify<T = unknown>(args: VerifyWebhookArgs): T;
5313
+ }
5314
+ declare class OrganizationUsage extends OrganizationResource {
5315
+ /**
5316
+ * Usage per workspace (`workspace_usage` rows), each for that workspace's
5317
+ * own billing period containing `period`. Paged by workspace. Needs
5318
+ * `organizations:read`.
5319
+ */
5320
+ list(params?: OrganizationUsageListParams): Result<ListResponse<OrganizationWorkspaceUsage>>;
5321
+ /**
5322
+ * Async-iterate the usage row of every workspace (same filters as `list`),
5323
+ * paging by the last row's `workspace_id`. Needs `organizations:read`.
5324
+ */
5325
+ listAll(params?: OrganizationUsageListParams): AsyncGenerator<OrganizationWorkspaceUsage, void, void>;
5326
+ }
5327
+ declare class OrganizationPlanQuotes extends OrganizationResource {
5328
+ /**
5329
+ * Price a plan change for one workspace the organization pays for (201).
5330
+ * Charges nothing; the quote lasts 10 minutes and holds a single-use
5331
+ * `confirm_token` (only in this answer). Its `pending_change` is a
5332
+ * downgrade already scheduled for the period end, or null; with one, a
5333
+ * quote for the current plan and tier is a `noop` whose confirm cancels
5334
+ * it. Needs `organizations:billing`.
5335
+ */
5336
+ create(workspaceId: string, body: OrganizationPlanQuoteCreate): Result<OrganizationPlanQuote>;
5337
+ /** One quote (`pq_…`). Needs `organizations:read`. */
5338
+ get(workspaceId: string, quoteId: string): Result<OrganizationPlanQuote>;
5339
+ /**
5340
+ * Apply the quoted change and charge it. An Idempotency-Key is generated
5341
+ * when you don't pass one, so a retry can't charge twice. Needs
5342
+ * `organizations:billing`.
5343
+ */
5344
+ confirm(workspaceId: string, quoteId: string, body: OrganizationPlanQuoteConfirm, opts?: SendOptions): Result<OrganizationPlanQuote>;
5345
+ }
5346
+ declare class OrganizationSharedPlan extends OrganizationResource {
5347
+ /**
5348
+ * The organization's shared plan (one plan whose allowance its workspaces
5349
+ * share): whether it's turned on (`approved`), its `status` (`none` until
5350
+ * one is bought), plan, price and period, and this period's
5351
+ * `used_cents`, `overage_cents`, `paused`. Buying, upgrading and ending it
5352
+ * are done in the dashboard. Needs `organizations:read`.
5353
+ */
5354
+ get(): Result<OrganizationSharedPlan$1>;
5355
+ /** Every workspace on the shared plan, with its cap and what it drew this period (one page). Needs `organizations:read`. */
5356
+ listWorkspaces(): Result<ListResponse<OrganizationSharedPlanWorkspace>>;
5357
+ /**
5358
+ * Put a workspace on the shared plan (it moves onto the organization's
5359
+ * card), or set its cap when it's already on it. Refusals carry the reason
5360
+ * in `error.details[0].code` (`own_plan`, `limit_reached`, …). An
5361
+ * Idempotency-Key is generated when you don't pass one, so a retry answers
5362
+ * what the first call did. Needs `organizations:billing`.
5363
+ */
5364
+ addWorkspace(workspaceId: string, body?: OrganizationSharedPlanWorkspaceAdd, opts?: SendOptions): Result<OrganizationSharedPlanWorkspace>;
5365
+ /** Set a workspace's cap (`cap_cents`; null removes it). Needs `organizations:billing`. */
5366
+ updateWorkspace(workspaceId: string, body: OrganizationSharedPlanWorkspaceUpdate): Result<OrganizationSharedPlanWorkspace>;
5367
+ /**
5368
+ * Take a workspace off the shared plan: `drops_to` is `free` or
5369
+ * `needs_plan`; one not on it answers `left: false`. An Idempotency-Key is
5370
+ * generated when you don't pass one. Needs `organizations:billing`.
5371
+ */
5372
+ removeWorkspace(workspaceId: string, opts?: SendOptions): Result<OrganizationSharedPlanRemoval>;
5373
+ }
5374
+
5375
+ export { type ActivityListParams, type ApiFieldError, type ApiResult, type ContactListParams, type EmailListParams, type EmailStatsParams, type FileListParams, type FileUploadInput, type ListParams, type ListResponse, type LogListParams, models as Models, type OrganizationUsageListParams, type OrganizationWebhookDeliveryListParams, type OrganizationWorkspaceListParams, type Result, SDK_VERSION, type SendOptions, type SmsListParams, type SuppressionListParams, Unitpost, UnitpostError, type UnitpostOptions, UnitpostOrganization, type UnitpostOrganizationOptions, type VerifyWebhookArgs, type WebhookDeliveryListParams, WebhookVerificationError, verifyWebhook };