unitpost 0.3.0 → 0.5.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/CHANGELOG.md ADDED
@@ -0,0 +1,327 @@
1
+ # Changelog
2
+
3
+ Notable changes to the Unitpost Node.js SDK. Changes to the API itself (new
4
+ operations, new fields, behavior changes) are in the API changelog:
5
+ https://www.unitpost.com/docs/changelog.
6
+
7
+ To release, move the `Unreleased` items under a `## X.Y.Z` heading in the same
8
+ change that bumps the version (docs/sdk/RELEASING.md).
9
+
10
+ ## Unreleased
11
+
12
+ ## 0.5.0
13
+
14
+ - `UnitpostOrganization` gains `sharedPlan`: `get`, `listWorkspaces`, `addWorkspace`, `updateWorkspace`, `removeWorkspace` (the organization's shared plan; adding and removing take an optional idempotency key, or the SDK mints one). Reads need `organizations:read`; the three writes need `organizations:billing`. Buying, upgrading or ending the shared plan stays in the dashboard.
15
+ - `UnitpostOrganization` iterators: `webhooks.listAll()`, `webhooks.listAllDeliveries(webhookId)` and `usage.listAll()` (pages by `workspace_id`). The delivery log needs `organizations:write`.
16
+ - SMS tags: `sms.send({ …, tags: [{ name, value }] })` (up to 10) and `sms.list({ tag })` / `sms.listAll({ tag })`, where `tag` is `"name:value"`, several comma-separated, or an array; texts carrying all of them. The SMS object carries `tags`.
17
+ - `spendCaps` (new, ADR-0172): the workspace's monthly spend caps. `get()` reads the SMS-purchase cap, its `max_cents` and what it counted this UTC month; `update(body)` sets or clears it and needs `spend_caps:write`, which no key preset includes. A workspace its organization pays for answers `403 billed_by_organization`.
18
+ - `UnitpostOrganization` (new, ADR-0171): the client for an organization key
19
+ (`ok_live_…`), made with the key and the organization's id
20
+ (`UNITPOST_ORG_KEY` and `UNITPOST_ORGANIZATION_ID` when left out). It has
21
+ `workspaces` (`list`, `listAll`, `create` with an idempotency key, `get`,
22
+ `update`, `close`, `restore`), `workspaceKeys.create`, `webhooks` (the
23
+ organization's endpoints), `usage.list` and `planQuotes` (`create`, `get`,
24
+ `confirm` with an idempotency key). The workspace client `Unitpost` doesn't
25
+ carry them.
26
+ - `sms.addContact(id)`, `sms.listJoinKeywords(numberId)`, `sms.addJoinKeyword(numberId, body)`, `sms.removeJoinKeyword(numberId, keywordId)`: add a texter as a contact and manage text-to-join keywords.
27
+ - `SmsFailureCode` gains `sms_not_in_plan`: SMS wasn't on the plan when a text was due (the paid plan ended after its grace, or the plan is 100% discounted). Not charged.
28
+ - SMS numbers and registrations, start to finish (ADR-0160, 2026-11-12):
29
+ `sms.getNumber(id)`, `sms.releaseNumber(id, { force }, { idempotencyKey })`
30
+ (permanent), `sms.registrations.get(id)`, `sms.registrations.remove(id)` (a
31
+ 10DLC setup with no number) and `sms.registrations.replace(id)` (an approved
32
+ brand registration). Every new write mints an Idempotency-Key when you
33
+ don't pass one.
34
+ - Files and SMS onboarding by API (ADR-0159, 2026-11-12):
35
+ - `files` (new): `list({ purpose })`, `create(body, { idempotencyKey })`,
36
+ `get(id)`, `delete(id)`. A file (`file_` id) is bytes handed to the API
37
+ for one `purpose` (`sms_opt_in_evidence`, `sms_document`, `image`) from a
38
+ `url`, base64 `data`, or an upload session, used by `file_id` and
39
+ expiring after 24 hours.
40
+ - `files.upload({ path | data, purpose, contentType, filename? })`: sends a
41
+ file up to 3 MB inline, and a larger one through an upload session (the
42
+ create, a PUT of the bytes with exactly `upload.headers`, then `get`).
43
+ - `sms`: a brand's documents (`listBrandDocuments(brandId)`,
44
+ `addBrandDocument(brandId, body, { idempotencyKey })`,
45
+ `getBrandDocument`, `removeBrandDocument`, and `brandDocumentUrl`, a
46
+ 5-minute signed link), and `resubmitNumber(numberId, body, {
47
+ idempotencyKey })` for a toll-free verification carriers sent back.
48
+ - `sms.registrations`: `resubmit(id, body, { idempotencyKey })` for a 10DLC
49
+ campaign carriers sent back, and `requestNumber(id, {}, {
50
+ idempotencyKey })` to retry a failed number whose fee is committed.
51
+ - Every new write generates an Idempotency-Key when you don't pass one.
52
+ - `error.docUrl`: the page the API links for an error, when it links one (today `sending_paused`, a paused sending stream; ADR-0156). `null`/`None` otherwise. The `Campaign.pause_reason.code` union adds `sending_paused`.
53
+ - A result carries `warning`, the response's `Unitpost-Warning` header, when a
54
+ successful call had one: something it left out or ignored without failing,
55
+ for example a recipient on a reserved domain (example.com) that wasn't sent
56
+ to, or a body field the operation ignored. Absent otherwise. The new
57
+ `ApiResult` type names the `{ data, error, warning? }` shape. Before this
58
+ the header was dropped, so an SDK caller couldn't tell a recipient was left
59
+ out (verifier on #1217).
60
+ - `ApiFieldError` (an entry of `UnitpostError.details`) declares the optional
61
+ `code`, a machine-readable reason for the entry, such as the SMS skip word
62
+ on `to` (`out_of_reach`). The type is now exported.
63
+ - The SMS list takes `sender_id`, a number's `snum_…` id: that number's
64
+ texts, both directions. A value it can't apply is ignored and named in the
65
+ `Unitpost-Warning` response header; `Unitpost-Strict: true` refuses it.
66
+ - `sms.quotes` (new): `create(body)`, `get(id)` and `confirm(id, {
67
+ confirm_token }, { idempotencyKey })` buy SMS carrier resources (`squote_`
68
+ ids): register a 10DLC brand, vet it, register a campaign, order a number.
69
+ `confirm` generates an Idempotency-Key when you don't pass one, so a retry
70
+ can't buy twice. `create` prices the order and binds what it buys (the
71
+ brand's and program's content, the price) and returns `due_now_cents`,
72
+ `monthly_cents`, `line_items` and a single-use `confirm_token` (`sqct_`),
73
+ only in that response; a quote lasts 10 minutes and charges nothing. The
74
+ confirm places the order at that price, or answers `409` when the price or
75
+ content changed. It needs `sms:purchase`, which no key preset includes, and
76
+ the workspace owner's monthly cap for SMS purchases by API (no cap set
77
+ refuses it). Show the person the price and get their yes before confirming.
78
+ - `logs.list(params)` (new `logs` resource): the workspace's API request
79
+ log, newest first and cursor-paginated (`rlog_` ids). Each row is one call:
80
+ `method`, `path`, `status`, `duration_ms`, `api_key_id` and its
81
+ `request_id` (the `x-request-id`), never the caller's IP or a body; rows are
82
+ kept 30 days. Filters (`LogListParams`): `status` (a code or `2xx`…`5xx`),
83
+ `api_key_id`, `method`, `path_prefix`, `request_id`, `created_after`,
84
+ `created_before`. It needs `apikeys:read`, which no key preset includes.
85
+ - Opt many contacts out of a topic at once: `email.topics.optOut(id, body, { idempotencyKey })`
86
+ and `sms.topics.optOut(id, body, { idempotencyKey })` (`TopicOptOut`: exactly
87
+ one of `contact_ids` or `emails`, up to 1,000, or `segment_id`). They answer
88
+ a `Job` (202); follow it with `jobs.get(id)`. The SDK mints an idempotency
89
+ key when you pass none, so a retry answers the same job. There is no bulk
90
+ opt-in. Needs `topics:write` (a segment also `segments:read`).
91
+ - `sms.registrations.list`, `sms.testDestinations.list`,
92
+ `sms.consentSetups.list`, `sms.billing.listResources` and
93
+ `sms.messagingPrograms.list` take `limit`, `after` and `before`
94
+ (`ListParams`): the five lists are cursor-paginated, newest first.
95
+ - New response fields are optional in the models (the API always sends
96
+ them), so a value typed as a model with only its 0.4.0 fields still
97
+ type-checks.
98
+ - The activity log, an API key's usage, several topic preferences at once and
99
+ list search. `workspace.listActivity(params)` / `listAllActivity`: the
100
+ workspace's activity log, newest first (cursor-paginated on `act_` ids):
101
+ what changed, when, who (`actor.name`) and, for a change over the API, MCP
102
+ or Ask Unit, how (`actor.via`, with the API key). Narrow it with `subject`
103
+ (and `subject_id`), `contact_id`, `campaign_id`, `q` and `channel: "email"`
104
+ (`ActivityListParams`; an unknown key is a `422`). It needs `activity:read`.
105
+ `apiKeys.usage(id)` returns `ApiKeyUsage`: a key's requests in the last 24
106
+ hours (`requests_24h`, `client_errors_24h`, `server_errors_24h`,
107
+ `rate_limited_24h`) and `last_used_at`. `apiKeys.list` now also works with
108
+ an API key or an MCP sign-in (it was dashboard-session only); with one,
109
+ `list` and `usage` need `apikeys:read`. Creating and revoking keys stay in
110
+ the dashboard. No key preset includes `activity:read` or `apikeys:read`.
111
+ `email.topics.updateTopics(contactId, { topics: [{ topic_id, subscribed }] })`
112
+ (`PATCH /contacts/{id}/topics`, up to 50) changes several of a contact's
113
+ preferences at once, leaves the others as they are, and returns
114
+ `ContactTopicList`; `setTopic` is unchanged. `email.list` /
115
+ `listAll` take `q` (an exact recipient, or part of the subject or the
116
+ sender), `source` (`api` | `smtp` | `test` | `batch` | `campaign` | `reply`)
117
+ and `outcome` (`delivered` | `opened` | `clicked` | `unsubscribed` |
118
+ `bounced` | `complained` | `failed` | `pending`; with `campaign_id`, who
119
+ opened or clicked it). `sms.list` / `listAll` take `q` (the message text, or
120
+ 3 or more digits of either number) and `type` (`transactional` |
121
+ `marketing`). A `q`, `source`, `outcome` or `type` value the API can't apply
122
+ is ignored and named in the `Unitpost-Warning` response header;
123
+ `Unitpost-Strict: true` refuses it.
124
+ - List filters and a stats period. `suppressions.list` / `listAll` take `q`
125
+ (part of the address), `reason` and `created_after` / `created_before`
126
+ (`SuppressionListParams`; `scope` stays, deprecated).
127
+ `webhooks.listDeliveries` / `listAllDeliveries` take `status`
128
+ (comma-separated, e.g. `"failed,exhausted"`) and `event_type`
129
+ (`WebhookDeliveryListParams`). `email.stats` keeps `days` and takes a period
130
+ instead: `from` / `to`, with `grain` (`5m` | `1h` | `1d`) and `tz` for
131
+ `series`, the send volume per bucket, and `domain_id` for one sending domain
132
+ (`EmailStatsParams`). These lists ignored the filters before, so a value the
133
+ API can't apply is ignored and named in the `Unitpost-Warning` response
134
+ header; `Unitpost-Strict: true` refuses it. `webhooks.get` still returns
135
+ `Webhook`, which adds an optional `backlog: { queued, failed }` (what a flush
136
+ would send; only `get` fills it). `EmailStats` adds the permanent and transient bounces,
137
+ `suppressed`, `unsubscribed`, `rates.unsubscribe`, `domain_id`, `from`, `to`
138
+ and `series`; `Topic` adds `subscriber_count` and `unsubscribed_count`;
139
+ `Usage` adds the plan's `limits` and `features`.
140
+ - Who is calling, an email's events, a received email's original and
141
+ template rendering. `workspace.whoami()`: the workspace, the credential (an
142
+ API key or an OAuth sign-in, never its secret), its `capabilities` and the
143
+ workspace's rate limit; any valid credential may call it, so call it first
144
+ to see what a key may do. `email.listEvents(id, { limit, after, before })`:
145
+ one email's delivery events, oldest first, with each event's detail under
146
+ the webhook's names (cursor-paginated on `emev_` ids; no `listAll`).
147
+ `email.receivedRaw(id)`: a signed URL (about 5 minutes) to a received
148
+ message's original `.eml`, the way to read a body over 256 KB; a copy of
149
+ your own send is a `403`.
150
+ `email.templates.render(id, { variables, subject, contact_id })`: the
151
+ subject, HTML and text a send would carry, and its `missing_variables`; it
152
+ sends and stores nothing, so it takes no idempotency key, and the body is
153
+ optional. `listEvents` and `receivedRaw` need `emails:read`; `render` needs
154
+ `templates:read`. `email.get` still returns `Email`, which adds optional
155
+ `cc`, `bcc`, `reply_to` and `tags` (only `get` fills them).
156
+ - SMS brands and registrations. On `sms`:
157
+ `createBrand(body, { idempotencyKey })`, `getBrand(id)` and
158
+ `updateBrand(id, body)` (send `{ archived }` alone to archive or restore).
159
+ A new resource on `sms`: `sms.registrations.list(params)`, cursor-paginated
160
+ (no `listAll`). Creating a brand is free and makes
161
+ no carrier call; its tax id is write-only (read back as `tax_id_on_file`),
162
+ and a locked brand refuses carrier-field edits with `409 brand_locked`.
163
+ The reads need `sms:read`; the brand writes need `sms:manage`. Registering
164
+ a brand with carriers (a paid step), ordering numbers and a brand's
165
+ documents stay in the dashboard.
166
+ - SMS setup. On `sms.templates`: `usage(id)` and
167
+ `testSend(id, { to, variables, sender_id }, { idempotencyKey })`. Four new
168
+ resources on `sms`: `sms.messagingPrograms.list({ archived })`,
169
+ `create(body, { idempotencyKey })`, `get(id)`, `update(id, body)`,
170
+ `delete(id)` (it archives) and `duplicate(id, { idempotencyKey })`;
171
+ `sms.testDestinations.list()` and `delete(id)`; `sms.consentSetups.list()`;
172
+ and `sms.billing.listResources()`. These four lists are cursor-paginated
173
+ (no `listAll`). A test text goes only to the simulator or a
174
+ verified test number, and is billed like any text. The reads need `sms:read`
175
+ (`usage` needs `templates:read`); the test send needs `sms:send`; the
176
+ program writes and removing a test number need `sms:manage` (FULL keys have
177
+ it, SENDING keys don't). Ordering numbers, sender
178
+ registrations and payments stay in the dashboard.
179
+ - Brand Kit writes and imports on `brandKits`:
180
+ `brandKits.create({ name, make_default })`, `brandKits.update(id, body)`,
181
+ `brandKits.delete(id)`, `brandKits.reset(id)`, `brandKits.setDefault(id)`
182
+ and `brandKits.addGraphic(id, { url, role, label })`;
183
+ `brandKits.import({ url | text, website_url, brand_kit_id, review, sync_visual })`,
184
+ `brandKits.getImport(id)`,
185
+ `brandKits.acceptImport(id, { brand_kit_id, name, sync_visual })` (the body
186
+ is optional) and `brandKits.cancelImport(id)`. An import builds a profile
187
+ from a website (`url`) or the brand's own words (`text`) in the background
188
+ (`202`; follow it with `getImport`). By default it is applied when it lands;
189
+ with `review: true` it stops at a proposal for `acceptImport`. Deleting the
190
+ last profile is a `409` (reset it instead). `addGraphic` brings an image
191
+ from a public https URL into the image library and pins it. The writes, and
192
+ starting, accepting or canceling an import, need the `branding:write`
193
+ capability, which no key preset grants: tick it on the key. The reads stay
194
+ `templates:read`.
195
+ - Three new resources. Image library:
196
+ `libraryImages.list({ limit, after, before })`, `libraryImages.listAll()`,
197
+ `libraryImages.create({ url | data, content_type, filename, alt }, { idempotencyKey })`,
198
+ `libraryImages.get(id)`, `libraryImages.update(id, { alt })` and
199
+ `libraryImages.delete(id, { force })`. Branding: `branding.get()`,
200
+ `branding.update(body)`,
201
+ `branding.setLogo({ url | data, content_type, filename })` and
202
+ `branding.removeLogo()`. Workspace:
203
+ `workspace.update({ name })`, `workspace.setImage(body)` and
204
+ `workspace.removeImage()`. The library holds the images a template embeds:
205
+ an image's `path` (`/img/…`) goes in a template's `<Image src>`. `create`
206
+ uploads from a public https `url` or base64 `data` (PNG, JPEG, GIF or
207
+ WebP, up to 5 MB) and takes an idempotency key, minted when you don't pass
208
+ one, so a retried upload stores one image. Deleting an image that a
209
+ template, a campaign or sent mail uses is a `409` `resource_in_use` unless
210
+ you pass `{ force: true }` (sent as `?force=true`). `branding` is the look
211
+ of marketing emails' footer and the hosted unsubscribe page, as Settings →
212
+ Brand shows it (`null` restores a default). `workspace` renames the
213
+ workspace and sets its image. `removeLogo` and `removeImage` answer the
214
+ updated object. The branding writes and every `workspace` call need the
215
+ `branding:write` capability, which no key preset grants: tick it on the key.
216
+ - Jobs: `jobs.list({ status, kind, limit, after, before })`,
217
+ `jobs.cancel(id)`, `jobs.retry(id)` and `jobs.download(id)`. Contacts:
218
+ `contacts.export({ q, status, phone, segment_id, segment_subscription })`.
219
+ Segments: `segments.preview(id)`, `segments.previewFilter({ filter })`,
220
+ `segments.allContacts()` and
221
+ `segments.updateMember(id, contact, { subscribed })`.
222
+ `export` starts a background job that writes a CSV of every contact, or
223
+ of the ones the filters match (one export at a time: another while it runs
224
+ is a `409`); follow it with `jobs.get`, then `jobs.download` gives a signed URL to
225
+ the file that expires in 5 minutes. `jobs.list` lists your background jobs;
226
+ `cancel` stops a queued or running one, and `retry` resumes a `FAILED`
227
+ one from where it stopped. `preview` and `previewFilter`
228
+ count who a saved segment or an unsaved filter reaches and how many of them
229
+ a campaign would mail; nothing is saved. `allContacts` returns the
230
+ managed "All subscribed contacts" segment, made the first time you ask.
231
+ `updateMember` opts a member out of a static segment's sends, or back
232
+ in, without removing it. None of these takes an idempotency key.
233
+ - Webhooks: `webhooks.replayDelivery(id, deliveryId)` and
234
+ `webhooks.flush(id, { include_failed })`. Email:
235
+ `email.retry(id, { idempotencyKey })` and
236
+ `email.listBatches({ limit, after, before })`. Domains: sender addresses
237
+ with `email.domains.listSenders({ domain_id, limit, after, before })`,
238
+ `createSender({ address, display_name })`, `getSender(id)`,
239
+ `updateSender(id, { display_name })` and `deleteSender(id)`.
240
+ `replayDelivery` delivers one event again with the same event id, and `flush`
241
+ delivers the deliveries held while a webhook was suspended (with
242
+ `include_failed`, also the ones that failed for good); both need the
243
+ webhook enabled (`409` otherwise). `retry` sends a failed email again on
244
+ the same id (an email that can't be retried is a `409` saying why); it
245
+ sends real email, so it takes an idempotency key and generates one when you
246
+ don't pass it. `listBatches` lists your batch sends with the same
247
+ rollup as `getBatch`. A
248
+ sender is a saved From address on one of your domains; saving a mailbox
249
+ that is already saved there is a `409`.
250
+ - Email templates:
251
+ `email.templates.duplicate(id, { name }, { idempotencyKey })`,
252
+ `email.templates.fromLibrary({ slug, name }, { idempotencyKey })`,
253
+ `email.templates.usage(id)`,
254
+ `email.templates.listVersions(id, { limit, after })` and
255
+ `email.templates.restoreVersion(id, version)`.
256
+ `duplicate` copies a template into a new draft, and `fromLibrary` adds a
257
+ gallery email as a draft Design template (the ones marked for paid plans are
258
+ `403 limit_reached` on the free plan); both take an idempotency key and
259
+ generate one when you don't pass it. `usage` says what uses a template and
260
+ whether an edit would be accepted now. `listVersions` pages by version
261
+ number: pass the last row's `version` as `after`. `restoreVersion` puts a
262
+ version back and is refused with `409` while a live campaign renders the
263
+ template.
264
+ - Inbox conversations: a new `email.threads` resource with
265
+ `list({ q, limit, after })`, `get(id)`, `delete(id)` and
266
+ `reply(id, body, { idempotencyKey })`. A conversation is a received message
267
+ plus the replies and forwards sent from it, as Emails → Received shows them.
268
+ `list` pages with `next_cursor` (pass it as `after`; it is not a row id);
269
+ `delete` erases the received messages for good. `reply` replies, replies all or forwards one received
270
+ message and sends real email, so it takes an idempotency key and generates
271
+ one when you don't pass it.
272
+ - Email campaigns: `email.campaigns.stats(id)`,
273
+ `email.campaigns.listStats(ids)`,
274
+ `email.campaigns.listRecipients(id, { status, limit, after })`,
275
+ `email.campaigns.listAffected(id)`, `email.campaigns.removeAffected(id)` and
276
+ `email.campaigns.requestReview(id)`. SMS campaigns:
277
+ `sms.campaigns.listRecipients(id, { limit, after, before, q })`. `stats`
278
+ reads a campaign's results: delivered, unique opens and clicks,
279
+ unsubscribes, bounces, complaints and their rates. `listStats` reads them
280
+ for up to 100 campaigns at once. On an email campaign, `listRecipients`
281
+ lists who a send now would reach and why any other member would be left out;
282
+ pass the page's `next_cursor` as `after` for the next page. After an
283
+ automatic quality pause, `listAffected` lists the hard-bounced and
284
+ complained addresses, `removeAffected` takes them out of the campaign's
285
+ static segment, and `requestReview` asks for the review a repeat pause needs
286
+ before `resume`. Both are safe to repeat: a second call removes no one and
287
+ notifies no one. On an SMS campaign, `listRecipients` lists how each
288
+ recipient fared, with `skipped_by_reason` counts for the whole campaign.
289
+ - Contacts: `contacts.addresses(idOrEmail)`,
290
+ `contacts.activity(idOrEmail, { limit })`,
291
+ `contacts.listSegments(idOrEmail)` and `contacts.retryImport(id)`. SMS:
292
+ `sms.requestSmsOptIn(contactId, { phone }, { idempotencyKey })`.
293
+ `requestSmsOptIn` texts the contact a request to reply
294
+ YES to confirm marketing texts. It sends a real text, so it sends the
295
+ idempotency key you pass, or one it makes up, and a retry returns the same
296
+ text instead of sending another.
297
+ - Contacts carry `phone`, their SMS number in E.164, on create, update and
298
+ read. `null` on update removes the number only with the `Unitpost-Strict: true` header; without it the number is kept and the response warns. Setting it records no SMS
299
+ consent: record that with `sms.recordSmsConsent`.
300
+ - `contacts.list` / `contacts.listAll` take `q`, `status` (`subscribed` |
301
+ `unsubscribed`), `phone` (`has` | `none`), `segment_id` and
302
+ `segment_subscription` (`subscribed` | `opted_out`); `email.list` /
303
+ `email.listAll` take `to` and `contact_id`.
304
+ - Email and SMS campaigns: `unschedule(id)` and `duplicate(id, { name }, { idempotencyKey })`. Unschedule moves a scheduled campaign
305
+ back to a draft; duplicate copies a campaign into a new draft. Duplicate
306
+ sends the idempotency key you pass, or one it makes up, so a retry returns
307
+ the same copy instead of making a second one.
308
+ - The campaign update model takes `name`, `subject`, `from`, `preview_text`,
309
+ `template_id` and `segment_id`: the API now edits these on a draft.
310
+ - The email campaign and segment lists take the optional `archived` query
311
+ parameter (`archived=true` lists archived rows).
312
+ - The API now answers `422` for a misnamed send time (`send_at`,
313
+ `scheduledAt` on SMS, …) on sends and campaign writes, instead of sending at
314
+ once or dropping it. Use `scheduled_at`.
315
+ - Campaign create's `403` now says which refusal it is: `limit_reached` for
316
+ the plan's contact limit, `domain_not_found` / `domain_blocked` /
317
+ `domain_not_verified` for the sender (it was always `domain_not_verified`).
318
+ Read `error.code` to tell them apart.
319
+ - Domains: the update model takes `capabilities` (`{ receiving: "enabled" |
320
+ "disabled" }` turns receiving on or off), and domain reads carry
321
+ `capabilities` and a `receiving` object (status, the MX record to publish,
322
+ the last checks).
323
+
324
+ ## 0.4.0
325
+
326
+ The release this changelog starts from. Earlier changes are in the git history
327
+ (tags `sdk-node-v*`).
package/README.md CHANGED
@@ -36,6 +36,15 @@ Every method returns `{ data, error }` — an API-level failure populates `error
36
36
  (a typed `UnitpostError`) instead of throwing, so you never need a `try/catch`
37
37
  around a normal request.
38
38
 
39
+ A success can also carry `warning`: the API's note about something it left out
40
+ or ignored without failing the call, such as a recipient on a reserved domain
41
+ (example.com) that wasn't sent to. Log it or show it:
42
+
43
+ ```ts
44
+ const { data, error, warning } = await unitpost.email.send({ ... });
45
+ if (warning) console.warn(warning);
46
+ ```
47
+
39
48
  ## Authentication
40
49
 
41
50
  Pass the key directly, or set `UNITPOST_API_KEY` and construct with no argument:
@@ -47,23 +56,75 @@ const unitpost = new Unitpost(); // reads process.env.UNITPOST_API_KEY
47
56
  Create a key at [unitpost.com → Settings → API keys](https://www.unitpost.com).
48
57
  Options: `new Unitpost({ apiKey, baseUrl, timeout, fetch, headers, maxRetries, retryBaseDelay, maxRetryDelay })`.
49
58
 
59
+ ## Organization keys
60
+
61
+ A platform that gives each of its customers a workspace uses an organization
62
+ key (`ok_live_…`) with the second client, `UnitpostOrganization`. It takes the
63
+ key and the organization's id (`org_…`), and reads `UNITPOST_ORG_KEY` and
64
+ `UNITPOST_ORGANIZATION_ID` when you leave them out:
65
+
66
+ ```ts
67
+ import { Unitpost, UnitpostOrganization } from "unitpost";
68
+
69
+ const org = new UnitpostOrganization({
70
+ apiKey: process.env.UNITPOST_ORG_KEY,
71
+ organizationId: process.env.UNITPOST_ORGANIZATION_ID,
72
+ });
73
+
74
+ const { data: workspace } = await org.workspaces.create({ name: "Acme Bakery", external_id: "cust_42" });
75
+ const { data: minted } = await org.workspaceKeys.create(workspace!.id, { name: "Production", scope: "sending" });
76
+
77
+ // Work inside that workspace with its own key.
78
+ const acme = new Unitpost(minted!.key);
79
+ ```
80
+
81
+ | Accessor | Covers |
82
+ | --- | --- |
83
+ | `workspaces` | `list()` (`external_id` filter), `listAll()`, `create()` (takes an idempotency key), `get()`, `update()`, `close()`, `restore()` |
84
+ | `workspaceKeys` | `create(workspaceId, body)`: mint a workspace key; the secret is in that answer only |
85
+ | `webhooks` | The organization's endpoints (events from every workspace, each with `workspace_id` and `external_id`): `list()`, `listAll()`, `create()`, `get()`, `update()`, `delete()`, `rotateSecret()`, `test()`, `listDeliveries()` (needs `organizations:write`), `listAllDeliveries()`, `replayDelivery()`, `flush()`, `verify()` |
86
+ | `usage` | `list({ period })`, `listAll()`: usage per workspace for its billing period |
87
+ | `planQuotes` | Change a workspace's plan: `create()` prices it, `get()`, `confirm()` applies and charges it (takes an idempotency key) |
88
+ | `sharedPlan` | The organization's shared plan: `get()`, `listWorkspaces()`, `addWorkspace()`, `updateWorkspace()` (its cap), `removeWorkspace()` (adding and removing take an idempotency key) |
89
+
90
+ Each client takes one kind of key: the organization client only calls
91
+ `/organizations/{id}/…` routes, and the API answers `401` to an organization
92
+ key on any other route. An Owner or Admin makes the key in the dashboard under
93
+ Organization → API.
94
+
50
95
  ## Client surface
51
96
 
52
97
  | Accessor | Covers |
53
98
  | --- | --- |
54
- | `email` | Send, batch, list, get, update, stats, inbound (`received*`) |
99
+ | `email` | Send, batch, list, get, update, stats, one email's delivery events (`listEvents()`), inbound (`received*`; the original `.eml` with `receivedRaw()`), retry a failed email (`retry()`, takes an idempotency key), batches (`listBatches()`, `getBatch()`, `cancelBatch()`) |
55
100
  | `email.topics` | Topics + contact topic prefs |
56
- | `email.campaigns` | Draft, schedule, send, pause/resume |
57
- | `email.templates` | Template CRUD |
58
- | `email.domains` | Domains + verify |
59
- | `contacts` | CRUD, import jobs |
101
+ | `email.campaigns` | Draft, schedule, send, pause/resume, results (`stats()`, `listStats()`), who a send would reach (`listRecipients()`), quality-pause recovery (`listAffected()`, `removeAffected()`, `requestReview()`) |
102
+ | `email.templates` | Template CRUD, `duplicate()`, add from the gallery (`fromLibrary()`), what uses it (`usage()`), history (`listVersions()`, `restoreVersion()`), render it without sending (`render()`, which lists `missing_variables`) |
103
+ | `email.domains` | Domains + verify, `diagnose()`, saved From addresses (`listSenders()`, `createSender()`, `getSender()`, `updateSender()`, `deleteSender()`) |
104
+ | `email.threads` | Inbox conversations: `list()` (`q`; page with `next_cursor`), `get()`, `delete()`, `reply()` (reply, reply all or forward; takes an idempotency key) |
105
+ | `sms` | Send, get, list, make the sender of a received text a contact (`addContact()`, which needs `contacts:write`), `brands()`, a brand (`createBrand()`, which takes an idempotency key, `getBrand()`, `updateBrand()`; the writes need `sms:manage`), `numbers()`, one number (`getNumber()`), a toll-free verification carriers sent back (`resubmitNumber()`, takes an idempotency key), release a number (`releaseNumber()`, PERMANENT: its fee ends and it can't be had back; `{ force: true }` releases it although campaigns are scheduled on it or texts are queued through it; takes an idempotency key and needs `sms:manage`), a number's text-to-join keywords (`listJoinKeywords()`, `addJoinKeyword()`, `removeJoinKeyword()`; the writes need `sms:manage`), a brand's documents (`listBrandDocuments()`, `addBrandDocument()` with a `file_id` or `text` (takes an idempotency key), `getBrandDocument()`, `removeBrandDocument()`, `brandDocumentUrl()`, a 5-minute signed link), contact SMS consent, `requestSmsOptIn()` (reply-YES confirmation). Available on paid plans: on the free plan `send` returns a `403` with code `limit_reached`, while the reads keep working. |
106
+ | `sms.templates` | Template CRUD, what uses it (`usage()`), one test text to a simulator number or a verified number from `sms.testDestinations` (`testSend()`, billed like any text; takes an idempotency key) |
107
+ | `sms.messagingPrograms` | What a sender registration says your texts are for: `list()` (`{ archived: true }` includes archived ones), `create()` and `duplicate()` (each takes an idempotency key), `get()`, `update()`, `delete()` (archives). The writes need `sms:manage` |
108
+ | `sms.testDestinations` | Verified test numbers: `list()`, `delete()` (needs `sms:manage`). Adding and verifying one stays in the dashboard |
109
+ | `sms.consentSetups` | Where and how people opt in to your texts: `list()` |
110
+ | `sms.billing` | Recurring SMS charges: `listResources()` |
111
+ | `sms.registrations` | Carrier registrations and their review state: `list()`, `get()`, a 10DLC campaign carriers sent back (`resubmit()`), a failed number whose fee is committed (`requestNumber()`), take down a 10DLC setup with no number (`remove()`), archive an approved brand registration to register it again (`replace()`); the writes take an idempotency key and need `sms:manage` |
112
+ | `sms.quotes` | Buy carrier resources (register a 10DLC brand, vet it, register a campaign, order a number): `create()` prices the order and returns a single-use `confirm_token`; `confirm()` places it (takes an idempotency key; one is generated when you don't pass one). The confirm needs `sms:purchase`, which no key preset includes, and the owner's monthly cap for SMS purchases by API. Show the person the price first. Release a number with `sms.releaseNumber()` |
113
+ | `contacts` | CRUD, list filters, import jobs (start, cancel, retry), addresses, recent activity, the segments it is in (`listSegments()`; add or remove it with `segments.addMember()` / `segments.removeMember()`), export to CSV (`export()`, a background job) |
60
114
  | `contactFields` | Custom field definitions |
61
- | `segments` | Segments + membership |
62
- | `brandKits` | Brand kit |
63
- | `webhooks` | Endpoints + `verify()` |
64
- | `apiKeys` | API key management |
115
+ | `segments` | Segments + membership, opt a member in or out (`updateMember()`), who it reaches (`preview()`, and `previewFilter()` for an unsaved filter), the managed all-contacts segment (`allContacts()`) |
116
+ | `brandKits` | Brand Kit profiles: `list()`, `get()`, `create()`, `update()`, `delete()`, `reset()`, `setDefault()`, `addGraphic()`, and imports from a website or the brand's own words (`import()`, `getImport()`, `acceptImport()`, `cancelImport()`). The writes and starting, accepting or canceling an import need the `branding:write` capability, which no key preset grants |
117
+ | `libraryImages` | The image library templates embed (`/img/…` paths): `list()`, `listAll()`, `create()` (takes an idempotency key), `get()`, `update()`, `delete()` (`{ force: true }` deletes an image in use) |
118
+ | `files` | Files handed to the API for one purpose and used by `file_id` (a brand document, SMS opt-in evidence, an image): `list()` (`purpose` filters), `create()` (a `url`, base64 `data`, or an upload session; takes an idempotency key), `get()`, `delete()`, and `upload({ path or data, purpose, contentType })`, which sends up to 3 MB inline and a larger file through an upload session. A file expires 24 hours after it is created |
119
+ | `branding` | The email footer and unsubscribe page look: `get()`, `update()`, `setLogo()`, `removeLogo()`. The writes need the `branding:write` capability, which no key preset grants |
120
+ | `workspace` | Who is calling and what it may do (`whoami()`, any credential), the activity log (`listActivity()`, `listAllActivity()`; needs `activity:read`), and the workspace's name and image: `update()`, `setImage()`, `removeImage()`. Those three need `branding:write`. No key preset grants either capability |
121
+ | `webhooks` | Endpoints + `verify()`, the delivery log (`listDeliveries()`), replay one delivery (`replayDelivery()`), deliver the backlog (`flush()`) |
122
+ | `apiKeys` | `list()` and a key's last 24 hours (`usage()`), which need `apikeys:read` (on no key preset); `create()` and `delete()` need a dashboard session |
123
+ | `logs` | The API request log, newest first: `list()` (each call's method, path, status, duration, key and request id; never the IP or a body; kept 30 days). Filters: `status`, `api_key_id`, `method`, `path_prefix`, `request_id`, `created_after` / `created_before`. Needs `apikeys:read` (on no key preset) |
65
124
  | `suppressions` | Suppression list |
125
+ | `jobs` | Background jobs: `list()`, `get()`, `cancel()`, `retry()`, a finished job's file (`download()`) |
66
126
  | `usage` | Billing-period usage snapshot |
127
+ | `spendCaps` | `get()`, `update()`: the monthly spend cap on SMS purchases made with a key or an app and what it counted this month; `update()` needs `spend_caps:write`, which no key preset grants |
67
128
 
68
129
  ## Pagination
69
130
 
@@ -87,7 +148,7 @@ complaints are added automatically; you can also add your own:
87
148
  await unitpost.suppressions.create({ email: "bounced@example.com", reason: "manual" });
88
149
  await unitpost.suppressions.create({ emails: ["a@example.com", "b@example.com"] });
89
150
 
90
- // Look one up by id or email; list (optionally filter scope); un-suppress.
151
+ // Look one up by id or email; list your own; un-suppress.
91
152
  const { data } = await unitpost.suppressions.get("bounced@example.com");
92
153
  for await (const s of unitpost.suppressions.listAll()) console.log(s.email, s.reason);
93
154
  await unitpost.suppressions.delete("bounced@example.com");
@@ -112,12 +173,57 @@ const event = verifyWebhook({
112
173
  });
113
174
  ```
114
175
 
115
- You can also call it from the client (Resend-style alias):
176
+ You can also call it from the client:
116
177
 
117
178
  ```ts
118
179
  const event = unitpost.webhooks.verify({ payload: rawBody, secret, headers: req.headers });
119
180
  ```
120
181
 
182
+ ## Receive a text and answer it
183
+
184
+ US toll-free, 10DLC and Canadian numbers take replies (`two_way: true` on
185
+ `sms.numbers()`). Subscribe a webhook to `sms.received`, skip STOP and texts
186
+ Unitpost already answered, read the conversation with `participant`, and answer
187
+ without `from` so the reply leaves from the number they texted.
188
+
189
+ ```ts
190
+ import { Unitpost, verifyWebhook } from "unitpost";
191
+
192
+ const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
193
+
194
+ // Your webhook endpoint, subscribed to sms.received. Pass the RAW body.
195
+ export async function onWebhook(rawBody: string, headers: Record<string, string>) {
196
+ const event = verifyWebhook<{ type: string; data: SmsReceived }>({
197
+ payload: rawBody,
198
+ secret: process.env.UNITPOST_WEBHOOK_SECRET!, // whsec_…
199
+ headers,
200
+ });
201
+ if (event.type !== "sms.received") return;
202
+ const reply = event.data;
203
+ if (reply.keyword === "OPT_OUT" || reply.auto_replied) return; // STOP, or already answered
204
+
205
+ // The whole conversation with this person, both directions, newest first.
206
+ const { data: history } = await unitpost.sms.list({ participant: reply.from, limit: 20 });
207
+ const answer = await yourAgent(history?.data ?? [], reply.body ?? "");
208
+
209
+ // No `from`: the answer goes out from the number they texted.
210
+ await unitpost.sms.send({ to: reply.from, body: answer });
211
+ }
212
+
213
+ type SmsReceived = {
214
+ sms_id: string;
215
+ from: string;
216
+ to: string;
217
+ body: string | null; // empty when the reply carried no text
218
+ keyword: "OPT_OUT" | "OPT_IN" | "HELP" | null;
219
+ auto_replied: boolean;
220
+ in_reply_to: string | null;
221
+ contact_id: string | null;
222
+ received_at: string | null; // order a conversation by this
223
+ created_at: string | null;
224
+ };
225
+ ```
226
+
121
227
  ## Idempotency
122
228
 
123
229
  `email.send` and `email.batch` are safe to retry by default: if you don't pass
@@ -161,7 +267,8 @@ CI-gated, so the SDK never silently drifts from the API.
161
267
  | | |
162
268
  | --- | --- |
163
269
  | Docs + API reference | https://www.unitpost.com/docs |
164
- | Product / SMTP / MCP guides | https://www.unitpost.com/guides |
270
+ | Product guides | https://www.unitpost.com/guides |
271
+ | SMTP | https://www.unitpost.com/docs/smtp |
165
272
  | OpenAPI JSON | https://www.unitpost.com/api/v1/openapi.json |
166
273
  | LLM index | https://www.unitpost.com/llms.txt |
167
274
  | Dashboard / API keys | https://www.unitpost.com |
@@ -169,7 +276,7 @@ CI-gated, so the SDK never silently drifts from the API.
169
276
  | Template gallery | https://www.unitpost.com/templates/gallery |
170
277
  | Playground | https://www.unitpost.com/playground |
171
278
  | Migration Assistant | https://www.unitpost.com/migration |
172
- | MCP + Agent Skills | https://www.unitpost.com/guides#ai-mcp · https://www.unitpost.com/guides#ai-skills |
279
+ | MCP + Agent Skills | https://www.unitpost.com/docs/ai/mcp · https://www.unitpost.com/docs/ai/skills |
173
280
  | Support | support@unitpost.com |
174
281
 
175
282
  ## License