unitpost 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- declare const SDK_VERSION = "0.1.0";
1
+ declare const SDK_VERSION = "0.4.0";
2
2
  interface ApiFieldError {
3
3
  /** Dotted path to the offending field, e.g. "template.variables.first_name". */
4
4
  field: string;
@@ -129,9 +129,10 @@ type ApiKey = {
129
129
  type ApiKeyCreate = {
130
130
  name: string;
131
131
  scope?: "full" | "sending" | "read_only";
132
- capabilities?: Array<"contacts:read" | "contacts:write" | "suppressions:read" | "suppressions:write" | "segments:read" | "segments:write" | "topics:read" | "topics:write" | "templates:read" | "templates:write" | "components:read" | "components:write" | "campaigns:read" | "campaigns:write" | "campaigns:send" | "domains:read" | "domains:write" | "emails:read" | "emails:send" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
132
+ capabilities?: Array<"contacts:read" | "contacts:write" | "suppressions:read" | "suppressions:write" | "segments:read" | "segments:write" | "topics:read" | "topics:write" | "templates:read" | "templates:write" | "components:read" | "components:write" | "campaigns:read" | "campaigns:write" | "campaigns:send" | "domains:read" | "domains:write" | "emails:read" | "emails:send" | "sms:read" | "sms:send" | "sms:manage" | "sms:purchase" | "apikeys:read" | "apikeys:manage" | "webhooks:read" | "webhooks:manage" | "team:read" | "team:invite" | "team:manage_members" | "workspace:update" | "workspace:delete" | "billing:manage">;
133
133
  };
134
134
  type ApiKeyCreated = ApiKey & {
135
+ /** The plaintext secret. Shown exactly once — store it now; it can never be retrieved again. */
135
136
  key: string;
136
137
  };
137
138
  type Batch = {
@@ -140,49 +141,62 @@ type Batch = {
140
141
  count: number;
141
142
  scheduled_at: string | null;
142
143
  created_at: string;
144
+ /** Live child counts keyed by status (e.g. { delivered: 98, failed: 2 }). */
143
145
  status_counts: Record<string, number>;
144
146
  cancelable: number;
145
147
  };
146
148
  type BatchSend = Array<{
149
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
147
150
  from: string;
148
151
  to: string | Array<string>;
149
152
  subject?: string;
150
153
  cc?: string | Array<string>;
151
154
  bcc?: string | Array<string>;
152
155
  reply_to?: string | Array<string>;
156
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
153
157
  in_reply_to?: string;
158
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
154
159
  headers?: Record<string, string>;
155
160
  tags?: Array<{
156
161
  name: string;
157
162
  value: string;
158
163
  }>;
164
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
159
165
  template?: {
160
166
  id: string;
161
167
  variables?: Record<string, string | number>;
162
168
  };
169
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
163
170
  html?: string;
171
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
164
172
  text?: string;
165
173
  open_tracking?: boolean;
166
174
  click_tracking?: boolean;
167
175
  }> | {
168
176
  emails: Array<{
177
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
169
178
  from: string;
170
179
  to: string | Array<string>;
171
180
  subject?: string;
172
181
  cc?: string | Array<string>;
173
182
  bcc?: string | Array<string>;
174
183
  reply_to?: string | Array<string>;
184
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
175
185
  in_reply_to?: string;
186
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
176
187
  headers?: Record<string, string>;
177
188
  tags?: Array<{
178
189
  name: string;
179
190
  value: string;
180
191
  }>;
192
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
181
193
  template?: {
182
194
  id: string;
183
195
  variables?: Record<string, string | number>;
184
196
  };
197
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
185
198
  html?: string;
199
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
186
200
  text?: string;
187
201
  open_tracking?: boolean;
188
202
  click_tracking?: boolean;
@@ -191,6 +205,7 @@ type BatchSend = Array<{
191
205
  };
192
206
  type BatchSendResult = {
193
207
  object: "list";
208
+ /** Handle for GET / cancel on /email/batches/{id}. */
194
209
  batch_id: string;
195
210
  status: "queued" | "scheduled";
196
211
  scheduled_at: string | null;
@@ -284,9 +299,33 @@ type Campaign = {
284
299
  scheduled_at: string | null;
285
300
  variable_fallbacks: Record<string, string>;
286
301
  excluded_contact_ids: Array<string>;
302
+ /** Recipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate. */
287
303
  total_recipients: number;
304
+ /** The audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only. */
305
+ projected_recipients?: {
306
+ total: number;
307
+ reachable: number;
308
+ skipped: number;
309
+ } | null;
288
310
  sent_count: number;
289
311
  failed_count: number;
312
+ pause_reason: {
313
+ code: "user" | "hard_bounce_rate" | "complaint_rate" | "quality_review" | "provider_limit" | "failure_streak" | "sender_unavailable" | "template_unavailable" | "billing" | "not_drained" | "sending_restricted" | "workspace_suspended";
314
+ message: string | null;
315
+ metric: "hard_bounce_rate" | "complaint_rate" | null;
316
+ value: number | null;
317
+ threshold: number | null;
318
+ sample: {
319
+ events: number;
320
+ of: number;
321
+ } | null;
322
+ window: {
323
+ since: string | null;
324
+ } | null;
325
+ decided_by: "floor" | "unit" | null;
326
+ resume: "self_serve" | "review_required" | "account_review" | "resume_slowly" | null;
327
+ paused_at: string | null;
328
+ } | null;
290
329
  created_at: string;
291
330
  updated_at: string;
292
331
  };
@@ -299,6 +338,7 @@ type CampaignCreate = {
299
338
  from: string;
300
339
  subject?: string;
301
340
  preview_text?: string;
341
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`. */
302
342
  scheduled_at?: string;
303
343
  open_tracking?: boolean | null;
304
344
  click_tracking?: boolean | null;
@@ -306,8 +346,12 @@ type CampaignCreate = {
306
346
  excluded_contact_ids?: Array<string>;
307
347
  };
308
348
  type CampaignReschedule = {
349
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; returned in UTC. A time without a timezone is read as UTC (deprecated: include the zone). */
309
350
  scheduled_at: string;
310
351
  };
352
+ type CampaignSend = {
353
+ scheduled_at?: string | null;
354
+ };
311
355
  type CampaignUpdate = {
312
356
  archived?: boolean;
313
357
  topic_id?: string | null;
@@ -315,11 +359,12 @@ type CampaignUpdate = {
315
359
  click_tracking?: boolean | null;
316
360
  variable_fallbacks?: Record<string, string>;
317
361
  excluded_contact_ids?: Array<string>;
362
+ scheduled_at?: string | null;
318
363
  };
319
364
  type Contact = {
320
365
  object: "contact";
321
366
  id: string;
322
- email: string;
367
+ email: string | null;
323
368
  first_name: string | null;
324
369
  last_name: string | null;
325
370
  unsubscribed: boolean;
@@ -342,6 +387,7 @@ type ContactField = {
342
387
  key: string;
343
388
  label: string;
344
389
  type: "text" | "number" | "boolean" | "date";
390
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
345
391
  default_value: string | null;
346
392
  position: number;
347
393
  created_at: string;
@@ -351,6 +397,7 @@ type ContactFieldCreate = {
351
397
  key: string;
352
398
  label: string;
353
399
  type?: "text" | "number" | "boolean" | "date";
400
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
354
401
  default_value?: string | null;
355
402
  };
356
403
  type ContactFieldRename = {
@@ -360,12 +407,13 @@ type ContactFieldUpdate = {
360
407
  label?: string;
361
408
  type?: "text" | "number" | "boolean" | "date";
362
409
  position?: number;
410
+ /** The value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value. */
363
411
  default_value?: string | null;
364
412
  };
365
413
  type ContactImport = {
366
414
  object: "contact_import";
367
415
  id: string;
368
- status: "pending" | "processing" | "completed" | "failed";
416
+ status: "pending" | "processing" | "completed" | "failed" | "canceled";
369
417
  total: number;
370
418
  imported: number;
371
419
  skipped: number;
@@ -384,11 +432,15 @@ type ContactImportCreate = {
384
432
  first_name?: string;
385
433
  last_name?: string;
386
434
  custom_fields?: Record<string, string | number | boolean | null>;
435
+ /** Create this contact already unsubscribed (`true`, or a string `true`/`1`/`yes`/`y`). One-way: it never clears an opt-out, and an existing contact is skipped entirely. */
436
+ unsubscribed?: boolean | string;
387
437
  }>;
388
438
  };
389
439
  type ContactTopic = {
390
440
  object: "contact_topic";
391
441
  topic_id: string;
442
+ /** The topic's channel: manage it under `/email/topics` or `/sms/topics`. */
443
+ channel: "email" | "sms";
392
444
  subscribed: boolean;
393
445
  status: "subscribed" | "unsubscribed";
394
446
  source: "user" | "manual" | "import" | "api";
@@ -420,6 +472,7 @@ type Domain = {
420
472
  click_tracking: boolean | null;
421
473
  tls: "opportunistic" | "enforced";
422
474
  tracking_subdomain: string | null;
475
+ /** When tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null. */
423
476
  tracking_verified_at: string | null;
424
477
  verified_at: string | null;
425
478
  created_at: string;
@@ -428,6 +481,42 @@ type Domain = {
428
481
  type DomainCreate = {
429
482
  name: string;
430
483
  };
484
+ type DomainDiagnosis = {
485
+ object: "domain_diagnosis";
486
+ domain_id: string;
487
+ domain: string;
488
+ /** The domain's stored status, next to the live diagnosis. */
489
+ status: string;
490
+ checked_at: string;
491
+ /** The last verify check, which this call does not change. */
492
+ last_checked_at?: string | null;
493
+ /** Whether a verify run now would mark the domain verified. */
494
+ would_verify: boolean;
495
+ /** The zone whose nameservers were asked; null when none was found. */
496
+ zone?: string | null;
497
+ nameservers?: Array<{
498
+ host?: string;
499
+ ips?: Array<string>;
500
+ }>;
501
+ /** The email provider's view of the sending identity. */
502
+ provider?: {
503
+ configured?: boolean;
504
+ identity_exists?: boolean | null;
505
+ dkim_status?: string | null;
506
+ mail_from_status?: string | null;
507
+ error?: string | null;
508
+ };
509
+ /** Every expected record, with each nameserver's answer and a `verdict` (`ok`, `partial`, `wrong`, `missing`, `unknown`). */
510
+ records: Array<Record<string, unknown>>;
511
+ /** What is wrong, most serious first, each with the concrete `fix`. */
512
+ findings: Array<{
513
+ code: string;
514
+ severity: "blocking" | "warning" | "info";
515
+ title: string;
516
+ detail: string;
517
+ fix: string;
518
+ }>;
519
+ };
431
520
  type DomainUpdate = {
432
521
  open_tracking?: boolean | null;
433
522
  click_tracking?: boolean | null;
@@ -458,7 +547,9 @@ type EmailPatch = {
458
547
  scheduled_at?: string;
459
548
  };
460
549
  type EmailStats = {
550
+ /** The rolling window, in days. */
461
551
  windowDays: number;
552
+ /** Non-null when the requested window exceeded the plan's log retention and was clamped to this many days (data past the retention horizon is purged). */
462
553
  clampedToRetentionDays?: number | null;
463
554
  totals: {
464
555
  sent: number;
@@ -469,6 +560,7 @@ type EmailStats = {
469
560
  complained: number;
470
561
  failed: number;
471
562
  };
563
+ /** Percentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered. */
472
564
  rates: {
473
565
  delivery: number;
474
566
  open: number;
@@ -479,17 +571,37 @@ type EmailStats = {
479
571
  };
480
572
  type Error$1 = {
481
573
  error: {
574
+ /** Stable machine-readable error code (branch on this, not the message). */
482
575
  code: string;
576
+ /** Human-readable summary. For validation errors it's path-prefixed (e.g. "template.variables.first_name: …"). */
483
577
  message: string;
578
+ /** Present on errors that carry per-field reasons: validation errors (422), a blocked campaign send (409), and a plan that doesn't include a feature (403 `limit_reached` with one entry whose `code` is `feature_not_in_plan` and whose `field` names the feature, e.g. `smsChannel`). One entry per offending field/blocker. */
484
579
  details?: Array<{
580
+ /** Dotted path to the field, e.g. "template.variables.first_name" (empty for a whole-body problem). */
485
581
  field: string;
582
+ /** Machine-readable reason for this entry, when there is one (e.g. `template_not_published` on `template_id` for a blocked SMS campaign send, or `feature_not_in_plan` on `smsChannel` when the plan has no SMS). Absent on plain validation errors. */
583
+ code?: string;
486
584
  message: string;
487
585
  }>;
488
586
  };
489
587
  };
588
+ type Job = {
589
+ object: "job";
590
+ id: string;
591
+ kind: string;
592
+ status: "QUEUED" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELED";
593
+ total: number | null;
594
+ processed: number;
595
+ failed: number;
596
+ error: string | null;
597
+ created_at: string;
598
+ completed_at: string | null;
599
+ };
490
600
  type ReceivedAttachmentUrl = {
491
601
  object: "received_attachment_url";
602
+ /** A signed, expiring URL to download the attachment bytes. */
492
603
  url: string;
604
+ /** ISO 8601 expiry of the signed URL (~5 minutes out). */
493
605
  expires_at: string;
494
606
  };
495
607
  type ReceivedEmail = {
@@ -548,6 +660,7 @@ type Segment = {
548
660
  name: string;
549
661
  description: string | null;
550
662
  type: "static" | "dynamic";
663
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
551
664
  filter: unknown | null;
552
665
  created_at: string;
553
666
  updated_at: string;
@@ -556,6 +669,7 @@ type SegmentCreate = {
556
669
  name: string;
557
670
  description?: string;
558
671
  type?: "static" | "dynamic";
672
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
559
673
  filter?: unknown;
560
674
  };
561
675
  type SegmentMember = {
@@ -571,26 +685,33 @@ type SegmentMemberAdd = {
571
685
  type SegmentUpdate = {
572
686
  name?: string;
573
687
  description?: string | null;
688
+ /** Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value. */
574
689
  filter?: unknown;
575
690
  };
576
691
  type SendEmail = {
692
+ /** Sender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message. */
577
693
  from: string;
578
694
  to: string | Array<string>;
579
695
  subject?: string;
580
696
  cc?: string | Array<string>;
581
697
  bcc?: string | Array<string>;
582
698
  reply_to?: string | Array<string>;
699
+ /** Id of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`. */
583
700
  in_reply_to?: string;
701
+ /** Custom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient. */
584
702
  headers?: Record<string, string>;
585
703
  tags?: Array<{
586
704
  name: string;
587
705
  value: string;
588
706
  }>;
707
+ /** Published template plus variable values. Mutually exclusive with `html` and `text`. */
589
708
  template?: {
590
709
  id: string;
591
710
  variables?: Record<string, string | number>;
592
711
  };
712
+ /** HTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown. */
593
713
  html?: string;
714
+ /** Plain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged. */
594
715
  text?: string;
595
716
  attachments?: Array<{
596
717
  filename: string;
@@ -601,6 +722,7 @@ type SendEmail = {
601
722
  }>;
602
723
  open_tracking?: boolean;
603
724
  click_tracking?: boolean;
725
+ /** Future send time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC (reads return UTC). Up to 90 days ahead, fewer on some plans. A time in the past or under 30 seconds ahead sends immediately, so check the response `status`. */
604
726
  scheduled_at?: string;
605
727
  };
606
728
  type SendResult = {
@@ -608,6 +730,308 @@ type SendResult = {
608
730
  status: "queued" | "scheduled";
609
731
  scheduled_at: string | null;
610
732
  };
733
+ type Sms$1 = {
734
+ object: "sms";
735
+ id: string;
736
+ to: string;
737
+ from: string | null;
738
+ direction: "outbound" | "inbound";
739
+ status: "queued" | "scheduled" | "sending" | "sent" | "delivered" | "failed" | "suppressed" | "canceled" | "received";
740
+ type: "transactional" | "marketing";
741
+ body: string | null;
742
+ /** Billed units. Outbound: segments. Inbound: 1 when the received text was charged (1¢ in the US and Canada), else 0. */
743
+ segments: number;
744
+ /** Inbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise. */
745
+ in_reply_to: string | null;
746
+ /** Inbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound. */
747
+ received_at: string | null;
748
+ /** Inbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound. */
749
+ looks_like_opt_out: boolean;
750
+ country: string | null;
751
+ scheduled_at: string | null;
752
+ /** Legacy free-text error. Prefer `error.code`. */
753
+ last_error: string | null;
754
+ /** Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise. */
755
+ error: {
756
+ /** Why a message was skipped before reaching the carrier. `out_of_reach`: no sender covers the recipient's country; `unsupported_country`: no compliance rule for the country yet, or SMS to that country is paused for now (every message, transactional included, until it resumes); `no_phone`: the contact has no SMS handle; `opted_out`: STOP / suppression / unreachable; `no_marketing_consent`: marketing without express consent; `quiet_hours_deferred`: delayed to the recipient's local window; `sender_not_active`: the sender lost approval. */
757
+ code: "out_of_reach" | "unsupported_country" | "no_phone" | "opted_out" | "no_marketing_consent" | "quiet_hours_deferred" | "sender_not_active";
758
+ /** Human-readable sentence for `code`. */
759
+ message: string;
760
+ } | null;
761
+ created_at: string;
762
+ };
763
+ type SmsBrand = {
764
+ object: "sms_brand";
765
+ /** Prefixed brand id, e.g. `sbrand_…`. */
766
+ id: string;
767
+ /** Public-facing brand name. */
768
+ name: string;
769
+ /** Registered legal entity name. */
770
+ legal_name: string;
771
+ /** Brand website URL. */
772
+ website: string | null;
773
+ /** Registrable domain derived from the website. The brand contact email must be on this domain. */
774
+ domain: string | null;
775
+ contact_email: string | null;
776
+ /** `incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier. */
777
+ status: "incomplete" | "ready" | "pending" | "action_required" | "verified" | "rejected" | "archived";
778
+ /** Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing. */
779
+ missing: Array<string>;
780
+ /** True when the 10DLC brand registration is approved. */
781
+ ten_dlc_verified: boolean;
782
+ tax_id_on_file: boolean;
783
+ /** Non-released senders on this brand (phone numbers and Sender ID countries, any status). */
784
+ number_count: number;
785
+ /** False once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask. */
786
+ editable: boolean;
787
+ created_at: string;
788
+ };
789
+ type SmsCampaign = {
790
+ object: "sms_campaign";
791
+ id: string;
792
+ name: string;
793
+ status: "draft" | "scheduled" | "sending" | "paused" | "sent" | "canceled" | "failed";
794
+ type: "marketing" | "transactional";
795
+ template_id: string;
796
+ segment_id: string;
797
+ sender_id: string | null;
798
+ topic_id: string | null;
799
+ routing: "automatic" | "fixed" | "pool";
800
+ scheduled_at: string | null;
801
+ hold: {
802
+ reason: "scheduled" | "quiet_hours";
803
+ until: string | null;
804
+ } | null;
805
+ pause_reason: {
806
+ code: "user" | "budget_exhausted" | "plan_lapsed" | "sender_not_active" | "template_unavailable" | "workspace_suspended" | "sending_restricted" | "risk_throttled" | "sms_brand_blocked" | "subscription_inactive" | "not_drained";
807
+ message: string | null;
808
+ paused_at: string | null;
809
+ } | null;
810
+ projected_recipients: {
811
+ total: number;
812
+ reachable: number;
813
+ skipped: number;
814
+ } | null;
815
+ recipient_count: number;
816
+ variable_fallbacks: Record<string, string>;
817
+ excluded_contact_ids: Array<string>;
818
+ started_at: string | null;
819
+ completed_at: string | null;
820
+ canceled_at: string | null;
821
+ created_at: string;
822
+ updated_at: string;
823
+ };
824
+ type SmsCampaignCreate = {
825
+ name: string;
826
+ template_id: string;
827
+ segment_id: string;
828
+ sender_id?: string | null;
829
+ topic_id?: string | null;
830
+ excluded_contact_ids?: Array<string>;
831
+ variable_fallbacks?: Record<string, string>;
832
+ scheduled_at?: string | null;
833
+ };
834
+ type SmsCampaignReschedule = {
835
+ /** ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`. */
836
+ scheduled_at: string;
837
+ };
838
+ type SmsCampaignSend = {
839
+ scheduled_at?: string | null;
840
+ };
841
+ type SmsCampaignUpdate = {
842
+ archived?: boolean;
843
+ name?: string;
844
+ template_id?: string;
845
+ segment_id?: string;
846
+ sender_id?: string | null;
847
+ topic_id?: string | null;
848
+ excluded_contact_ids?: Array<string>;
849
+ variable_fallbacks?: Record<string, string>;
850
+ scheduled_at?: string | null;
851
+ };
852
+ type SmsCampaignValidation = {
853
+ object: "sms_campaign_validation";
854
+ campaign_id: string;
855
+ can_send: boolean;
856
+ blockers: Array<{
857
+ code: string;
858
+ message: string;
859
+ }>;
860
+ total: number;
861
+ reachable: number;
862
+ skipped: number;
863
+ no_marketing_consent: number;
864
+ quiet_hours_deferred: number;
865
+ skipped_by_reason: Array<{
866
+ reason: string;
867
+ count: number;
868
+ remedy: string;
869
+ }>;
870
+ routing: "automatic" | "fixed" | "pool";
871
+ earliest_start: {
872
+ at: string;
873
+ reason: "quiet_hours";
874
+ countries: Array<string>;
875
+ } | null;
876
+ use_case_mismatch: boolean;
877
+ unresolved_variables: Array<string>;
878
+ /** Per template variable that some recipients lack, missing-for-all first. `missing_for_all`: no recipient has it, so a `variable_fallbacks` default is REQUIRED to send. Otherwise a default is optional and only fills the `missing_count` blanks (it never replaces a recipient's own value); or exclude those contacts. `has_default`: the campaign already sets one. */
879
+ variable_coverage?: Array<{
880
+ name: string;
881
+ missing_count: number;
882
+ eligible: number;
883
+ missing_for_all: boolean;
884
+ has_default: boolean;
885
+ }>;
886
+ };
887
+ type SmsConsent = {
888
+ object: "sms_consent";
889
+ phone: string | null;
890
+ country?: string | null;
891
+ status: string;
892
+ marketing_eligible?: boolean;
893
+ consented_at?: string | null;
894
+ consent_source?: string | null;
895
+ consent_purpose?: string | null;
896
+ history: Array<{
897
+ id: string;
898
+ action: string;
899
+ source: string | null;
900
+ purpose: string | null;
901
+ occurred_at: string;
902
+ evidence_url: string | null;
903
+ disclosure_version: string | null;
904
+ }>;
905
+ };
906
+ type SmsConsentRecord = {
907
+ action: "opt_in" | "opt_out";
908
+ source: "web_form" | "hosted_form" | "keyword" | "qr" | "verbal" | "paper" | "api_import" | "api";
909
+ purpose?: "marketing" | "transactional";
910
+ phone?: string;
911
+ occurred_at?: string;
912
+ evidence_url?: string;
913
+ disclosure_version?: string;
914
+ };
915
+ type SmsConsentRecorded = {
916
+ object: "sms_consent";
917
+ phone: string;
918
+ recorded: {
919
+ id: string;
920
+ action: string;
921
+ source: string | null;
922
+ occurred_at: string;
923
+ } | null;
924
+ };
925
+ type SmsNumber = {
926
+ object: "sms_number";
927
+ /** Prefixed number id, e.g. `snum_…`. */
928
+ id: string;
929
+ /** E.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval. */
930
+ phone_number: string | null;
931
+ /** `long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender. */
932
+ type: "toll_free" | "ten_dlc" | "long_code" | "sender_id" | "simulator";
933
+ /** Only `active` numbers can send. */
934
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
935
+ /** Informational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag. */
936
+ is_default: boolean;
937
+ /** ISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded. */
938
+ country: string | null;
939
+ /** Whether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs 1¢. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator. */
940
+ two_way: boolean;
941
+ /** ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown. */
942
+ reach: Array<string>;
943
+ /** The brand this number is registered under. */
944
+ brand_id: string | null;
945
+ /** What carriers approved this number to send. Required for approval; submitted with the number. */
946
+ use_case: {
947
+ name: string;
948
+ category: string | null;
949
+ } | null;
950
+ /** Set when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`. */
951
+ action_required_reason: string | null;
952
+ /** Present on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set. */
953
+ sender_id_group: {
954
+ /** The Sender ID string recipients see. */
955
+ name: string;
956
+ /** The brand that owns this Sender ID. */
957
+ brand_id: string | null;
958
+ /** Every country this Sender ID is enabled for, with each country's own status. */
959
+ countries: Array<{
960
+ /** ISO-3166 alpha-2. */
961
+ country: string;
962
+ status: "pending" | "action_required" | "active" | "rejected" | "released";
963
+ }>;
964
+ } | null;
965
+ created_at: string;
966
+ };
967
+ type SmsPatch = {
968
+ /** Cancel a `queued` or `scheduled` text. Its reserved credit is refunded. */
969
+ cancel?: true;
970
+ /** Move a `scheduled` text to this future time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC. */
971
+ scheduled_at?: string;
972
+ };
973
+ type SmsSend = {
974
+ /** Recipient phone number in E.164 format, e.g. `+15551234567`. */
975
+ to: string;
976
+ /** Optional sender to send from: a number id from `GET /sms/numbers` (`snum_…`), or the E.164 number / Sender ID string itself (e.g. `+18005550100`, `Acme`). Must belong to your workspace, be active, and be able to reach the recipient's country. Otherwise it answers `404 not_found`, `403 sender_not_approved`, or `422 sender_cannot_reach`. Omit to route automatically: a transactional text to someone who texted one of your numbers in the last 30 days goes out from that number, so a reply stays in the same thread on their phone; otherwise Unitpost picks the active sender whose reach covers the recipient's country (10DLC before toll-free for US recipients; the matching Sender ID elsewhere), exactly as campaigns do. */
977
+ from?: string;
978
+ /** Message text. Billing is per segment (160 GSM-7 chars single-segment, 153 per segment concatenated; 70/67 for Unicode). */
979
+ body: string;
980
+ /** Defaults to `transactional`. Use `marketing` for anything promotional (offers, sales, newsletters): marketing sends require the recipient's prior express consent on record and honor recipient-local quiet hours. Sending promotional text as `transactional` skips both checks and breaks carrier rules. */
981
+ type?: "transactional" | "marketing";
982
+ /** Time to send at: ISO 8601 with `Z` or a `±hh:mm` offset (e.g. `2026-10-24T02:00:00Z` or `2026-10-24T09:00:00+07:00`), normalized to UTC. Omit to send immediately. A time in the past is not refused: the text goes out right away. */
983
+ scheduled_at?: string;
984
+ /** Create a contact for this recipient if one doesn't exist yet. Defaults to false. Sends don't modify your contact list. When the recipient is already a contact, the message is attached to them either way. A contact created this way records no consent, so it can't be used for marketing sends. */
985
+ create_contact?: boolean;
986
+ };
987
+ type SmsStats = {
988
+ object: "sms_stats";
989
+ /** The rolling window, in days. */
990
+ window_days: number;
991
+ /** Non-null when the requested window exceeded the plan's log retention and was clamped to this many days. */
992
+ clamped_to_retention_days: number | null;
993
+ totals: {
994
+ /** Queued, scheduled, or being handed to the carrier. */
995
+ queued: number;
996
+ /** Accepted by the carrier, no delivery receipt yet. */
997
+ sent: number;
998
+ /** The carrier confirmed delivery. */
999
+ delivered: number;
1000
+ /** Refused by the carrier or a compliance check after we tried. */
1001
+ failed: number;
1002
+ /** Skipped on purpose before sending (consent, opt-out, reach, quiet hours). Never billed. */
1003
+ suppressed: number;
1004
+ canceled: number;
1005
+ /** Texts received from recipients, including STOP/HELP keywords. */
1006
+ inbound: number;
1007
+ /** Segments billed for outbound texts that reached the carrier. */
1008
+ segments: number;
1009
+ };
1010
+ /** Percentages (one decimal). delivery and failure are vs sent + delivered + failed; suppression is vs those plus suppressed. */
1011
+ rates: {
1012
+ delivery: number;
1013
+ failure: number;
1014
+ suppression: number;
1015
+ };
1016
+ };
1017
+ type SmsTemplate = {
1018
+ object: "sms_template";
1019
+ id: string;
1020
+ name: string;
1021
+ body: string;
1022
+ status: "draft" | "published";
1023
+ created_at: string;
1024
+ updated_at: string;
1025
+ };
1026
+ type SmsTemplateCreate = {
1027
+ name: string;
1028
+ body?: string;
1029
+ };
1030
+ type SmsTemplateUpdate = {
1031
+ name?: string;
1032
+ body?: string;
1033
+ status?: "draft" | "published";
1034
+ };
611
1035
  type Suppression = {
612
1036
  object: "suppression";
613
1037
  id: string;
@@ -621,8 +1045,11 @@ type Suppression = {
621
1045
  };
622
1046
  type SuppressionBulkResult = {
623
1047
  object: "list";
1048
+ /** Addresses newly suppressed. */
624
1049
  added: number;
1050
+ /** Addresses already suppressed (no-op). */
625
1051
  skipped: number;
1052
+ /** Deduplicated input count. */
626
1053
  total: number;
627
1054
  };
628
1055
  type SuppressionCreate = {
@@ -636,1481 +1063,124 @@ type Template = {
636
1063
  id: string;
637
1064
  name: string;
638
1065
  subject: string | null;
639
- mode: "code" | "visual";
640
1066
  status: "draft" | "published";
641
- design?: unknown | null;
1067
+ /** Which editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body. */
1068
+ editor?: "simple" | "design" | "code";
1069
+ /** The coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`. */
1070
+ kind: "simple" | "designed";
1071
+ /** Inbox preview text: the snippet most inboxes show after the subject. Empty when unset. */
1072
+ preview_text?: string;
1073
+ html?: string | null;
1074
+ /** A `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows. */
1075
+ tsx?: string | null;
1076
+ /** Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user. */
1077
+ warnings?: Array<string>;
642
1078
  created_at: string;
643
1079
  updated_at: string;
644
1080
  };
1081
+ /** Create a template. The body is EXACTLY ONE of `tsx` (a Design email from our components — the default), `html` (a Code email: raw HTML) or `text` (a Simple, Gmail-style plain email). The spec can't express this exclusivity, so `required` lists only `name`; a request with none or several is rejected with 422. `theme` goes with `tsx` only. */
645
1082
  type TemplateCreate = {
646
1083
  name: string;
647
1084
  subject?: string;
648
- mode?: "code" | "visual";
649
- category?: "transactional" | "marketing";
650
- design?: {
651
- version?: 5;
652
- previewText?: string;
653
- category?: "transactional" | "marketing";
654
- openTracking?: boolean;
655
- clickTracking?: boolean;
656
- tracking?: boolean;
657
- from?: string;
658
- theme?: {
659
- fontFamily?: string;
660
- textColor?: string;
661
- backgroundColor?: string;
662
- bodyColor?: string;
663
- linkColor?: string;
664
- contentWidth?: number;
665
- bodyPadding?: number;
666
- bodyPaddingSides?: {
667
- top?: number;
668
- right?: number;
669
- bottom?: number;
670
- left?: number;
671
- };
672
- bodyRadius?: number;
673
- };
674
- variables?: Array<{
675
- name: string;
676
- type?: "string" | "number";
677
- source?: "input" | "contact";
678
- contactField?: string;
679
- style?: {
680
- bold?: boolean;
681
- italic?: boolean;
682
- underline?: boolean;
683
- color?: string;
684
- background?: string;
685
- fontFamily?: string;
686
- fontSize?: number;
687
- href?: string;
688
- };
689
- }>;
690
- className?: string;
691
- blocks?: Array<unknown | {
692
- type: "row";
693
- id: string;
694
- backgroundColor?: string;
695
- border?: {
696
- width?: number;
697
- style?: "solid" | "dashed" | "dotted";
698
- color?: string;
699
- radius?: number;
700
- };
701
- paddingX?: number;
702
- paddingY?: number;
703
- columnGap?: number;
704
- stackOnMobile?: boolean;
705
- margin?: {
706
- top?: number;
707
- right?: number;
708
- bottom?: number;
709
- left?: number;
710
- };
711
- padding?: {
712
- top?: number;
713
- right?: number;
714
- bottom?: number;
715
- left?: number;
716
- };
717
- customCss?: string;
718
- className?: string;
719
- componentRef?: {
720
- id: string;
721
- name?: string;
722
- unlocked?: boolean;
723
- };
724
- columns?: Array<{
725
- type: "column";
726
- id: string;
727
- width?: number;
728
- backgroundColor?: string;
729
- border?: {
730
- width?: number;
731
- style?: "solid" | "dashed" | "dotted";
732
- color?: string;
733
- radius?: number;
734
- };
735
- paddingX?: number;
736
- paddingY?: number;
737
- margin?: {
738
- top?: number;
739
- right?: number;
740
- bottom?: number;
741
- left?: number;
742
- };
743
- padding?: {
744
- top?: number;
745
- right?: number;
746
- bottom?: number;
747
- left?: number;
748
- };
749
- customCss?: string;
750
- className?: string;
751
- componentRef?: {
752
- id: string;
753
- name?: string;
754
- unlocked?: boolean;
755
- };
756
- children?: Array<{
757
- type: "text";
758
- id: string;
759
- text?: string;
760
- content?: Array<{
761
- text?: string;
762
- marks?: {
763
- bold?: boolean;
764
- italic?: boolean;
765
- underline?: boolean;
766
- link?: string;
767
- color?: string;
768
- background?: string;
769
- fontFamily?: string;
770
- fontSize?: number;
771
- };
772
- variable?: string;
773
- }>;
774
- align?: "left" | "center" | "right";
775
- color?: string;
776
- fontSize?: number;
777
- fontFamily?: string;
778
- lineHeight?: number | string;
779
- letterSpacing?: number;
780
- fontWeight?: string | number;
781
- marginBottom?: number;
782
- margin?: {
783
- top?: number;
784
- right?: number;
785
- bottom?: number;
786
- left?: number;
787
- };
788
- padding?: {
789
- top?: number;
790
- right?: number;
791
- bottom?: number;
792
- left?: number;
793
- };
794
- customCss?: string;
795
- className?: string;
796
- componentRef?: {
797
- id: string;
798
- name?: string;
799
- unlocked?: boolean;
800
- };
801
- } | {
802
- type: "heading";
803
- id: string;
804
- text?: string;
805
- content?: Array<{
806
- text?: string;
807
- marks?: {
808
- bold?: boolean;
809
- italic?: boolean;
810
- underline?: boolean;
811
- link?: string;
812
- color?: string;
813
- background?: string;
814
- fontFamily?: string;
815
- fontSize?: number;
816
- };
817
- variable?: string;
818
- }>;
819
- level?: 1 | 2 | 3 | 4;
820
- fontSize?: number;
821
- align?: "left" | "center" | "right";
822
- color?: string;
823
- fontFamily?: string;
824
- lineHeight?: number | string;
825
- letterSpacing?: number;
826
- fontWeight?: string | number;
827
- marginBottom?: number;
828
- margin?: {
829
- top?: number;
830
- right?: number;
831
- bottom?: number;
832
- left?: number;
833
- };
834
- padding?: {
835
- top?: number;
836
- right?: number;
837
- bottom?: number;
838
- left?: number;
839
- };
840
- customCss?: string;
841
- className?: string;
842
- componentRef?: {
843
- id: string;
844
- name?: string;
845
- unlocked?: boolean;
846
- };
847
- } | {
848
- type: "button";
849
- id: string;
850
- text?: string;
851
- href?: string;
852
- align?: "left" | "center" | "right";
853
- backgroundColor?: string;
854
- textColor?: string;
855
- borderRadius?: number;
856
- innerPaddingX?: number;
857
- innerPaddingY?: number;
858
- marginBottom?: number;
859
- margin?: {
860
- top?: number;
861
- right?: number;
862
- bottom?: number;
863
- left?: number;
864
- };
865
- padding?: {
866
- top?: number;
867
- right?: number;
868
- bottom?: number;
869
- left?: number;
870
- };
871
- customCss?: string;
872
- className?: string;
873
- componentRef?: {
874
- id: string;
875
- name?: string;
876
- unlocked?: boolean;
877
- };
878
- } | {
879
- type: "image";
880
- id: string;
881
- src?: string;
882
- alt?: string;
883
- href?: string;
884
- width?: number;
885
- height?: number;
886
- borderRadius?: number;
887
- border?: {
888
- width?: number;
889
- style?: "solid" | "dashed" | "dotted";
890
- color?: string;
891
- radius?: number;
892
- };
893
- objectFit?: "cover" | "contain" | "fill";
894
- backgroundColor?: string;
895
- align?: "left" | "center" | "right";
896
- marginBottom?: number;
897
- margin?: {
898
- top?: number;
899
- right?: number;
900
- bottom?: number;
901
- left?: number;
902
- };
903
- padding?: {
904
- top?: number;
905
- right?: number;
906
- bottom?: number;
907
- left?: number;
908
- };
909
- customCss?: string;
910
- className?: string;
911
- componentRef?: {
912
- id: string;
913
- name?: string;
914
- unlocked?: boolean;
915
- };
916
- } | {
917
- type: "divider";
918
- id: string;
919
- color?: string;
920
- marginBottom?: number;
921
- margin?: {
922
- top?: number;
923
- right?: number;
924
- bottom?: number;
925
- left?: number;
926
- };
927
- padding?: {
928
- top?: number;
929
- right?: number;
930
- bottom?: number;
931
- left?: number;
932
- };
933
- customCss?: string;
934
- className?: string;
935
- componentRef?: {
936
- id: string;
937
- name?: string;
938
- unlocked?: boolean;
939
- };
940
- } | {
941
- type: "link";
942
- id: string;
943
- text?: string;
944
- href?: string;
945
- align?: "left" | "center" | "right";
946
- color?: string;
947
- fontSize?: number;
948
- fontFamily?: string;
949
- underline?: boolean;
950
- marginBottom?: number;
951
- margin?: {
952
- top?: number;
953
- right?: number;
954
- bottom?: number;
955
- left?: number;
956
- };
957
- padding?: {
958
- top?: number;
959
- right?: number;
960
- bottom?: number;
961
- left?: number;
962
- };
963
- customCss?: string;
964
- className?: string;
965
- componentRef?: {
966
- id: string;
967
- name?: string;
968
- unlocked?: boolean;
969
- };
970
- } | {
971
- type: "spacer";
972
- id: string;
973
- height?: number;
974
- margin?: {
975
- top?: number;
976
- right?: number;
977
- bottom?: number;
978
- left?: number;
979
- };
980
- customCss?: string;
981
- className?: string;
982
- componentRef?: {
983
- id: string;
984
- name?: string;
985
- unlocked?: boolean;
986
- };
987
- } | {
988
- type: "markdown";
989
- id: string;
990
- markdown?: string;
991
- align?: "left" | "center" | "right";
992
- color?: string;
993
- fontSize?: number;
994
- marginBottom?: number;
995
- margin?: {
996
- top?: number;
997
- right?: number;
998
- bottom?: number;
999
- left?: number;
1000
- };
1001
- padding?: {
1002
- top?: number;
1003
- right?: number;
1004
- bottom?: number;
1005
- left?: number;
1006
- };
1007
- customCss?: string;
1008
- className?: string;
1009
- componentRef?: {
1010
- id: string;
1011
- name?: string;
1012
- unlocked?: boolean;
1013
- };
1014
- } | {
1015
- type: "code";
1016
- id: string;
1017
- code?: string;
1018
- backgroundColor?: string;
1019
- color?: string;
1020
- marginBottom?: number;
1021
- margin?: {
1022
- top?: number;
1023
- right?: number;
1024
- bottom?: number;
1025
- left?: number;
1026
- };
1027
- padding?: {
1028
- top?: number;
1029
- right?: number;
1030
- bottom?: number;
1031
- left?: number;
1032
- };
1033
- customCss?: string;
1034
- className?: string;
1035
- componentRef?: {
1036
- id: string;
1037
- name?: string;
1038
- unlocked?: boolean;
1039
- };
1040
- } | {
1041
- type: "html";
1042
- id: string;
1043
- html?: string;
1044
- marginBottom?: number;
1045
- margin?: {
1046
- top?: number;
1047
- right?: number;
1048
- bottom?: number;
1049
- left?: number;
1050
- };
1051
- padding?: {
1052
- top?: number;
1053
- right?: number;
1054
- bottom?: number;
1055
- left?: number;
1056
- };
1057
- customCss?: string;
1058
- className?: string;
1059
- componentRef?: {
1060
- id: string;
1061
- name?: string;
1062
- unlocked?: boolean;
1063
- };
1064
- }>;
1065
- }>;
1066
- } | {
1067
- type: "text";
1068
- id: string;
1069
- text?: string;
1070
- content?: Array<{
1071
- text?: string;
1072
- marks?: {
1073
- bold?: boolean;
1074
- italic?: boolean;
1075
- underline?: boolean;
1076
- link?: string;
1077
- color?: string;
1078
- background?: string;
1079
- fontFamily?: string;
1080
- fontSize?: number;
1081
- };
1082
- variable?: string;
1083
- }>;
1084
- align?: "left" | "center" | "right";
1085
- color?: string;
1086
- fontSize?: number;
1087
- fontFamily?: string;
1088
- lineHeight?: number | string;
1089
- letterSpacing?: number;
1090
- fontWeight?: string | number;
1091
- marginBottom?: number;
1092
- margin?: {
1093
- top?: number;
1094
- right?: number;
1095
- bottom?: number;
1096
- left?: number;
1097
- };
1098
- padding?: {
1099
- top?: number;
1100
- right?: number;
1101
- bottom?: number;
1102
- left?: number;
1103
- };
1104
- customCss?: string;
1105
- className?: string;
1106
- componentRef?: {
1107
- id: string;
1108
- name?: string;
1109
- unlocked?: boolean;
1110
- };
1111
- } | {
1112
- type: "heading";
1113
- id: string;
1114
- text?: string;
1115
- content?: Array<{
1116
- text?: string;
1117
- marks?: {
1118
- bold?: boolean;
1119
- italic?: boolean;
1120
- underline?: boolean;
1121
- link?: string;
1122
- color?: string;
1123
- background?: string;
1124
- fontFamily?: string;
1125
- fontSize?: number;
1126
- };
1127
- variable?: string;
1128
- }>;
1129
- level?: 1 | 2 | 3 | 4;
1130
- fontSize?: number;
1131
- align?: "left" | "center" | "right";
1132
- color?: string;
1133
- fontFamily?: string;
1134
- lineHeight?: number | string;
1135
- letterSpacing?: number;
1136
- fontWeight?: string | number;
1137
- marginBottom?: number;
1138
- margin?: {
1139
- top?: number;
1140
- right?: number;
1141
- bottom?: number;
1142
- left?: number;
1143
- };
1144
- padding?: {
1145
- top?: number;
1146
- right?: number;
1147
- bottom?: number;
1148
- left?: number;
1149
- };
1150
- customCss?: string;
1151
- className?: string;
1152
- componentRef?: {
1153
- id: string;
1154
- name?: string;
1155
- unlocked?: boolean;
1156
- };
1157
- } | {
1158
- type: "button";
1159
- id: string;
1160
- text?: string;
1161
- href?: string;
1162
- align?: "left" | "center" | "right";
1163
- backgroundColor?: string;
1164
- textColor?: string;
1165
- borderRadius?: number;
1166
- innerPaddingX?: number;
1167
- innerPaddingY?: number;
1168
- marginBottom?: number;
1169
- margin?: {
1170
- top?: number;
1171
- right?: number;
1172
- bottom?: number;
1173
- left?: number;
1174
- };
1175
- padding?: {
1176
- top?: number;
1177
- right?: number;
1178
- bottom?: number;
1179
- left?: number;
1180
- };
1181
- customCss?: string;
1182
- className?: string;
1183
- componentRef?: {
1184
- id: string;
1185
- name?: string;
1186
- unlocked?: boolean;
1187
- };
1188
- } | {
1189
- type: "image";
1190
- id: string;
1191
- src?: string;
1192
- alt?: string;
1193
- href?: string;
1085
+ /** A Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>; no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1086
+ tsx?: string;
1087
+ /** A Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1088
+ html?: string;
1089
+ /** A Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`. */
1090
+ text?: string;
1091
+ /** Page-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style). */
1092
+ theme?: {
1093
+ /** Page backdrop around the email card, e.g. `#f5f5f4`. */
1094
+ background_color?: string;
1095
+ /** The email card's background, e.g. `#ffffff`. */
1096
+ body_color?: string;
1097
+ /** Card width in px (default 600; 560–640 reads best). */
1098
+ content_width?: number;
1099
+ /** Padding inside the card in px. 0 lets full-width sections reach the edges. */
1100
+ body_padding?: number;
1101
+ /** Card corner radius in px. */
1102
+ body_radius?: number;
1103
+ /** A stroke around the card (corners follow `body_radius`); null removes it. */
1104
+ body_border?: {
1194
1105
  width?: number;
1195
- height?: number;
1196
- borderRadius?: number;
1197
- border?: {
1198
- width?: number;
1199
- style?: "solid" | "dashed" | "dotted";
1200
- color?: string;
1201
- radius?: number;
1202
- };
1203
- objectFit?: "cover" | "contain" | "fill";
1204
- backgroundColor?: string;
1205
- align?: "left" | "center" | "right";
1206
- marginBottom?: number;
1207
- margin?: {
1208
- top?: number;
1209
- right?: number;
1210
- bottom?: number;
1211
- left?: number;
1212
- };
1213
- padding?: {
1214
- top?: number;
1215
- right?: number;
1216
- bottom?: number;
1217
- left?: number;
1218
- };
1219
- customCss?: string;
1220
- className?: string;
1221
- componentRef?: {
1222
- id: string;
1223
- name?: string;
1224
- unlocked?: boolean;
1225
- };
1226
- } | {
1227
- type: "divider";
1228
- id: string;
1229
- color?: string;
1230
- marginBottom?: number;
1231
- margin?: {
1232
- top?: number;
1233
- right?: number;
1234
- bottom?: number;
1235
- left?: number;
1236
- };
1237
- padding?: {
1238
- top?: number;
1239
- right?: number;
1240
- bottom?: number;
1241
- left?: number;
1242
- };
1243
- customCss?: string;
1244
- className?: string;
1245
- componentRef?: {
1246
- id: string;
1247
- name?: string;
1248
- unlocked?: boolean;
1249
- };
1250
- } | {
1251
- type: "link";
1252
- id: string;
1253
- text?: string;
1254
- href?: string;
1255
- align?: "left" | "center" | "right";
1256
- color?: string;
1257
- fontSize?: number;
1258
- fontFamily?: string;
1259
- underline?: boolean;
1260
- marginBottom?: number;
1261
- margin?: {
1262
- top?: number;
1263
- right?: number;
1264
- bottom?: number;
1265
- left?: number;
1266
- };
1267
- padding?: {
1268
- top?: number;
1269
- right?: number;
1270
- bottom?: number;
1271
- left?: number;
1272
- };
1273
- customCss?: string;
1274
- className?: string;
1275
- componentRef?: {
1276
- id: string;
1277
- name?: string;
1278
- unlocked?: boolean;
1279
- };
1280
- } | {
1281
- type: "spacer";
1282
- id: string;
1283
- height?: number;
1284
- margin?: {
1285
- top?: number;
1286
- right?: number;
1287
- bottom?: number;
1288
- left?: number;
1289
- };
1290
- customCss?: string;
1291
- className?: string;
1292
- componentRef?: {
1293
- id: string;
1294
- name?: string;
1295
- unlocked?: boolean;
1296
- };
1297
- } | {
1298
- type: "markdown";
1299
- id: string;
1300
- markdown?: string;
1301
- align?: "left" | "center" | "right";
1106
+ style?: "solid" | "dashed" | "dotted";
1302
1107
  color?: string;
1303
- fontSize?: number;
1304
- marginBottom?: number;
1305
- margin?: {
1306
- top?: number;
1307
- right?: number;
1308
- bottom?: number;
1309
- left?: number;
1310
- };
1311
- padding?: {
1312
- top?: number;
1313
- right?: number;
1314
- bottom?: number;
1315
- left?: number;
1316
- };
1317
- customCss?: string;
1318
- className?: string;
1319
- componentRef?: {
1320
- id: string;
1321
- name?: string;
1322
- unlocked?: boolean;
1323
- };
1324
- } | {
1325
- type: "code";
1326
- id: string;
1327
- code?: string;
1328
- backgroundColor?: string;
1329
- color?: string;
1330
- marginBottom?: number;
1331
- margin?: {
1332
- top?: number;
1333
- right?: number;
1334
- bottom?: number;
1335
- left?: number;
1336
- };
1337
- padding?: {
1338
- top?: number;
1339
- right?: number;
1340
- bottom?: number;
1341
- left?: number;
1342
- };
1343
- customCss?: string;
1344
- className?: string;
1345
- componentRef?: {
1346
- id: string;
1347
- name?: string;
1348
- unlocked?: boolean;
1349
- };
1350
- } | {
1351
- type: "html";
1352
- id: string;
1353
- html?: string;
1354
- marginBottom?: number;
1355
- margin?: {
1356
- top?: number;
1357
- right?: number;
1358
- bottom?: number;
1359
- left?: number;
1360
- };
1361
- padding?: {
1362
- top?: number;
1363
- right?: number;
1364
- bottom?: number;
1365
- left?: number;
1366
- };
1367
- customCss?: string;
1368
- className?: string;
1369
- componentRef?: {
1370
- id: string;
1371
- name?: string;
1372
- unlocked?: boolean;
1373
- };
1374
- }>;
1108
+ } | null;
1109
+ /** Default font stack, e.g. `Inter, -apple-system, 'Segoe UI', Arial, sans-serif`. */
1110
+ font_family?: string;
1111
+ /** Default text color. */
1112
+ text_color?: string;
1113
+ /** Inline link color. */
1114
+ link_color?: string;
1375
1115
  };
1116
+ /** Inbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>. */
1117
+ preview_text?: string;
1118
+ category?: "transactional" | "marketing";
1119
+ };
1120
+ type TemplateTestSend = {
1121
+ to: string;
1122
+ subject?: string;
1123
+ variables?: Record<string, string>;
1124
+ };
1125
+ type TemplateTestSendResult = {
1126
+ object: "template_test_send";
1127
+ /** The test email (`email_…`); retrieve it like any email. */
1128
+ email_id: string;
1129
+ /** The test email's status, usually `queued`. */
1130
+ status: string;
1131
+ /** False when this environment records sends without delivering them. */
1132
+ dispatched: boolean;
1133
+ /** Variables with no sample value, sent as a literal `{{name}}`. */
1134
+ unresolved_variables: Array<string>;
1376
1135
  };
1136
+ /** Update a template's metadata and/or body. Replace the body with ONE of `tsx` (Design), `html` (Code) or `text` (Simple) — 422 for several. Match the template's current `editor` (design → `tsx`, code → `html`, simple → `text`); another body field switches it, so only do that when the user asked. `editor` alone converts the current body. `theme` restyles a Design template (with or without `tsx`). A whole read sent back is fine: `html`, `tsx` (incl. its `null`) and `editor` that repeat the current read are ignored, so the field you changed is the edit. */
1377
1137
  type TemplateUpdate = {
1378
1138
  name?: string;
1379
1139
  subject?: string | null;
1380
- mode?: "code" | "visual";
1381
1140
  status?: "draft" | "published";
1382
- design?: {
1383
- version?: 5;
1384
- previewText?: string;
1385
- category?: "transactional" | "marketing";
1386
- openTracking?: boolean;
1387
- clickTracking?: boolean;
1388
- tracking?: boolean;
1389
- from?: string;
1390
- theme?: {
1391
- fontFamily?: string;
1392
- textColor?: string;
1393
- backgroundColor?: string;
1394
- bodyColor?: string;
1395
- linkColor?: string;
1396
- contentWidth?: number;
1397
- bodyPadding?: number;
1398
- bodyPaddingSides?: {
1399
- top?: number;
1400
- right?: number;
1401
- bottom?: number;
1402
- left?: number;
1403
- };
1404
- bodyRadius?: number;
1405
- };
1406
- variables?: Array<{
1407
- name: string;
1408
- type?: "string" | "number";
1409
- source?: "input" | "contact";
1410
- contactField?: string;
1411
- style?: {
1412
- bold?: boolean;
1413
- italic?: boolean;
1414
- underline?: boolean;
1415
- color?: string;
1416
- background?: string;
1417
- fontFamily?: string;
1418
- fontSize?: number;
1419
- href?: string;
1420
- };
1421
- }>;
1422
- className?: string;
1423
- blocks?: Array<unknown | {
1424
- type: "row";
1425
- id: string;
1426
- backgroundColor?: string;
1427
- border?: {
1428
- width?: number;
1429
- style?: "solid" | "dashed" | "dotted";
1430
- color?: string;
1431
- radius?: number;
1432
- };
1433
- paddingX?: number;
1434
- paddingY?: number;
1435
- columnGap?: number;
1436
- stackOnMobile?: boolean;
1437
- margin?: {
1438
- top?: number;
1439
- right?: number;
1440
- bottom?: number;
1441
- left?: number;
1442
- };
1443
- padding?: {
1444
- top?: number;
1445
- right?: number;
1446
- bottom?: number;
1447
- left?: number;
1448
- };
1449
- customCss?: string;
1450
- className?: string;
1451
- componentRef?: {
1452
- id: string;
1453
- name?: string;
1454
- unlocked?: boolean;
1455
- };
1456
- columns?: Array<{
1457
- type: "column";
1458
- id: string;
1459
- width?: number;
1460
- backgroundColor?: string;
1461
- border?: {
1462
- width?: number;
1463
- style?: "solid" | "dashed" | "dotted";
1464
- color?: string;
1465
- radius?: number;
1466
- };
1467
- paddingX?: number;
1468
- paddingY?: number;
1469
- margin?: {
1470
- top?: number;
1471
- right?: number;
1472
- bottom?: number;
1473
- left?: number;
1474
- };
1475
- padding?: {
1476
- top?: number;
1477
- right?: number;
1478
- bottom?: number;
1479
- left?: number;
1480
- };
1481
- customCss?: string;
1482
- className?: string;
1483
- componentRef?: {
1484
- id: string;
1485
- name?: string;
1486
- unlocked?: boolean;
1487
- };
1488
- children?: Array<{
1489
- type: "text";
1490
- id: string;
1491
- text?: string;
1492
- content?: Array<{
1493
- text?: string;
1494
- marks?: {
1495
- bold?: boolean;
1496
- italic?: boolean;
1497
- underline?: boolean;
1498
- link?: string;
1499
- color?: string;
1500
- background?: string;
1501
- fontFamily?: string;
1502
- fontSize?: number;
1503
- };
1504
- variable?: string;
1505
- }>;
1506
- align?: "left" | "center" | "right";
1507
- color?: string;
1508
- fontSize?: number;
1509
- fontFamily?: string;
1510
- lineHeight?: number | string;
1511
- letterSpacing?: number;
1512
- fontWeight?: string | number;
1513
- marginBottom?: number;
1514
- margin?: {
1515
- top?: number;
1516
- right?: number;
1517
- bottom?: number;
1518
- left?: number;
1519
- };
1520
- padding?: {
1521
- top?: number;
1522
- right?: number;
1523
- bottom?: number;
1524
- left?: number;
1525
- };
1526
- customCss?: string;
1527
- className?: string;
1528
- componentRef?: {
1529
- id: string;
1530
- name?: string;
1531
- unlocked?: boolean;
1532
- };
1533
- } | {
1534
- type: "heading";
1535
- id: string;
1536
- text?: string;
1537
- content?: Array<{
1538
- text?: string;
1539
- marks?: {
1540
- bold?: boolean;
1541
- italic?: boolean;
1542
- underline?: boolean;
1543
- link?: string;
1544
- color?: string;
1545
- background?: string;
1546
- fontFamily?: string;
1547
- fontSize?: number;
1548
- };
1549
- variable?: string;
1550
- }>;
1551
- level?: 1 | 2 | 3 | 4;
1552
- fontSize?: number;
1553
- align?: "left" | "center" | "right";
1554
- color?: string;
1555
- fontFamily?: string;
1556
- lineHeight?: number | string;
1557
- letterSpacing?: number;
1558
- fontWeight?: string | number;
1559
- marginBottom?: number;
1560
- margin?: {
1561
- top?: number;
1562
- right?: number;
1563
- bottom?: number;
1564
- left?: number;
1565
- };
1566
- padding?: {
1567
- top?: number;
1568
- right?: number;
1569
- bottom?: number;
1570
- left?: number;
1571
- };
1572
- customCss?: string;
1573
- className?: string;
1574
- componentRef?: {
1575
- id: string;
1576
- name?: string;
1577
- unlocked?: boolean;
1578
- };
1579
- } | {
1580
- type: "button";
1581
- id: string;
1582
- text?: string;
1583
- href?: string;
1584
- align?: "left" | "center" | "right";
1585
- backgroundColor?: string;
1586
- textColor?: string;
1587
- borderRadius?: number;
1588
- innerPaddingX?: number;
1589
- innerPaddingY?: number;
1590
- marginBottom?: number;
1591
- margin?: {
1592
- top?: number;
1593
- right?: number;
1594
- bottom?: number;
1595
- left?: number;
1596
- };
1597
- padding?: {
1598
- top?: number;
1599
- right?: number;
1600
- bottom?: number;
1601
- left?: number;
1602
- };
1603
- customCss?: string;
1604
- className?: string;
1605
- componentRef?: {
1606
- id: string;
1607
- name?: string;
1608
- unlocked?: boolean;
1609
- };
1610
- } | {
1611
- type: "image";
1612
- id: string;
1613
- src?: string;
1614
- alt?: string;
1615
- href?: string;
1616
- width?: number;
1617
- height?: number;
1618
- borderRadius?: number;
1619
- border?: {
1620
- width?: number;
1621
- style?: "solid" | "dashed" | "dotted";
1622
- color?: string;
1623
- radius?: number;
1624
- };
1625
- objectFit?: "cover" | "contain" | "fill";
1626
- backgroundColor?: string;
1627
- align?: "left" | "center" | "right";
1628
- marginBottom?: number;
1629
- margin?: {
1630
- top?: number;
1631
- right?: number;
1632
- bottom?: number;
1633
- left?: number;
1634
- };
1635
- padding?: {
1636
- top?: number;
1637
- right?: number;
1638
- bottom?: number;
1639
- left?: number;
1640
- };
1641
- customCss?: string;
1642
- className?: string;
1643
- componentRef?: {
1644
- id: string;
1645
- name?: string;
1646
- unlocked?: boolean;
1647
- };
1648
- } | {
1649
- type: "divider";
1650
- id: string;
1651
- color?: string;
1652
- marginBottom?: number;
1653
- margin?: {
1654
- top?: number;
1655
- right?: number;
1656
- bottom?: number;
1657
- left?: number;
1658
- };
1659
- padding?: {
1660
- top?: number;
1661
- right?: number;
1662
- bottom?: number;
1663
- left?: number;
1664
- };
1665
- customCss?: string;
1666
- className?: string;
1667
- componentRef?: {
1668
- id: string;
1669
- name?: string;
1670
- unlocked?: boolean;
1671
- };
1672
- } | {
1673
- type: "link";
1674
- id: string;
1675
- text?: string;
1676
- href?: string;
1677
- align?: "left" | "center" | "right";
1678
- color?: string;
1679
- fontSize?: number;
1680
- fontFamily?: string;
1681
- underline?: boolean;
1682
- marginBottom?: number;
1683
- margin?: {
1684
- top?: number;
1685
- right?: number;
1686
- bottom?: number;
1687
- left?: number;
1688
- };
1689
- padding?: {
1690
- top?: number;
1691
- right?: number;
1692
- bottom?: number;
1693
- left?: number;
1694
- };
1695
- customCss?: string;
1696
- className?: string;
1697
- componentRef?: {
1698
- id: string;
1699
- name?: string;
1700
- unlocked?: boolean;
1701
- };
1702
- } | {
1703
- type: "spacer";
1704
- id: string;
1705
- height?: number;
1706
- margin?: {
1707
- top?: number;
1708
- right?: number;
1709
- bottom?: number;
1710
- left?: number;
1711
- };
1712
- customCss?: string;
1713
- className?: string;
1714
- componentRef?: {
1715
- id: string;
1716
- name?: string;
1717
- unlocked?: boolean;
1718
- };
1719
- } | {
1720
- type: "markdown";
1721
- id: string;
1722
- markdown?: string;
1723
- align?: "left" | "center" | "right";
1724
- color?: string;
1725
- fontSize?: number;
1726
- marginBottom?: number;
1727
- margin?: {
1728
- top?: number;
1729
- right?: number;
1730
- bottom?: number;
1731
- left?: number;
1732
- };
1733
- padding?: {
1734
- top?: number;
1735
- right?: number;
1736
- bottom?: number;
1737
- left?: number;
1738
- };
1739
- customCss?: string;
1740
- className?: string;
1741
- componentRef?: {
1742
- id: string;
1743
- name?: string;
1744
- unlocked?: boolean;
1745
- };
1746
- } | {
1747
- type: "code";
1748
- id: string;
1749
- code?: string;
1750
- backgroundColor?: string;
1751
- color?: string;
1752
- marginBottom?: number;
1753
- margin?: {
1754
- top?: number;
1755
- right?: number;
1756
- bottom?: number;
1757
- left?: number;
1758
- };
1759
- padding?: {
1760
- top?: number;
1761
- right?: number;
1762
- bottom?: number;
1763
- left?: number;
1764
- };
1765
- customCss?: string;
1766
- className?: string;
1767
- componentRef?: {
1768
- id: string;
1769
- name?: string;
1770
- unlocked?: boolean;
1771
- };
1772
- } | {
1773
- type: "html";
1774
- id: string;
1775
- html?: string;
1776
- marginBottom?: number;
1777
- margin?: {
1778
- top?: number;
1779
- right?: number;
1780
- bottom?: number;
1781
- left?: number;
1782
- };
1783
- padding?: {
1784
- top?: number;
1785
- right?: number;
1786
- bottom?: number;
1787
- left?: number;
1788
- };
1789
- customCss?: string;
1790
- className?: string;
1791
- componentRef?: {
1792
- id: string;
1793
- name?: string;
1794
- unlocked?: boolean;
1795
- };
1796
- }>;
1797
- }>;
1798
- } | {
1799
- type: "text";
1800
- id: string;
1801
- text?: string;
1802
- content?: Array<{
1803
- text?: string;
1804
- marks?: {
1805
- bold?: boolean;
1806
- italic?: boolean;
1807
- underline?: boolean;
1808
- link?: string;
1809
- color?: string;
1810
- background?: string;
1811
- fontFamily?: string;
1812
- fontSize?: number;
1813
- };
1814
- variable?: string;
1815
- }>;
1816
- align?: "left" | "center" | "right";
1817
- color?: string;
1818
- fontSize?: number;
1819
- fontFamily?: string;
1820
- lineHeight?: number | string;
1821
- letterSpacing?: number;
1822
- fontWeight?: string | number;
1823
- marginBottom?: number;
1824
- margin?: {
1825
- top?: number;
1826
- right?: number;
1827
- bottom?: number;
1828
- left?: number;
1829
- };
1830
- padding?: {
1831
- top?: number;
1832
- right?: number;
1833
- bottom?: number;
1834
- left?: number;
1835
- };
1836
- customCss?: string;
1837
- className?: string;
1838
- componentRef?: {
1839
- id: string;
1840
- name?: string;
1841
- unlocked?: boolean;
1842
- };
1843
- } | {
1844
- type: "heading";
1845
- id: string;
1846
- text?: string;
1847
- content?: Array<{
1848
- text?: string;
1849
- marks?: {
1850
- bold?: boolean;
1851
- italic?: boolean;
1852
- underline?: boolean;
1853
- link?: string;
1854
- color?: string;
1855
- background?: string;
1856
- fontFamily?: string;
1857
- fontSize?: number;
1858
- };
1859
- variable?: string;
1860
- }>;
1861
- level?: 1 | 2 | 3 | 4;
1862
- fontSize?: number;
1863
- align?: "left" | "center" | "right";
1864
- color?: string;
1865
- fontFamily?: string;
1866
- lineHeight?: number | string;
1867
- letterSpacing?: number;
1868
- fontWeight?: string | number;
1869
- marginBottom?: number;
1870
- margin?: {
1871
- top?: number;
1872
- right?: number;
1873
- bottom?: number;
1874
- left?: number;
1875
- };
1876
- padding?: {
1877
- top?: number;
1878
- right?: number;
1879
- bottom?: number;
1880
- left?: number;
1881
- };
1882
- customCss?: string;
1883
- className?: string;
1884
- componentRef?: {
1885
- id: string;
1886
- name?: string;
1887
- unlocked?: boolean;
1888
- };
1889
- } | {
1890
- type: "button";
1891
- id: string;
1892
- text?: string;
1893
- href?: string;
1894
- align?: "left" | "center" | "right";
1895
- backgroundColor?: string;
1896
- textColor?: string;
1897
- borderRadius?: number;
1898
- innerPaddingX?: number;
1899
- innerPaddingY?: number;
1900
- marginBottom?: number;
1901
- margin?: {
1902
- top?: number;
1903
- right?: number;
1904
- bottom?: number;
1905
- left?: number;
1906
- };
1907
- padding?: {
1908
- top?: number;
1909
- right?: number;
1910
- bottom?: number;
1911
- left?: number;
1912
- };
1913
- customCss?: string;
1914
- className?: string;
1915
- componentRef?: {
1916
- id: string;
1917
- name?: string;
1918
- unlocked?: boolean;
1919
- };
1920
- } | {
1921
- type: "image";
1922
- id: string;
1923
- src?: string;
1924
- alt?: string;
1925
- href?: string;
1141
+ /** A Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>; no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1142
+ tsx?: string;
1143
+ /** A Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`. */
1144
+ html?: string;
1145
+ /** A Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`. */
1146
+ text?: string;
1147
+ /** Page-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style). */
1148
+ theme?: {
1149
+ /** Page backdrop around the email card, e.g. `#f5f5f4`. */
1150
+ background_color?: string;
1151
+ /** The email card's background, e.g. `#ffffff`. */
1152
+ body_color?: string;
1153
+ /** Card width in px (default 600; 560–640 reads best). */
1154
+ content_width?: number;
1155
+ /** Padding inside the card in px. 0 lets full-width sections reach the edges. */
1156
+ body_padding?: number;
1157
+ /** Card corner radius in px. */
1158
+ body_radius?: number;
1159
+ /** A stroke around the card (corners follow `body_radius`); null removes it. */
1160
+ body_border?: {
1926
1161
  width?: number;
1927
- height?: number;
1928
- borderRadius?: number;
1929
- border?: {
1930
- width?: number;
1931
- style?: "solid" | "dashed" | "dotted";
1932
- color?: string;
1933
- radius?: number;
1934
- };
1935
- objectFit?: "cover" | "contain" | "fill";
1936
- backgroundColor?: string;
1937
- align?: "left" | "center" | "right";
1938
- marginBottom?: number;
1939
- margin?: {
1940
- top?: number;
1941
- right?: number;
1942
- bottom?: number;
1943
- left?: number;
1944
- };
1945
- padding?: {
1946
- top?: number;
1947
- right?: number;
1948
- bottom?: number;
1949
- left?: number;
1950
- };
1951
- customCss?: string;
1952
- className?: string;
1953
- componentRef?: {
1954
- id: string;
1955
- name?: string;
1956
- unlocked?: boolean;
1957
- };
1958
- } | {
1959
- type: "divider";
1960
- id: string;
1961
- color?: string;
1962
- marginBottom?: number;
1963
- margin?: {
1964
- top?: number;
1965
- right?: number;
1966
- bottom?: number;
1967
- left?: number;
1968
- };
1969
- padding?: {
1970
- top?: number;
1971
- right?: number;
1972
- bottom?: number;
1973
- left?: number;
1974
- };
1975
- customCss?: string;
1976
- className?: string;
1977
- componentRef?: {
1978
- id: string;
1979
- name?: string;
1980
- unlocked?: boolean;
1981
- };
1982
- } | {
1983
- type: "link";
1984
- id: string;
1985
- text?: string;
1986
- href?: string;
1987
- align?: "left" | "center" | "right";
1162
+ style?: "solid" | "dashed" | "dotted";
1988
1163
  color?: string;
1989
- fontSize?: number;
1990
- fontFamily?: string;
1991
- underline?: boolean;
1992
- marginBottom?: number;
1993
- margin?: {
1994
- top?: number;
1995
- right?: number;
1996
- bottom?: number;
1997
- left?: number;
1998
- };
1999
- padding?: {
2000
- top?: number;
2001
- right?: number;
2002
- bottom?: number;
2003
- left?: number;
2004
- };
2005
- customCss?: string;
2006
- className?: string;
2007
- componentRef?: {
2008
- id: string;
2009
- name?: string;
2010
- unlocked?: boolean;
2011
- };
2012
- } | {
2013
- type: "spacer";
2014
- id: string;
2015
- height?: number;
2016
- margin?: {
2017
- top?: number;
2018
- right?: number;
2019
- bottom?: number;
2020
- left?: number;
2021
- };
2022
- customCss?: string;
2023
- className?: string;
2024
- componentRef?: {
2025
- id: string;
2026
- name?: string;
2027
- unlocked?: boolean;
2028
- };
2029
- } | {
2030
- type: "markdown";
2031
- id: string;
2032
- markdown?: string;
2033
- align?: "left" | "center" | "right";
2034
- color?: string;
2035
- fontSize?: number;
2036
- marginBottom?: number;
2037
- margin?: {
2038
- top?: number;
2039
- right?: number;
2040
- bottom?: number;
2041
- left?: number;
2042
- };
2043
- padding?: {
2044
- top?: number;
2045
- right?: number;
2046
- bottom?: number;
2047
- left?: number;
2048
- };
2049
- customCss?: string;
2050
- className?: string;
2051
- componentRef?: {
2052
- id: string;
2053
- name?: string;
2054
- unlocked?: boolean;
2055
- };
2056
- } | {
2057
- type: "code";
2058
- id: string;
2059
- code?: string;
2060
- backgroundColor?: string;
2061
- color?: string;
2062
- marginBottom?: number;
2063
- margin?: {
2064
- top?: number;
2065
- right?: number;
2066
- bottom?: number;
2067
- left?: number;
2068
- };
2069
- padding?: {
2070
- top?: number;
2071
- right?: number;
2072
- bottom?: number;
2073
- left?: number;
2074
- };
2075
- customCss?: string;
2076
- className?: string;
2077
- componentRef?: {
2078
- id: string;
2079
- name?: string;
2080
- unlocked?: boolean;
2081
- };
2082
- } | {
2083
- type: "html";
2084
- id: string;
2085
- html?: string;
2086
- marginBottom?: number;
2087
- margin?: {
2088
- top?: number;
2089
- right?: number;
2090
- bottom?: number;
2091
- left?: number;
2092
- };
2093
- padding?: {
2094
- top?: number;
2095
- right?: number;
2096
- bottom?: number;
2097
- left?: number;
2098
- };
2099
- customCss?: string;
2100
- className?: string;
2101
- componentRef?: {
2102
- id: string;
2103
- name?: string;
2104
- unlocked?: boolean;
2105
- };
2106
- }>;
1164
+ } | null;
1165
+ /** Default font stack, e.g. `Inter, -apple-system, 'Segoe UI', Arial, sans-serif`. */
1166
+ font_family?: string;
1167
+ /** Default text color. */
1168
+ text_color?: string;
1169
+ /** Inline link color. */
1170
+ link_color?: string;
2107
1171
  };
1172
+ /** Inbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>. */
1173
+ preview_text?: string;
1174
+ /** Convert the template to this editor. Alone (no body field) it converts the CURRENT body: simple → design keeps every line; design → code renders it to HTML (looks the same, no longer editable block by block); code → design rebuilds components where the HTML maps and keeps the rest as HTML; design or code → simple flattens to plain lines. What a conversion changes comes back in `warnings`. With a body field it must name that field's editor (`tsx` = design, `html` = code, `text` = simple). Only when the user asked to switch. */
1175
+ editor?: "simple" | "design" | "code";
2108
1176
  };
2109
1177
  type Topic = {
2110
1178
  object: "topic";
2111
1179
  id: string;
2112
1180
  name: string;
2113
1181
  description: string | null;
1182
+ /** Which channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`. */
1183
+ channel: "email" | "sms";
2114
1184
  default_opt_in: boolean;
2115
1185
  created_at: string;
2116
1186
  updated_at: string;
@@ -2145,35 +1215,97 @@ type Usage$1 = {
2145
1215
  overage_cap_cents: number | null;
2146
1216
  email_rate_per_1k_cents: number | null;
2147
1217
  } | null;
1218
+ spend: {
1219
+ total_cents: number;
1220
+ email_cents: number;
1221
+ sms_cents: number;
1222
+ sms_carrier_fees_cents: number;
1223
+ other_cents: number;
1224
+ refunds_cents: number;
1225
+ included_cents: number;
1226
+ purchased_credit_cents: number;
1227
+ overage_cents: number;
1228
+ credits_added_cents: number;
1229
+ };
1230
+ sms: {
1231
+ messages: number;
1232
+ segments: number;
1233
+ send_cents: number;
1234
+ received: number;
1235
+ received_cents: number;
1236
+ monthly_fees_cents: number;
1237
+ one_time_fees_cents: number;
1238
+ refunds_cents: number;
1239
+ countries: Array<{
1240
+ country: string;
1241
+ messages: number;
1242
+ segments: number;
1243
+ price_per_segment_cents: number | null;
1244
+ cost_cents: number;
1245
+ }>;
1246
+ };
2148
1247
  };
2149
1248
  type Webhook = {
2150
1249
  object: "webhook";
2151
1250
  id: string;
2152
1251
  name: string;
2153
1252
  url: string;
2154
- events: Array<string>;
1253
+ events: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
2155
1254
  status: "enabled" | "disabled" | "suspended";
2156
1255
  created_at: string;
2157
1256
  updated_at: string;
2158
1257
  };
2159
1258
  type WebhookCreate = {
2160
1259
  url: string;
2161
- events: Array<string>;
1260
+ events: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
2162
1261
  name?: string;
2163
1262
  };
2164
1263
  type WebhookCreated = Webhook & {
1264
+ /** The HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint. */
2165
1265
  signing_secret: string;
2166
1266
  };
1267
+ type WebhookDelivery = {
1268
+ object: "webhook_delivery";
1269
+ /** The delivery id (`msg_…`). */
1270
+ id: string;
1271
+ /** The `svix-id` header this delivery's requests carried; retries reuse it, so dedupe on it. */
1272
+ svix_id: string;
1273
+ webhook_id: string;
1274
+ /** The event (`evt_…`). The delivered payload's `event_id` is the same id without the `evt_` prefix. */
1275
+ event_id: string;
1276
+ event_type: string;
1277
+ /** `queued`: held while the endpoint is disabled. `retrying`: an attempt failed and another is scheduled at `next_attempt_at`. `exhausted`: every retry failed. */
1278
+ status: "pending" | "queued" | "retrying" | "succeeded" | "failed" | "exhausted";
1279
+ /** Attempts made so far. */
1280
+ attempt: number;
1281
+ /** Your endpoint's last HTTP status, or null before an attempt or on a network error. */
1282
+ response_status: number | null;
1283
+ error: string | null;
1284
+ scheduled_at: string;
1285
+ next_attempt_at: string | null;
1286
+ delivered_at: string | null;
1287
+ event_created_at: string;
1288
+ /** The event's `data`, as delivered. */
1289
+ data: Record<string, unknown>;
1290
+ };
1291
+ type WebhookSecretRotated = WebhookCreated & {
1292
+ /** Until this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then. */
1293
+ previous_secret_expires_at: string;
1294
+ };
2167
1295
  type WebhookTestResult = {
2168
1296
  object: "webhook_test";
1297
+ /** Whether the endpoint accepted the probe (2xx). */
2169
1298
  delivered: boolean;
1299
+ /** The HTTP status the endpoint returned, or null on a transport error. */
2170
1300
  response_status: number | null;
1301
+ /** The sample event type that was sent. */
2171
1302
  event_type: string;
1303
+ /** A transport/error message when delivery failed, else null. */
2172
1304
  error: string | null;
2173
1305
  };
2174
1306
  type WebhookUpdate = {
2175
1307
  url?: string;
2176
- events?: Array<string>;
1308
+ events?: Array<"email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.scheduled" | "email.suppressed" | "email.received" | "email.*" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.scheduled" | "sms.suppressed" | "sms.received" | "sms.*" | "domain.created" | "domain.updated" | "domain.deleted" | "domain.*" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.*" | "segment.joined" | "segment.left" | "segment.*" | "topic.subscribed" | "topic.unsubscribed" | "topic.*" | "campaign.paused" | "campaign.resumed" | "campaign.*" | "sms_campaign.paused" | "sms_campaign.resumed" | "sms_campaign.*" | (string & {})>;
2177
1309
  name?: string;
2178
1310
  status?: "enabled" | "disabled";
2179
1311
  };
@@ -2189,6 +1321,7 @@ type models_BrandKitList = BrandKitList;
2189
1321
  type models_Campaign = Campaign;
2190
1322
  type models_CampaignCreate = CampaignCreate;
2191
1323
  type models_CampaignReschedule = CampaignReschedule;
1324
+ type models_CampaignSend = CampaignSend;
2192
1325
  type models_CampaignUpdate = CampaignUpdate;
2193
1326
  type models_Contact = Contact;
2194
1327
  type models_ContactCreate = ContactCreate;
@@ -2203,9 +1336,11 @@ type models_ContactTopicSet = ContactTopicSet;
2203
1336
  type models_ContactUpdate = ContactUpdate;
2204
1337
  type models_Domain = Domain;
2205
1338
  type models_DomainCreate = DomainCreate;
1339
+ type models_DomainDiagnosis = DomainDiagnosis;
2206
1340
  type models_DomainUpdate = DomainUpdate;
2207
1341
  type models_EmailPatch = EmailPatch;
2208
1342
  type models_EmailStats = EmailStats;
1343
+ type models_Job = Job;
2209
1344
  type models_ReceivedAttachmentUrl = ReceivedAttachmentUrl;
2210
1345
  type models_ReceivedEmail = ReceivedEmail;
2211
1346
  type models_ReceivedEmailSummary = ReceivedEmailSummary;
@@ -2216,11 +1351,30 @@ type models_SegmentMemberAdd = SegmentMemberAdd;
2216
1351
  type models_SegmentUpdate = SegmentUpdate;
2217
1352
  type models_SendEmail = SendEmail;
2218
1353
  type models_SendResult = SendResult;
1354
+ type models_SmsBrand = SmsBrand;
1355
+ type models_SmsCampaign = SmsCampaign;
1356
+ type models_SmsCampaignCreate = SmsCampaignCreate;
1357
+ type models_SmsCampaignReschedule = SmsCampaignReschedule;
1358
+ type models_SmsCampaignSend = SmsCampaignSend;
1359
+ type models_SmsCampaignUpdate = SmsCampaignUpdate;
1360
+ type models_SmsCampaignValidation = SmsCampaignValidation;
1361
+ type models_SmsConsent = SmsConsent;
1362
+ type models_SmsConsentRecord = SmsConsentRecord;
1363
+ type models_SmsConsentRecorded = SmsConsentRecorded;
1364
+ type models_SmsNumber = SmsNumber;
1365
+ type models_SmsPatch = SmsPatch;
1366
+ type models_SmsSend = SmsSend;
1367
+ type models_SmsStats = SmsStats;
1368
+ type models_SmsTemplate = SmsTemplate;
1369
+ type models_SmsTemplateCreate = SmsTemplateCreate;
1370
+ type models_SmsTemplateUpdate = SmsTemplateUpdate;
2219
1371
  type models_Suppression = Suppression;
2220
1372
  type models_SuppressionBulkResult = SuppressionBulkResult;
2221
1373
  type models_SuppressionCreate = SuppressionCreate;
2222
1374
  type models_Template = Template;
2223
1375
  type models_TemplateCreate = TemplateCreate;
1376
+ type models_TemplateTestSend = TemplateTestSend;
1377
+ type models_TemplateTestSendResult = TemplateTestSendResult;
2224
1378
  type models_TemplateUpdate = TemplateUpdate;
2225
1379
  type models_Topic = Topic;
2226
1380
  type models_TopicCreate = TopicCreate;
@@ -2228,12 +1382,27 @@ type models_TopicUpdate = TopicUpdate;
2228
1382
  type models_Webhook = Webhook;
2229
1383
  type models_WebhookCreate = WebhookCreate;
2230
1384
  type models_WebhookCreated = WebhookCreated;
1385
+ type models_WebhookDelivery = WebhookDelivery;
1386
+ type models_WebhookSecretRotated = WebhookSecretRotated;
2231
1387
  type models_WebhookTestResult = WebhookTestResult;
2232
1388
  type models_WebhookUpdate = WebhookUpdate;
2233
1389
  declare namespace models {
2234
- export type { models_ApiKey as ApiKey, models_ApiKeyCreate as ApiKeyCreate, models_ApiKeyCreated as ApiKeyCreated, models_Batch as Batch, models_BatchSend as BatchSend, models_BatchSendResult as BatchSendResult, models_BrandKit as BrandKit, models_BrandKitList as BrandKitList, models_Campaign as Campaign, models_CampaignCreate as CampaignCreate, models_CampaignReschedule as CampaignReschedule, models_CampaignUpdate as CampaignUpdate, models_Contact as Contact, models_ContactCreate as ContactCreate, models_ContactField as ContactField, models_ContactFieldCreate as ContactFieldCreate, models_ContactFieldRename as ContactFieldRename, models_ContactFieldUpdate as ContactFieldUpdate, models_ContactImport as ContactImport, models_ContactImportCreate as ContactImportCreate, models_ContactTopic as ContactTopic, models_ContactTopicSet as ContactTopicSet, models_ContactUpdate as ContactUpdate, models_Domain as Domain, models_DomainCreate as DomainCreate, models_DomainUpdate as DomainUpdate, Email$1 as Email, models_EmailPatch as EmailPatch, models_EmailStats as EmailStats, Error$1 as Error, models_ReceivedAttachmentUrl as ReceivedAttachmentUrl, models_ReceivedEmail as ReceivedEmail, models_ReceivedEmailSummary as ReceivedEmailSummary, models_Segment as Segment, models_SegmentCreate as SegmentCreate, models_SegmentMember as SegmentMember, models_SegmentMemberAdd as SegmentMemberAdd, models_SegmentUpdate as SegmentUpdate, models_SendEmail as SendEmail, models_SendResult as SendResult, models_Suppression as Suppression, models_SuppressionBulkResult as SuppressionBulkResult, models_SuppressionCreate as SuppressionCreate, models_Template as Template, models_TemplateCreate as TemplateCreate, models_TemplateUpdate as TemplateUpdate, models_Topic as Topic, models_TopicCreate as TopicCreate, models_TopicUpdate as TopicUpdate, Usage$1 as Usage, models_Webhook as Webhook, models_WebhookCreate as WebhookCreate, models_WebhookCreated as WebhookCreated, models_WebhookTestResult as WebhookTestResult, models_WebhookUpdate as WebhookUpdate };
1390
+ export type { models_ApiKey as ApiKey, models_ApiKeyCreate as ApiKeyCreate, models_ApiKeyCreated as ApiKeyCreated, models_Batch as Batch, models_BatchSend as BatchSend, models_BatchSendResult as BatchSendResult, models_BrandKit as BrandKit, models_BrandKitList as BrandKitList, models_Campaign as Campaign, models_CampaignCreate as CampaignCreate, models_CampaignReschedule as CampaignReschedule, models_CampaignSend as CampaignSend, models_CampaignUpdate as CampaignUpdate, models_Contact as Contact, models_ContactCreate as ContactCreate, models_ContactField as ContactField, models_ContactFieldCreate as ContactFieldCreate, models_ContactFieldRename as ContactFieldRename, models_ContactFieldUpdate as ContactFieldUpdate, models_ContactImport as ContactImport, models_ContactImportCreate as ContactImportCreate, models_ContactTopic as ContactTopic, models_ContactTopicSet as ContactTopicSet, models_ContactUpdate as ContactUpdate, models_Domain as Domain, models_DomainCreate as DomainCreate, models_DomainDiagnosis as DomainDiagnosis, models_DomainUpdate as DomainUpdate, Email$1 as Email, models_EmailPatch as EmailPatch, models_EmailStats as EmailStats, Error$1 as Error, models_Job as Job, models_ReceivedAttachmentUrl as ReceivedAttachmentUrl, models_ReceivedEmail as ReceivedEmail, models_ReceivedEmailSummary as ReceivedEmailSummary, models_Segment as Segment, models_SegmentCreate as SegmentCreate, models_SegmentMember as SegmentMember, models_SegmentMemberAdd as SegmentMemberAdd, models_SegmentUpdate as SegmentUpdate, models_SendEmail as SendEmail, models_SendResult as SendResult, Sms$1 as Sms, models_SmsBrand as SmsBrand, models_SmsCampaign as SmsCampaign, models_SmsCampaignCreate as SmsCampaignCreate, models_SmsCampaignReschedule as SmsCampaignReschedule, models_SmsCampaignSend as SmsCampaignSend, models_SmsCampaignUpdate as SmsCampaignUpdate, models_SmsCampaignValidation as SmsCampaignValidation, models_SmsConsent as SmsConsent, models_SmsConsentRecord as SmsConsentRecord, models_SmsConsentRecorded as SmsConsentRecorded, models_SmsNumber as SmsNumber, models_SmsPatch as SmsPatch, models_SmsSend as SmsSend, models_SmsStats as SmsStats, models_SmsTemplate as SmsTemplate, models_SmsTemplateCreate as SmsTemplateCreate, models_SmsTemplateUpdate as SmsTemplateUpdate, models_Suppression as Suppression, models_SuppressionBulkResult as SuppressionBulkResult, models_SuppressionCreate as SuppressionCreate, models_Template as Template, models_TemplateCreate as TemplateCreate, models_TemplateTestSend as TemplateTestSend, models_TemplateTestSendResult as TemplateTestSendResult, models_TemplateUpdate as TemplateUpdate, models_Topic as Topic, models_TopicCreate as TopicCreate, models_TopicUpdate as TopicUpdate, Usage$1 as Usage, models_Webhook as Webhook, models_WebhookCreate as WebhookCreate, models_WebhookCreated as WebhookCreated, models_WebhookDelivery as WebhookDelivery, models_WebhookSecretRotated as WebhookSecretRotated, models_WebhookTestResult as WebhookTestResult, models_WebhookUpdate as WebhookUpdate };
2235
1391
  }
2236
1392
 
1393
+ /** Filters for `sms.list` / `sms.listAll`. */
1394
+ type SmsListParams = ListParams & {
1395
+ direction?: "inbound" | "outbound";
1396
+ status?: string;
1397
+ from?: string;
1398
+ to?: string;
1399
+ /** The other party's number: both directions of the conversation. */
1400
+ participant?: string;
1401
+ contact_id?: string;
1402
+ campaign_id?: string;
1403
+ created_after?: string;
1404
+ created_before?: string;
1405
+ };
2237
1406
  type Result<T> = Promise<{
2238
1407
  data: T | null;
2239
1408
  error: UnitpostError | null;
@@ -2245,6 +1414,129 @@ declare class Resource {
2245
1414
  protected readonly http: HttpClient;
2246
1415
  constructor(http: HttpClient);
2247
1416
  }
1417
+ declare class Sms extends Resource {
1418
+ /** SMS templates: plain-text bodies with `{{variable}}` placeholders. */
1419
+ readonly templates: SmsTemplates;
1420
+ /** SMS campaigns: a published SMS template sent to a segment. */
1421
+ readonly campaigns: SmsCampaigns;
1422
+ /** SMS subscription topics (independent from email topics). */
1423
+ readonly topics: SmsTopics;
1424
+ constructor(http: HttpClient);
1425
+ /**
1426
+ * Send or schedule an SMS message.
1427
+ *
1428
+ * The recipient must be E.164 (`+15551234567`). Marketing sends require the
1429
+ * recipient's prior express consent on record and honor recipient-local
1430
+ * quiet hours (deferred, never dropped). Billing is per segment. An
1431
+ * `Idempotency-Key` is generated automatically when you don't pass one.
1432
+ */
1433
+ send(body: SmsSend, opts?: SendOptions): Result<Sms$1>;
1434
+ /** Retrieve one SMS message's status and delivery state. */
1435
+ get(id: string): Result<Sms$1>;
1436
+ /**
1437
+ * Cancel a queued/scheduled SMS (`{ cancel: true }` — its reserved credit is
1438
+ * refunded) or move a scheduled one (`{ scheduled_at }`).
1439
+ */
1440
+ update(id: string, body: SmsPatch): Result<Sms$1>;
1441
+ /**
1442
+ * List SMS messages (cursor-paginated, newest first). `participant` returns
1443
+ * the whole conversation with one number: texts you sent them and their
1444
+ * replies.
1445
+ */
1446
+ list(params?: SmsListParams): Result<ListResponse<Sms$1>>;
1447
+ /** Async-iterate every SMS message (same filters as `list`). */
1448
+ listAll(params?: SmsListParams): AsyncGenerator<Sms$1, void, void>;
1449
+ /**
1450
+ * List SMS brands and their setup status.
1451
+ *
1452
+ * A brand is the business identity carriers register before they approve a
1453
+ * phone number, so this is what to poll to answer "is SMS ready yet?":
1454
+ * `status` says whether you or the carrier is the blocker, and `missing`
1455
+ * lists exactly what is still required.
1456
+ *
1457
+ * Read-only — creating a brand is a paid carrier submission and is only
1458
+ * available in the dashboard.
1459
+ */
1460
+ brands(params?: ListParams): Result<ListResponse<SmsBrand>>;
1461
+ /**
1462
+ * List SMS phone numbers.
1463
+ *
1464
+ * Only numbers with `status: "active"` can send. A `ten_dlc` number has no
1465
+ * `phone_number` until carriers approve it, and a `simulator` number only
1466
+ * reaches verified test destinations.
1467
+ *
1468
+ * Read-only — requesting or releasing a number is only available in the
1469
+ * dashboard.
1470
+ */
1471
+ numbers(params?: ListParams): Result<ListResponse<SmsNumber>>;
1472
+ /**
1473
+ * SMS delivery stats over a rolling window: queued, sent, delivered,
1474
+ * failed, suppressed, canceled, inbound and segments billed, with delivery,
1475
+ * failure and suppression rates. No opens or clicks on SMS.
1476
+ *
1477
+ * `days` is the window size (1–365); defaults to 30 server-side.
1478
+ */
1479
+ stats(params?: {
1480
+ days?: number;
1481
+ }): Result<SmsStats>;
1482
+ /** Read a contact's SMS consent state and immutable consent history. */
1483
+ smsConsent(contactId: string): Result<SmsConsent>;
1484
+ /** Record an SMS consent change (opt-in or opt-out) for a contact. */
1485
+ recordSmsConsent(contactId: string, body: SmsConsentRecord): Result<SmsConsentRecorded>;
1486
+ }
1487
+ /**
1488
+ * SMS templates (`/sms/templates`). Draft → published like email templates;
1489
+ * only published templates can be sent by an SMS campaign.
1490
+ */
1491
+ declare class SmsTemplates extends Resource {
1492
+ list(params?: ListParams): Result<ListResponse<SmsTemplate>>;
1493
+ listAll(params?: ListParams): AsyncGenerator<SmsTemplate, void, void>;
1494
+ create(body: SmsTemplateCreate): Result<SmsTemplate>;
1495
+ get(id: string): Result<SmsTemplate>;
1496
+ update(id: string, body: SmsTemplateUpdate): Result<SmsTemplate>;
1497
+ delete(id: string): Result<null>;
1498
+ }
1499
+ /** SMS subscription topics (`/sms/topics`); `delete` archives. */
1500
+ declare class SmsCampaigns extends Resource {
1501
+ list(params?: ListParams): Result<ListResponse<SmsCampaign>>;
1502
+ listAll(params?: ListParams): AsyncGenerator<SmsCampaign, void, void>;
1503
+ /** Create a draft. Omit `sender_id` for automatic routing. */
1504
+ create(body: SmsCampaignCreate): Result<SmsCampaign>;
1505
+ get(id: string): Result<SmsCampaign>;
1506
+ /** Edit a draft (409 once sent or scheduled). */
1507
+ update(id: string, body: SmsCampaignUpdate): Result<SmsCampaign>;
1508
+ /** Archive a draft or finished campaign (cancel an in-flight one first). */
1509
+ delete(id: string): Result<null>;
1510
+ /**
1511
+ * Send now, or pass `{ scheduled_at }` to schedule. A large audience whose
1512
+ * recipient check is still running is refused with `409 preflight_pending`:
1513
+ * poll `validate(id)` until it returns the report, then send again.
1514
+ */
1515
+ send(id: string, body?: SmsCampaignSend): Result<SmsCampaign>;
1516
+ /**
1517
+ * The campaign, already `canceled`. With more than 500 queued texts (202)
1518
+ * they are canceled and refunded in the background.
1519
+ */
1520
+ cancel(id: string): Result<SmsCampaign>;
1521
+ pause(id: string): Result<SmsCampaign>;
1522
+ resume(id: string): Result<SmsCampaign>;
1523
+ reschedule(id: string, body: SmsCampaignReschedule): Result<SmsCampaign>;
1524
+ /**
1525
+ * Who the campaign would reach if sent now (non-mutating). A large audience
1526
+ * is counted in the background: the first call returns that `Job` (202).
1527
+ * Call again until it returns the report; tell them apart with `object`
1528
+ * (`"job"`).
1529
+ */
1530
+ validate(id: string): Result<SmsCampaignValidation | Job>;
1531
+ }
1532
+ declare class SmsTopics extends Resource {
1533
+ list(params?: ListParams): Result<ListResponse<Topic>>;
1534
+ listAll(params?: ListParams): AsyncGenerator<Topic, void, void>;
1535
+ create(body: TopicCreate): Result<Topic>;
1536
+ get(id: string): Result<Topic>;
1537
+ update(id: string, body: TopicUpdate): Result<Topic>;
1538
+ delete(id: string): Result<null>;
1539
+ }
2248
1540
  declare class Email extends Resource {
2249
1541
  readonly topics: Topics;
2250
1542
  readonly campaigns: Campaigns;
@@ -2308,6 +1600,7 @@ declare class Contacts extends Resource {
2308
1600
  import(body: ContactImportCreate): Result<ContactImport>;
2309
1601
  listImports(params?: ListParams): Result<ListResponse<ContactImport>>;
2310
1602
  getImport(id: string): Result<ContactImport>;
1603
+ cancelImport(id: string): Result<ContactImport>;
2311
1604
  }
2312
1605
  declare class ContactFields extends Resource {
2313
1606
  list(params?: ListParams): Result<ListResponse<ContactField>>;
@@ -2315,8 +1608,26 @@ declare class ContactFields extends Resource {
2315
1608
  create(body: ContactFieldCreate): Result<ContactField>;
2316
1609
  get(id: string): Result<ContactField>;
2317
1610
  update(id: string, body: ContactFieldUpdate): Result<ContactField>;
2318
- delete(id: string): Result<null>;
2319
- rename(id: string, body: ContactFieldRename): Result<ContactField>;
1611
+ /**
1612
+ * `null` (204) when the field was deleted at once; a `Job` (202) when it
1613
+ * held a value on more than 5,000 contacts and the delete runs in the
1614
+ * background — follow it with `jobs.get(job.id)`.
1615
+ */
1616
+ delete(id: string): Result<null | Job>;
1617
+ /**
1618
+ * The renamed `ContactField` (200), or a `Job` (202) when more than 5,000
1619
+ * contacts hold the field: the key is already renamed and the values move in
1620
+ * the background — follow it with `jobs.get(job.id)`. Tell them apart with
1621
+ * `object` (`"contact_field"` / `"job"`).
1622
+ */
1623
+ rename(id: string, body: ContactFieldRename): Result<ContactField | Job>;
1624
+ }
1625
+ declare class Jobs extends Resource {
1626
+ /**
1627
+ * Retrieve a background job — the `202` answer of an operation too large for
1628
+ * one request. Poll until `status` is `COMPLETED`, `FAILED` or `CANCELED`.
1629
+ */
1630
+ get(id: string): Result<Job>;
2320
1631
  }
2321
1632
  declare class Segments extends Resource {
2322
1633
  list(params?: ListParams): Result<ListResponse<Segment>>;
@@ -2350,14 +1661,23 @@ declare class Campaigns extends Resource {
2350
1661
  get(id: string): Result<Campaign>;
2351
1662
  update(id: string, body: CampaignUpdate): Result<Campaign>;
2352
1663
  delete(id: string): Result<null>;
2353
- send(id: string): Result<Campaign>;
1664
+ /**
1665
+ * Send a draft. `{}` (the default) arms its saved `scheduled_at` while that
1666
+ * is still ahead, otherwise sends NOW; `{ scheduled_at: "<ISO 8601>" }`
1667
+ * schedules it; `{ scheduled_at: null }` sends now.
1668
+ */
1669
+ send(id: string, body?: CampaignSend): Result<Campaign>;
2354
1670
  cancel(id: string): Result<Campaign>;
2355
1671
  /** Pause a scheduled/sending campaign; already-sent messages are untouched. */
2356
1672
  pause(id: string): Result<Campaign>;
2357
1673
  /** Resume a paused campaign; sending continues with the remaining recipients. */
2358
1674
  resume(id: string): Result<Campaign>;
2359
1675
  reschedule(id: string, body: CampaignReschedule): Result<Campaign>;
2360
- /** Non-mutating pre-send validation report. */
1676
+ /**
1677
+ * Non-mutating pre-send validation report. A large audience is counted in
1678
+ * the background: the first call returns that `Job` (202). Call again until
1679
+ * it returns the report.
1680
+ */
2361
1681
  validate(id: string): Result<unknown>;
2362
1682
  }
2363
1683
  declare class Templates extends Resource {
@@ -2367,6 +1687,12 @@ declare class Templates extends Resource {
2367
1687
  get(id: string): Result<Template>;
2368
1688
  update(id: string, body: TemplateUpdate): Result<Template>;
2369
1689
  delete(id: string): Result<null>;
1690
+ /**
1691
+ * Send ONE test of the template to `to`, rendered with sample `variables`
1692
+ * exactly as a recipient gets it. Without a verified domain only workspace
1693
+ * members may receive it.
1694
+ */
1695
+ testSend(id: string, body: TemplateTestSend): Result<TemplateTestSendResult>;
2370
1696
  }
2371
1697
  /** Read-only Brand Kit profiles (voice, colors, pinned `/img/{id}` graphics). */
2372
1698
  declare class BrandKits extends Resource {
@@ -2388,6 +1714,8 @@ declare class Domains extends Resource {
2388
1714
  verify(id: string): Result<Domain & {
2389
1715
  checks?: unknown;
2390
1716
  }>;
1717
+ /** Explain the domain's DNS: every nameserver's answer per record, and ranked findings with fixes. Read-only. */
1718
+ diagnose(id: string): Result<DomainDiagnosis>;
2391
1719
  }
2392
1720
  declare class Webhooks extends Resource {
2393
1721
  list(params?: ListParams): Result<ListResponse<Webhook>>;
@@ -2399,6 +1727,15 @@ declare class Webhooks extends Resource {
2399
1727
  delete(id: string): Result<null>;
2400
1728
  /** Fire a synchronous sample event at the endpoint. */
2401
1729
  test(id: string): Result<WebhookTestResult>;
1730
+ /**
1731
+ * Mint a new signing secret. The response carries it exactly once; the old
1732
+ * secret co-signs deliveries until `previous_secret_expires_at` (24 h).
1733
+ */
1734
+ rotateSecret(id: string): Result<WebhookSecretRotated>;
1735
+ /** The endpoint's delivery log, newest first (cursor-paginated). */
1736
+ listDeliveries(id: string, params?: ListParams): Result<ListResponse<WebhookDelivery>>;
1737
+ /** Async-iterate every delivery of the endpoint. */
1738
+ listAllDeliveries(id: string, params?: ListParams): AsyncGenerator<WebhookDelivery, void, void>;
2402
1739
  /**
2403
1740
  * Verify a webhook delivery's signature and return the parsed event. Throws
2404
1741
  * `WebhookVerificationError` on a missing/invalid/stale signature. Alias of the
@@ -2414,8 +1751,12 @@ declare class ApiKeys extends Resource {
2414
1751
  delete(id: string): Result<null>;
2415
1752
  }
2416
1753
  declare class Suppressions extends Resource {
2417
- /** List suppressed addresses (your own + read-only platform rows). */
1754
+ /**
1755
+ * List your workspace's suppressed addresses. Unitpost-wide (platform)
1756
+ * blocks are enforced at send time but not listed — `get(email)` explains one.
1757
+ */
2418
1758
  list(params?: ListParams & {
1759
+ /** @deprecated Ignored since 2026-10-13: the list is always your own suppressions. */
2419
1760
  scope?: "workspace" | "platform";
2420
1761
  }): Result<ListResponse<Suppression>>;
2421
1762
  /** Async-iterate every suppressed address. */
@@ -2442,8 +1783,14 @@ declare class Usage extends Resource {
2442
1783
 
2443
1784
  declare class Unitpost {
2444
1785
  readonly email: Email;
1786
+ /**
1787
+ * SMS channel. Available on paid plans: on the free plan `send` returns a
1788
+ * 403 with code `limit_reached`; reads keep working.
1789
+ */
1790
+ readonly sms: Sms;
2445
1791
  readonly contacts: Contacts;
2446
1792
  readonly contactFields: ContactFields;
1793
+ readonly jobs: Jobs;
2447
1794
  readonly segments: Segments;
2448
1795
  readonly brandKits: BrandKits;
2449
1796
  readonly webhooks: Webhooks;
@@ -2453,4 +1800,4 @@ declare class Unitpost {
2453
1800
  constructor(apiKeyOrOptions?: string | UnitpostOptions);
2454
1801
  }
2455
1802
 
2456
- export { type ListParams, type ListResponse, models as Models, type Result, SDK_VERSION, type SendOptions, Unitpost, UnitpostError, type UnitpostOptions, type VerifyWebhookArgs, WebhookVerificationError, verifyWebhook };
1803
+ export { type ListParams, type ListResponse, models as Models, type Result, SDK_VERSION, type SendOptions, type SmsListParams, Unitpost, UnitpostError, type UnitpostOptions, type VerifyWebhookArgs, WebhookVerificationError, verifyWebhook };