@pidgeon-ai/sdk 1.67.4 → 2.0.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 CHANGED
@@ -1,1056 +1,22 @@
1
1
  # Changelog
2
2
 
3
- Versioned independently of the application. The API is `/v1`; this package
4
- is `1.x`. They are different contracts with different audiences, and tying
5
- the two would publish a release for every unrelated product deploy.
6
-
7
- Semver applies to **this package's own surface** — the exported names, the
8
- call shapes, the result shape — not to the API behind it.
9
-
10
- ## 1.67.4 — the button's figure is as tall as the S
11
-
12
- - No change to this package's surface. The Python package's
13
- `sign_in_button_html` draws the figure at Inter's cap height, top level
14
- with the capital S, as `@pidgeon-ai/sign-in` 0.2.1 does.
15
-
16
- ## 1.67.3 — a site lists the issuers it trusts
17
-
18
- - No change to this package's surface. The Python package's `PidgeonSignIn`
19
- takes `issuers`, a company's own issuers beside Pidgeon's, and
20
- `sign_in_with_pidgeon` signs in at the issuer that signed the agent's card
21
- when the site lists it, as `@pidgeon-ai/sign-in` and `@pidgeon-ai/id`
22
- 0.2.0 do.
23
-
24
- ## 1.67.2 — the button carries the symbol
25
-
26
- - No change to this package's surface. The Python package's
27
- `sign_in_button_html` draws Sign in with Pidgeon's symbol, the Pidgeon
28
- figure at the x-height before the label, as `@pidgeon-ai/sign-in` 0.1.2 does.
29
-
30
- ## 1.67.1 — an issuer the site names is never contacted
31
-
32
- - No change to this package's surface. The Python package's
33
- `sign_in_with_api_key` refuses a site that names another issuer before
34
- fetching anything from it, as `@pidgeon-ai/id` 0.1.1 does.
35
-
36
- ## 1.67.0 — one set of capabilities, two languages
37
-
38
- - `streamEvents` reconnects from its cursor when a connection is cut
39
- mid-response; it threw `TypeError: terminated` before, despite its promise
40
- that only `signal` ends the loop.
41
- - The Python package (`pidgeon`, same version) gains `pidgeon.identity`,
42
- `pidgeon.sign_in` and `pidgeon.stream`, the twins of `@pidgeon-ai/id`,
43
- `@pidgeon-ai/sign-in` and `streamEvents`. A test now fails the build when
44
- either language has a capability the other lacks.
45
-
46
- ## 1.66.1 — a retried approval is the same approval
47
-
48
- - `signInsApprove` takes an `Idempotency-Key`: a retry with the same key
49
- answers with the first callback instead of a second code.
50
-
51
- ## 1.66.0 — approving a sign-in
52
-
53
- - `signInsApprove`: an agent approves an app's Sign in with Pidgeon with its
54
- own key, and gets back the app's callback to open. The key must be able to
55
- send as the address.
56
-
57
- ## 1.65.0 — reply_to
58
-
59
- - `messagesSend` and `messagesCheck` take `reply_to`: where replies go when
60
- not to `from`. It must be one of your own addresses, or an address on a
61
- domain you have verified; anything else is refused with a 400.
62
-
63
- ## 1.64.0 — private pods
64
-
65
- - `private` on a pod. `podsCreate` and `podsUpdate` take it: `true` means
66
- the pod's mail is readable only with its own keys, not by the account's
67
- keys or people. Anyone who administers the pod may turn it on; only one of
68
- its own keys at `admin` turns it off, and `podsUpdate` now accepts a pod
69
- key for that.
70
-
71
- ## 1.63.0 — grants
72
-
73
- - `grantsTemplatesList`, `grantsTemplatesCreate`, `grantsTemplatesDelete`:
74
- what an account's agents may ask a person for.
75
- - `grantsCreate` asks a person (the answer carries `consent_url`) or grants
76
- as the organisation; `grantsList`, `grantsGet`, `grantsRevoke`; and the
77
- public `grantsStatus`.
78
- - `messagesSend` takes `grant_ids`, carried as `Post-Grant`.
79
- - `verifySender` takes `grants` and `subject`, and its answer gains
80
- `grants`: each one valid or not, with why.
81
-
82
- ## 1.62.0 — the shared domain, said plainly
83
-
84
- - `operator.shared` on `verifySender`'s answer: true for `pidgeon.email` and
85
- a company's name on it (`acme.pidgeon.email`), which anyone can get an
86
- address on. `operator.verified` is false there, and true only for a domain
87
- its owner proved.
88
- - `card.url` is now the card's page, for a person; `card.api_url` is the
89
- card as JSON with its signed JWS, which `card.url` was before.
90
-
91
- ## 1.61.0 — the card log
92
-
93
- - `logHead`, `logCheckpoint`, `logEntries`, `logProof` and
94
- `logConsistency`: the public card log, every agent card issued, changed or
95
- revoked, with signed checkpoints and RFC 9162 proofs. No key needed.
96
- - `logMonitorsList`, `logMonitorsCreate` and `logMonitorsDelete`: watch the
97
- log for a name or a domain, look-alikes included.
98
- - `card_log.matched`, a new event type a webhook can subscribe to.
99
- - `card.log` on `verifySender`'s answer: the card's inclusion proof.
100
-
101
- ## 1.60.0 — checking a signed request
102
-
103
- - `verifySender` takes `request` instead of `message`: an HTTP request an
104
- agent signed (HTTP Message Signatures, Web Bot Auth), as its method, URL,
105
- headers and body. The answer gains `signatures.request`. Signing is
106
- [`@pidgeon-ai/id`](https://www.npmjs.com/package/@pidgeon-ai/id).
107
-
108
- ## 1.59.1 — which addresses have a card
109
-
110
- - `cardsGet` and `identitiesCard` say it: every agent and service address,
111
- and a person's or a team's address once software has sent mail from it as
112
- an agent. No shape changed.
113
-
114
- ## 1.59.0 — who gets typed data
115
-
116
- - `recipients` on `messagesCheck`'s answer: each recipient once, with
117
- `network` (true for an agent or service address on Pidgeon that would get
118
- the message signed and verified, so send it typed `data`), `kind` and
119
- `on_behalf_of`. False for everyone else: write for a person.
120
-
121
- ## 1.58.0 — agent cards and the public verifier
122
-
123
- - `cardsGet` (`GET /cards/{id}`, no key) and `identitiesCard`
124
- (`GET /identities/{id}/card`): an agent or service address's signed agent
125
- card. `jws` is a compact JWS (EdDSA) to check against
126
- `<iss>/.well-known/post.json`; `card` is its payload, decoded.
127
- - `verifySender` (`POST /verify`, no key): send a raw message or its headers,
128
- get back whether an AI agent sent it, on whose behalf, and whether its
129
- signatures hold, as a `verdict` to act on.
130
-
131
- ## 1.57.0 — free time
132
-
133
- - `calendarFreeTime`: when several addresses are all free in a window, at
134
- least `duration_minutes` long, optionally only between `day_start` and
135
- `day_end` in a zone and on weekdays. Each slot comes with its wall times
136
- in that zone, and each address's busy blocks without titles.
137
- - `contactsList` takes `cursor` and pages through `next_cursor`, like every
138
- other list.
139
-
140
- ## 1.56.0 — contacts
141
-
142
- - `contactsList`, `contactsCreate`, `contactsGet`, `contactsUpdate`,
143
- `contactsDelete`, `contactsBlock` and `contactsUnblock`: the people and
144
- agents an address corresponds with, noted from the mail. Find one by part
145
- of a name or an address, keep notes on them, mute them until a date
146
- (`snoozed_until`), or send their mail to spam. A contact belongs to one
147
- address, and a key reaches only the contacts of addresses it holds.
148
-
149
- ## 1.55.1 — the new tagline
150
-
151
- - The package description now reads "Email inboxes for AI agents". No change
152
- to the surface.
153
-
154
- ## 1.55.0 — the visible AI line
155
-
156
- - `ai_line` on `Identity` and on `identitiesUpdate`: whether mail an agent
157
- sends from the address ends with one line a person can read, "Written by
158
- an AI agent for …. Check it: …", linking to the message's verify page. On
159
- by default, from 17 November 2026. Turn it off where the address's own
160
- footer already says so; the signed declaration headers are sent either
161
- way.
162
-
163
- ## 1.54.0 — referral months
164
-
165
- - New webhook event type `referral.rewarded`: a company that signed up
166
- through the workspace's referral link is up and running, and the workspace
167
- earned a month of Pro. The payload says which month of 12, how it was
168
- given (`credit`, `pro_month` or `manual`) and the sentence the Log shows.
169
-
170
- ## 1.53.0 — a record of every DNS change
171
-
172
- - New webhook event type `domain.dns_changed`: one event each time Pidgeon
173
- writes to a domain's DNS (with a provider token, or a Domain Connect
174
- request sent to the provider) and each time it undoes that. The payload
175
- names the records, the value replaced, and who pressed it.
176
-
177
- ## 1.52.0 — send later, from Pidgeon's side
178
-
179
- - `send_at` (ISO 8601 with an offset) on `messagesSend` and `messagesReply`:
180
- the message is queued on Pidgeon and sent at that time with no further
181
- call. The result is `status: "scheduled"` with `draft_id`, `send_at` and a
182
- `cancel` call (`DELETE /v1/drafts/{id}/schedule`). A forward cannot be
183
- scheduled.
184
- - An address that asks a person first now holds a scheduled send when it is
185
- scheduled, not when it falls due; approved before its time, it goes at
186
- `send_at`.
187
- - `thread_id` on a send result is nullable: a scheduled new message has no
188
- conversation until it goes. New fields `send_at` and `cancel` are null on
189
- every other result.
190
-
191
- ## 1.51.2 — the new description
192
-
193
- - The package description says "Email inboxes for your team and your AI
194
- agents". No change to any call or type.
195
-
196
- ## 1.51.1 — three new messages to one person, not one
197
-
198
- - `recipient_cooldown` (`429`) now refuses the fourth new message to the same
199
- person inside the address's `recipient_cooldown_minutes`, not the second. A
200
- verification code, a resend and a password reset all go. Replies are still
201
- never counted against it. No change to any call or type.
202
-
203
- ## 1.51.0 — a key can check what a message declared
204
-
205
- - `messagesRaw({ path: { id }, query: { headers: 'original' } })` returns only
206
- the original's header section: the agent declaration and the DKIM signature
207
- that covers it, checkable as /verify checks it. A key's plain `messagesRaw`
208
- is a rebuild carrying a canary token, which cannot verify. A 404 once the
209
- original is no longer kept.
210
-
211
- ## 1.50.0 — a loop stops at the second message, and an agent can ask first
212
-
213
- - `messagesCheck({ body })` takes the body `messagesSend` takes, plus
214
- `forward`, and runs every check a send makes without sending: it returns a
215
- `SendCheck` (`would_send`, `status`, the envelope) or the exact error the
216
- send would give. Nothing is written or counted.
217
- - `Identity.recipient_cooldown_minutes` (default 10, 0 is off, at most 1440),
218
- settable with `identitiesUpdate`. A send that is not a reply, to somebody the
219
- address wrote to inside it, is refused `429 recipient_cooldown` with
220
- `Retry-After`. Replies are exempt.
221
- - No send's result type changed.
222
-
223
- ## 1.49.0 — what stands between a key and sending
224
-
225
- - `agentSetup({ query: { identity_id } })` asks every check a send would
226
- make, without sending, and returns `steps` in order — each with `done`,
227
- `owner` (`agent` or `person`), `what` and `how` — plus `next`, the first not
228
- done, and `ready_to_send`. A `domain` step lists the DNS records still to
229
- publish; a `daily_limit` step says when sending frees up (`resets_at`).
230
- Without `identity_id` it answers for the address nearest to sending and
231
- lists the rest under `addresses`. It sees only the addresses the key reaches.
232
-
233
- ## 1.48.0 — an agent joins the inbox a person already has
234
-
235
- - `agentConnect({ body: { code, name } })` spends a setup code from the
236
- dashboard's Overview and returns `api_key` with `send` on that one address,
237
- plus `address` and `identity_id`. No account is created and no code is
238
- emailed. A code works once, for 10 minutes; every failure is the same
239
- `400`. The key shows under the person's API keys and is held for approval
240
- like any other.
241
-
242
- ## 1.47.0 — a code that beat the wait is not lost
243
-
244
- - `messagesAwait` with `after: "now"`, `has_code: "true"` and a `timeout`
245
- above 5 also returns a matching message that arrived up to 60 seconds before
246
- the call and that no key has read, with `looked_back: true` (a new optional
247
- field on `AwaitedMessage`). The cursor-first call (`timeout: 1`) is
248
- unchanged: it never returns an older code.
249
-
250
- ## 1.46.0 — a person's conversation is theirs, and new values do not break Python
251
-
252
- - A send with a key in a conversation a person has (it is `human` with an
253
- assignee, or in `human_review`) is refused `403 taken_over`: a reply, a
254
- forward, or sending a draft that answers it. So is `threadsUpdate` setting
255
- `owner_type` to anything but `human` while they have it. The person hands it
256
- back from the dashboard. Saving a draft there still works.
257
- - Python (`pidgeon` 1.46.0): every enum keeps a value it does not know as
258
- itself instead of raising `ValueError`, so a Firewall signal kind added
259
- later (`model_intent`) reads as that string. Known values are unchanged.
260
- - TypeScript needed no change for unknown values: its types are unions,
261
- checked at compile time only, so an unknown kind already passed through.
262
-
263
- ## 1.45.0 — an agent reads the PDF, the Word file and the spreadsheet
264
-
265
- - `attachmentsText` reads PDF (the text layer), `.docx` and `.xlsx` as well
266
- as text formats, up to 10 MB, screened like a message body.
267
- `AttachmentText.format` says how: `text`, `pdf`, `docx` or `xlsx`.
268
- - Text a document hides from a person (a hidden Word run, a hidden sheet,
269
- row or column) counts as `hidden_text`. Where the address holds suspicious
270
- mail, a flagged attachment holds its message and a key gets `403 held`.
271
-
272
- ## 1.44.0 — the original inside a forward
273
-
274
- - `Message.extracted.forwarded`: when a message is an inline forward (Gmail,
275
- Apple Mail or Outlook, in English or German), the original's sender, name,
276
- date, subject and text. `null` otherwise, and with `body=clean` when the
277
- Firewall found the message suspicious.
278
- - The `message.received` event carries `from_name`, `cc`, `owner_type` and
279
- `auth: { spf, dkim, dmarc }`. Event payloads are not typed by this package.
280
-
281
- ## 1.43.1 — forwards and raw reads
282
-
283
- - `messagesForward` from a key is refused `403 exfiltration_blocked` when a
284
- recipient is new to the conversation: not on any of its messages, not one
285
- of your addresses, and not named by an `allow` send rule.
286
- - `messagesRaw` gives a key the rebuilt message with a canary token in its
287
- text, never the archived original; `X-Pidgeon-Reconstructed` is `true`.
288
- Descriptions only: no type changed.
289
-
290
- ## 1.43.0 — a person approves the risky sends
291
-
292
- - Every send result carries `status`: `sent`, or `pending_approval` — nothing
293
- was sent, the message is a draft waiting for a person, `draft_id` names it
294
- and `approval` says why (`first_contact` or `risky_thread`) and when it
295
- expires (24 hours). Read `status` before treating a send as sent.
296
- - `draftsApproval` (`GET /drafts/{id}/approval`) says where a held send
297
- stands; `message_id` is set once it is approved and sent.
298
- - `Draft.approval`, and `Identity.send_approval` (`none` or `first_contact`),
299
- settable with `identitiesUpdate`.
300
- - Events `draft.approval_requested`, `draft.approved`, `draft.rejected` and
301
- `draft.expired`, carrying `draft_id`, `thread_id` and `reason`.
302
-
303
- ## 1.42.0 — suspicious mail is held for a person
304
-
305
- - `Message.is_held` and `MessageListItem.is_held`. A held message's content is
306
- empty to a key — `subject`, `text`, `html`, `headers`, `data`,
307
- `attachments` — and `firewall` keeps the verdict and each signal's `kind`
308
- and `where`. `messagesGet`, `messagesGetRaw`, `attachmentsGet` and
309
- `attachmentsGetText` on it answer `403` with `error.code: "held"`, and a
310
- reply or forward to it is refused the same way.
311
- - `Identity.hold_suspicious`, settable on `identitiesUpdate`. A key can turn it
312
- on, never off.
313
- - Two event types: `message.held` (instead of `message.received`, with ids,
314
- the verdict and signal kinds, never content) and `message.released`, when a
315
- person lets the agent read it.
316
-
317
- ## 1.41.1 — a refusal for what a key read
318
-
319
- - A send can be refused `403 exfiltration_blocked`: it carries text an API
320
- key read in another conversation, and the message names that
321
- conversation. Bodies read with a key carry an invisible canary token for
322
- this; a reply in the same conversation has it removed before sending.
323
- Descriptions only: no type changed.
324
-
325
- ## 1.41.0 — files larger than a request body
326
-
327
- - `attachmentsCreateUpload` takes `identity_id`, `filename`, `content_type`
328
- and `size`, and answers with `upload`: a signed URL to `PUT` the bytes to,
329
- the `headers` to send with them, and `expires_at` (15 minutes). The size and
330
- type are signed, so the store refuses anything else. Then
331
- `attachmentsCompleteUpload` makes the id sendable; a send naming it before
332
- then is a 409 `conflict`.
333
- - `attachmentsUpload` is unchanged, and capped at 4.5 MB a request by the
334
- platform whatever the plan allows — which is why the two above exist. Use
335
- it for small files.
336
-
337
- ## 1.40.0 — every key states its scope
338
-
339
- - `keysCreate` requires `access`, and takes `reaches_all` beside
340
- `identity_ids` and `pod_id`: one of the three is the key's reach. A key
341
- cannot ask for `reaches_all`; an owner chooses it in the dashboard.
342
- - `podsCreate`'s `key` requires `access`.
343
- - Both answers may carry `warnings` beside `data`. Until 26 November 2026 the
344
- API still takes a mint without `access` — the new key gets the calling
345
- key's level — and says so there; from that date it is a 400 with
346
- `field: "access"`. Code built against this version never sees it.
347
-
348
- ## 1.39.0 — what happened to a send
349
-
350
- - Every `Message` carries `delivery`: `state`, the worst any recipient has
351
- reached (`queued` through `delivered`, `bounced` or `complained`),
352
- `delivered_at`, and each recipient's `state`, `bounce_type` and
353
- `diagnostic`. Null for mail that arrived and for a send nobody has
354
- reported on yet. `/docs/test-mode` called it `delivery_state`; it is
355
- `delivery.state`.
356
- - `to`, `cc` and `bcc` take one address or several on `draftsCreate`,
357
- `draftsUpdate`, `messagesReply`, `messagesReplyAll` and
358
- `messagesForward`, as they did on `messagesSend`.
359
- - `draftsUpdate` adds the uploads named in `attachment_ids`. It took them
360
- and did nothing. A create refused for an upload that does not exist no
361
- longer saves the draft first.
362
- - `message.delivered`, `message.bounced`, `message.rejected` and
363
- `message.complained`, and the calendar events an invitation makes, carry
364
- `thread_id`.
365
-
366
- ## 1.38.0 — a Gmail forward Google vouched for
367
-
368
- `authentication` gains `arc`: `{ sealer: "google.com", dmarc: "pass" }` on a
369
- message forwarded through Gmail or Workspace whose sender failed DMARC here
370
- (it signs nothing, and SPF passed for Google, not for it), when Google's ARC
371
- seal verified and recorded DMARC pass for the same domain as `From:`. Such a
372
- message counts as authenticated for allow lists, sender rules and
373
- `messagesAwait`'s `from`. Null otherwise. Additive.
374
-
375
- ## 1.37.0 — every endpoint keeps the API's promises
376
-
377
- - **Every write takes an `Idempotency-Key` header**, not only the sends and
378
- the creates: every `PATCH`, `PUT` and `DELETE`, and the other `POST`s.
379
- Each declares the `409` (`idempotency_in_progress`,
380
- `idempotency_mismatch`) and the test-mode `504`. A retried delete replays
381
- "deleted" instead of answering `404`. Unauthenticated agent signup and
382
- `keysRotate` are the exceptions.
383
- - **Every list pages to the end.** `domainsList` and `webhooksList` honour
384
- the `limit` and `cursor` they always declared; `webhooksDeliveries`,
385
- `draftsList`, `calendarListEvents`, `calendarGetAgenda`,
386
- `calendarListEventInstances` and `messagesSearch` take `cursor` and answer
387
- `next_cursor`. Each used to stop at `limit` with `has_more: false`. A
388
- calendar window holding more than 1,000 events is a `400` naming
389
- `before`; search reads the 1,000 best matches.
390
- - `appPasswordsCreate` answers `AppPasswordCreated`, with the `username` and
391
- `password` it always returned. `password` and `WebhookCreated.secret` are
392
- `string | null`: null on an `Idempotency-Key` replay, because neither is
393
- stored. Check them before storing.
394
- - `MailboxChange` carries the listing row's fields, as the endpoint always
395
- sent them.
396
- - A `400` names the field you sent: an unknown key by its name, and in
397
- `snake_case` (`send_at`, not `sendAt`). Every `429` carries
398
- `X-RateLimit-Limit`, `-Remaining` and `-Reset` beside `Retry-After`.
399
-
400
- ## 1.36.0 — the mail a domain already receives
401
-
402
- `domainsCreate` answers `existing_mail`: who already receives mail for the
403
- domain, read from its MX — `{ provider, name, hosts }`, with `provider` one of
404
- `google`, `microsoft`, `zoho`, `fastmail`, `proton`, `icloud`, `godaddy` or
405
- `other` — or null when nothing does. When it is set and `inbound_enabled` is
406
- true, publishing the MX record stops that mail arriving at the provider. Send
407
- `inbound_enabled: false`, or add a subdomain such as `agents.` instead.
408
- Additive.
409
-
410
- ## 1.35.0 — a key says what it is, and minting is idempotent
411
-
412
- - `meGet` returns `key.test`, `key.rotated_at` and
413
- `key.previous_token_expires_at`. Read `key.test` rather than the token's
414
- prefix to tell a test key.
415
- - `keysCreate` takes an `Idempotency-Key` header. A replay returns the same
416
- key with `Idempotent-Replay: true` and `token: null`, so
417
- `ApiKeyCreated.token` is now `string | null`: check it before storing.
418
- - An idempotency `409` now has its own `error.code`:
419
- `idempotency_in_progress` (wait `Retry-After` seconds, then send the same
420
- request) or `idempotency_mismatch` (the key went with a different
421
- request). Both were `conflict`; code that matched `conflict` for these
422
- must match the new codes.
423
-
424
- ## 1.34.0 — a test key creates test addresses
425
-
426
- Every address carries `test`. `identitiesCreate` with a test key (at admin
427
- over the account or its pod) now creates a test address rather than
428
- answering `403`: outside your plan's counts, at most 100 at once, taking only
429
- test mail (a test send or `testInbound`), and deleted a day after it was
430
- made. A test key may delete one. Additive.
431
-
432
- ## 1.33.0 — failures on purpose, in test mode
433
-
434
- `messagesSend` now says that with a test key a send to `rejected@` (any
435
- domain) comes back in `rejected`, a send to `bounce@` bounces a few seconds
436
- later, and the `Pidgeon-Test-Fail` header causes a 429, a 503, a slow answer
437
- or a lost one. Every write that takes an `Idempotency-Key`, and
438
- `keysCreate` and `keysRotate`, declare the `504` (`test_dropped`) that
439
- `drop` answers, so the client returns it as an error. Additive.
440
-
441
- ## 1.32.0 — a thread pages to the end
442
-
443
- `messagesListInThread` takes `cursor` and answers `next_cursor`. It used to
444
- answer `has_more: true` with no cursor, so a thread longer than `limit` (at
445
- most 200) could not be read past its first page. Pass the `next_cursor` you
446
- were given until it is null. A bad `limit` or `cursor` is now refused naming
447
- that field rather than `thread_id`. Additive.
448
-
449
- ## 1.31.4 — one-click setup, described truly
450
-
451
- Descriptions only. `domainsGetSetupLink` said the `mail` template included MX
452
- — it never did; MX is `mx`, on its own — and that the URL was signed by the
453
- DNS provider, where it is signed with Pidgeon's key. `reason: provider` now
454
- also covers a provider that has not approved Pidgeon's template yet. No name,
455
- path or shape moves.
456
-
457
- ## 1.31.3 — take a cursor first
458
-
459
- Descriptions only. `messagesAwait` now says how to wait for mail you are
460
- about to cause: call with `after: 'now'` and `timeout: 1`, keep the
461
- `cursor`, submit the form or send, then wait with that cursor as `after`.
462
- No shape moves.
463
-
464
- ## 1.31.2 — the client names itself
465
-
466
- Outside a browser the default client now sends `User-Agent: @pidgeon-ai/sdk`
467
- on every request, so Pidgeon can tell an account made through the SDK from
468
- one made with a hand-written `fetch`. A header you set yourself still wins.
469
- In a browser nothing changes: the browser sets its own. The Python client
470
- does the same as `pidgeon-python/<version>`.
471
-
472
- ## 1.31.1 — inbox, address, folder
473
-
474
- Descriptions only. Where the docs said "mailbox" they now say inbox (what an
475
- agent or a person has), address (`name@domain`, which the API calls an
476
- identity) or folder. Every name stays: `mailboxes.list`, `/v1/mailboxes`,
477
- `identity_id`. No shape moves.
478
-
479
- ## 1.31.0 — `receive_policy`
480
-
481
- Every address carries `receive_policy`: `open` (anyone, the default) or
482
- `list`, which accepts only senders with an `inbox` receive rule on mail that
483
- passes DMARC and refuses everybody else before anything is stored.
484
- `identitiesUpdate` sets it; `identitiesReceiveRulesList` and
485
- `identitiesReceiveRulesCreate` return it beside the rules. Additive.
486
-
487
- ## 1.30.0 — `authentication.signature`
488
-
489
- A message carries `authentication.signature`: `pass` when it came from
490
- another Pidgeon address directly and its signed sender verified against the
491
- sending domain's key, null otherwise. Additive.
492
-
493
- ## 1.29.0 — The signed-sender records
494
-
495
- Every domain's DNS records (`domainsGet`, `domainsCreate`, `domainsVerify`)
496
- gain two optional ones: `signing`, a TXT at `_post`, and `signing_host`, a
497
- CNAME at `post`. With both connected, mail from the domain carries a
498
- signature receivers can check against the domain's published keys. Every
499
- record gains `optional`, true for these two; they have their own `status`
500
- and never count towards whether the domain is configured. Additive.
501
-
502
- ## 1.28.0 — DNS hosts for subdomains, and why a record is waiting
503
-
504
- Every DNS record (`domainsGet`, `domainsCreate`, `domainsVerify`) gains
505
- `zone`, `fqdn` and `host_relative`: for `agents.example.com` the DMARC record
506
- is `_dmarc.agents` in `example.com`, which is what Squarespace, GoDaddy and
507
- Namecheap ask for. `name` is unchanged. `state` says why `status` is what it
508
- is — `published` (correct in DNS, waiting on Amazon), `missing`,
509
- `wrong_value` or `wrong_name` — and `found_at` is where a misplaced record was
510
- found. For DKIM, `found` is now the CNAME read from DNS rather than Amazon's
511
- status word. Additive.
512
-
513
- ## 1.27.0 — a key that drafts and never sends
514
-
515
- `keysCreate` takes `access: 'draft'`, between `read` and `send`: the key
516
- reads, searches, labels, archives, trashes, updates and hands off threads,
517
- and creates, updates and deletes drafts. Every send, reply, forward, draft
518
- send, schedule, calendar write and app password answers `403`. `access` on a
519
- key, `me` and mailbox access can now be `'draft'`. Additive.
520
-
521
- ## 1.26.0 — provisioning and teardown by pod
522
-
523
- `podsCreate` takes `address` (the same fields as `identitiesCreate`) and `key`
524
- (`name`, `access`, `expires_at`, `test`), and makes the pod, that address in
525
- it and a pod key in one call, or none of them. It answers `PodCreated`: the
526
- pod with `address` and `key`, each null when not asked for. The key's `token`
527
- is there once; a replay with the same `Idempotency-Key` returns the same pod,
528
- address and key with `token: null`. `podsDelete` (`DELETE /pods/{id}`) revokes
529
- the pod's keys and deletes its addresses and all their mail, and needs
530
- `delete_addresses: 'true'` for a pod that holds any. `keysList` takes
531
- `pod_id`. Additive.
532
-
533
- ## 1.25.0 — a forged `from` is held back
534
-
535
- `messagesAwait` with `from` matches only mail that passed DMARC (or that
536
- Pidgeon delivered between its own addresses), because anybody can write a
537
- `From:`. A match that did not is counted in `held_back.unauthenticated`, and
538
- its id is in `held_back.message_ids`; `include_unauthenticated: 'true'`
539
- returns it. A behaviour change for a sender that publishes no DMARC record.
540
-
541
- ## 1.24.0 — test mode
542
-
543
- `keysCreate` takes `test: true` for a `pgn_test_` key: everything works, and
544
- nothing it sends leaves Pidgeon or counts against the plan. A test key's
545
- children are test keys. Every key, message and send answer (`messagesSend`,
546
- `messagesReply`, `messagesReplyAll`, `messagesForward`, `draftsSend`) has
547
- `test`. `testInbound` (`POST /test/inbound`) delivers a simulated message to
548
- one of a test key's addresses, optionally as a reply (`in_reply_to`). A test
549
- key gets `403` creating addresses, domains, pods or app passwords. Additive.
550
-
551
- ## 1.23.0 — rotating a key
552
-
553
- `keysRotate` (`POST /api-keys/{id}/rotate`) gives a key a new secret and
554
- keeps its id, so its scope, its ceiling, its expiry and every key it minted
555
- are unchanged and keep working. The old secret stops at once, or after
556
- `grace_period_seconds` (at most 86400). The answer carries the new `token`,
557
- once. Every key gains `rotated_at` and `previous_token_expires_at`. Additive.
558
-
559
- ## 1.22.0 — typed data, and the declared sender
560
-
561
- Every send — `messagesSend`, `messagesReply`, `messagesReplyAll`,
562
- `messagesForward`, and `draftsCreate` and `draftsUpdate` for a draft sent or
563
- scheduled later — takes an optional `data: { schema, body }`: `schema` is an
564
- http or https URL naming what `body` is, and `body` is up to 64 KB of JSON.
565
- It travels as its own part beside the text, which ordinary mail clients do
566
- not show, and comes back as `data` on the message, on a Pidgeon recipient's
567
- copy and on any received mail that carries one. It is never mixed into
568
- `text`, and the Firewall does not read it as prose.
569
-
570
- Every message has `sender: { address, kind, on_behalf_of }`. A message sent
571
- from Pidgeon declares `kind` (`person`, `agent` or `service`, from the
572
- address's type) and `on_behalf_of` (the workspace's name, which only an owner
573
- can change). Mail that arrived as ordinary email declared neither, and
574
- says `origin: "smtp"`; `authentication` is what is known about it.
575
- `message.sent` carries `sender` too. Additive; nothing narrows.
576
-
577
- ## 1.21.0 — every send takes a key, and receipts
578
-
579
- `Idempotency-Key` is a declared header on every operation that honours it,
580
- so each takes `headers: { 'Idempotency-Key': … }` typed rather than as a
581
- raw header. It is honoured now on every send: `messagesReply`,
582
- `messagesReplyAll`, `messagesForward`, `draftsSend`, `draftsSchedule`,
583
- `calendarCreateEvent`, `calendarUpdateEvent`, `calendarDeleteEvent`,
584
- `calendarRespondToEvent` and `messagesRespondToInvitation`, beside
585
- `messagesSend` and the creates that had it. The same key with the same
586
- request returns the first answer and sends nothing; with a different
587
- request, `409`. Reuse one key across your own retries of one send.
588
-
589
- Two event types, both receipts from a Pidgeon address you wrote to:
590
- `message.read` (its agent read the message through the API, the first
591
- time — only from an address with the new `readReceipts` capability, off by
592
- default) and `message.handed_off` (it handed the conversation to a person).
593
- Each carries `message_id`, `recipient`, `kind` and `at`, and is
594
- subscribable like any other. Additive; nothing narrows.
595
-
596
- ## 1.20.0 — a wait looks back before it waits
597
-
598
- `messagesAwait` with no `after` returns the newest matching message from
599
- the last two minutes before it starts waiting. An agent submits a form and
600
- then asks for the code, and a fast sender's code was already there: the
601
- wait started at "now" and timed out on it. `after` also takes `"now"`, the
602
- old start. A caller that looped without passing `cursor` back may now see a
603
- message twice; pass the cursor, as before.
604
-
605
- ## 1.19.2 — what `/raw` answers
606
-
607
- The description of `GET /messages/{id}/raw` said it 404s once the original
608
- has aged out. It does not: it answers a rebuild from the stored message,
609
- marked `X-Pidgeon-Reconstructed: true`, and received mail is the archived
610
- original until then. Wording only; no shape moves.
611
-
612
- ## 1.19.1 — the default wait is under a minute
613
-
614
- `GET /messages/await` waits 50 seconds when no `timeout` is given, down
615
- from 60. Clients that give up on a request at 60 seconds — the TypeScript
616
- Agents SDK, Claude Code's MCP client — failed the default wait exactly when
617
- no message came. An explicit `timeout` up to 280 behaves as before.
618
-
619
- ## 1.19.0 — every status is declared, and Python raises
620
-
621
- The contract declares every status a route can answer with, read off the
622
- code rather than written from memory: `400`, `403`, `409`, `500` and `503`
623
- on every operation beside the `401`, `404` and `429` it had, `402` where a
624
- plan can say no, and `410` on calendar events and `mailboxesChanges`. In
625
- this package that widens each operation's error type; no request or success
626
- shape changes, and `error` held every failure already.
627
-
628
- **The Python client raises.** A status from 400 up raises
629
- `pidgeon.errors.PidgeonError`, carrying `status_code`, `code`, `message`,
630
- `field` and `retry_after`, instead of returning `Error` for a declared status
631
- and `None` for any other. A call returns its success model or raises, so a
632
- refused send can no longer pass for a sent one. Code that checked
633
- `isinstance(result, Error)` sees the exception instead.
634
-
635
- **The CLI** (1.8.4) exits 1 on a refusal and prints `403 abuse_blocked: …`;
636
- it exited 2 with the sentence alone, as if the flags were wrong.
637
-
638
- ## 1.18.0 — the key you mint comes back with its token
639
-
640
- `POST /api-keys` is typed as `ApiKeyCreated`: the key plus its `token`,
641
- returned once and never again. The API always sent the token; the published
642
- type left it out, so `keysCreate` had no typed field for it and the Python
643
- client's `ApiKey` model dropped it.
644
-
645
- ## 1.17.0 — a hand-off says why
646
-
647
- `threadsUpdate` takes an optional `reason` (up to 500 characters): why the
648
- conversation is being handed over, shown to the person in their notification
649
- and carried on `thread.updated` and `thread.assigned`.
650
-
651
- ## 1.16.1 — a refused send says so
652
-
653
- The contract declares `400` and `403` on every send — `messagesSend`,
654
- `messagesReply`, `messagesReplyAll`, `messagesForward`, `draftsSend` — and
655
- `409` on `messagesSend`. No request or success shape changes. The Python
656
- client returned `None` for a `403` (a sending limit, a rule, the send
657
- policy) because the status was not in the document; it returns the `Error`
658
- now, so check for it before treating a send as done.
659
-
660
- ## 1.16.0 — an attachment as text
661
-
662
- `attachmentsText` (`GET /attachments/{id}/text`) returns a text attachment —
663
- CSV, log, JSON, calendar — as text, up to 5 MB and 200,000 characters, with
664
- a Pidgeon Firewall verdict judged with the message's sender. `body: 'clean'`
665
- returns the cleaned text. HTML, PDF, Office files and images are refused.
666
-
667
- ## 1.15.0 — a read says what it held back
668
-
669
- `GET /messages/await` returns `held_back`: matching messages that arrived
670
- and were filed as spam, by count and id, so a wait that times out on a code
671
- from a sender whose authentication failed no longer reads as "nothing came".
672
- `include_spam=true` returns such a message instead. The inbox page of
673
- `GET /mailboxes/{folder}` carries `held_back.spam`, the unread messages in
674
- Spam, because an inbox that looks empty may not be.
675
-
676
- ## 1.14.2 — the PyPI page is the Python README
677
-
678
- No change to the API or the exported surface. Released with the Python
679
- client, whose PyPI page is now its own README rather than a shorter copy.
680
-
681
- ## 1.14.1 — the README leads with the job
682
-
683
- No change to the API or the exported surface. The README opens with
684
- creating an address, sending, waiting for the answer and replying with
685
- `messagesReply`, and the package's description and keywords say what it is
686
- for: email inboxes for AI agents.
687
-
688
- ## 1.14.0 — clean bodies in a conversation
689
-
690
- `body=clean` on `GET /messages`, as on `GET /messages/{id}` and
691
- `/messages/await`: every message in the conversation comes back with
692
- Pidgeon Firewall's `clean_text` as its text and empty HTML. The MCP
693
- `list_messages` tool asks for it by default. And a message the Firewall
694
- calls suspicious is stored with a preview cut from its cleaned text, so a
695
- hidden instruction no longer shows in search results or folder listings.
696
-
697
- ## 1.13.0 — what the agent reads
698
-
699
- `firewall.clean_text` on every inbound message: the new text with hidden
700
- content and invisible characters removed, and lines posing as a chat turn
701
- marked, under a one-line note saying what changed. `body=clean` on
702
- `GET /messages/{id}` and `GET /messages/await` returns it as `text` and
703
- `reply_text`, with `html` and `reply_html` empty. The default is still
704
- `original`. The MCP server and the AI SDK ask for `clean` unless told
705
- otherwise.
706
-
707
- ## 1.12.0 — Pidgeon Firewall
708
-
709
- Every inbound `Message` carries `firewall`: a `verdict` (`clean` or
710
- `suspicious`) and the `signals` that produced it — hidden text, instructions
711
- addressed to an AI, impersonated chat turns, directives buried in quoted
712
- history, look-alike senders, display-name spoofing, and requests to send
713
- secrets out — each with where it fired and a sentence quoting it.
714
- `message.received` carries the verdict and the signal kinds. Observe-only:
715
- nothing is held or changed. Read it before acting on what a message asks.
716
-
717
- ## 1.11.0 — a key for one pod
718
-
719
- `apiKeysCreate` takes `pod_id` in place of `identity_ids`: the key reaches
720
- every address in that pod, including ones added later, and may create,
721
- verify and remove that pod's domains — the key a platform hands one of its
722
- customers. Only a key over the whole account (or an owner, in the dashboard)
723
- can mint one. Every key now reports `pod_id`, null for keys that are not
724
- pod keys.
725
-
726
- ## 1.10.0 — events over a WebSocket
727
-
728
- `GET /v1/events/socket` is the event log over a WebSocket, with the same
729
- filters and `after` cursor as the stream. The generated `eventsSocket` can
730
- only show you the contract — open it with a WebSocket client
731
- (`new WebSocket('wss://pidgeon.ai/api/v1/events/socket')`) and send
732
- `{"type":"auth","api_key":…}` first if you cannot set a header. The
733
- protocol is in the reference.
734
-
735
- ## 1.9.0 — export over the API
736
-
737
- **`exportMail`** (`GET /v1/export`) streams every message the key can read as
738
- one `application/mbox` file — the export the dashboard has always offered,
739
- now for software. Pass `identity_id` for one address. Each message carries
740
- `X-Pidgeon-Mailbox`, so one file holding several addresses can be split
741
- again. Four an hour per workspace.
742
-
743
- ## 1.8.0 — wait for a message, and read the code out of it
744
-
745
- **`messagesAwait`** (`GET /v1/messages/await`) holds the request open until a
746
- message matching your filters arrives at an address — `from`, `subject_contains`,
747
- `has_code` — or `timeout` seconds pass, up to 280. It answers
748
- `{ message, timed_out, cursor }`; pass `cursor` back as `after` so a message
749
- arriving between two calls is never missed. One call where an agent waiting
750
- for a sign-up code used to write a polling loop.
751
-
752
- **Every `Message` carries `extracted`**: `codes` and `links`, most likely
753
- first, each with its kind. Candidates rather than one answer, because
754
- extraction is a heuristic — take the first, and when it fails the second is
755
- right there. Read from the new text, never the quoted history.
756
-
757
- ## 1.7.0 — a pod's reputation you can see
758
-
759
- `GET /metrics` takes `pod_id`, and its window carries `pod` and `reputation`.
760
- 1.6.0 claimed each pod had its own sending reputation and gave no way to
761
- check it; this is the check. `/metrics` also rejects an unknown query
762
- parameter instead of ignoring it, so a caller passing a misspelt filter is
763
- told rather than answered for the whole account.
764
-
765
- ## 1.6.0 — a pod is a boundary now
766
-
767
- **No field changed.** What changed is what a pod means, and that is worth a
768
- release because 1.5.0's own description told you the opposite.
769
-
770
- **Each pod has its own sending reputation.** Bounces and complaints from one
771
- customer's mail are counted against that customer's pod and nothing else, so
772
- one bad tenant cannot degrade delivery for the rest. Mail from an address in
773
- a pod sends under that pod whichever domain it is on, so two pods sharing one
774
- domain are still separate.
775
-
776
- 1.5.0 said _"a pod carries no sending reputation of its own"_, which was true
777
- and is not. Leaving it would be the worse kind of stale documentation — a
778
- caller reading it would decline to use something they already have.
779
-
780
- A pod is still **not** a key scope. A key is a list of address ids, which is
781
- what makes its reach checkable.
782
-
783
- ## 1.5.0 — a container your customers live in
784
-
785
- **Additive.** Every account has exactly one pod already, every address is in
786
- it, and a caller who never mentions a pod cannot tell this release from the
787
- last one.
788
-
789
- **Added.** `podsList`, `podsCreate`, `podsGet`, `podsUpdate`, the `Pod` type,
790
- `pod_id` on an address, and `pod_id` as a filter on `identitiesList`.
791
-
792
- A **pod** holds addresses and domains: one of your customers, a client, or
793
- just test kept apart from production. It has a name and an optional
794
- `client_id` that is your own id for it, carried and never parsed.
795
-
796
- **It is organisational and not a boundary**, and the types say so because the
797
- risk in shipping the container before the isolation is a reader assuming the
798
- isolation. A pod carries no sending reputation of its own — one SES tenant
799
- per _account_, unchanged — and **a key is still a list of address ids**,
800
- never something scoped to a pod.
801
-
802
- **No delete.** The verb that destroys a container full of mailboxes is worth
803
- making somebody ask for, and nothing yet moves addresses between pods, so it
804
- would either refuse every non-empty pod or destroy mail.
805
-
806
- ## 1.4.0 — things the prose promised and the types did not have
807
-
808
- **Additive, and two corrections to descriptions that were wrong.**
809
-
810
- The rest of what a field test found on 15 October building a shared mailroom.
811
- Everything below was either returned and undeclared, or described in the
812
- documentation and absent from the product.
813
-
814
- **Added to `Message`.**
815
-
816
- - `headers`, which `skill.md` and the MCP `get_message` tool have both
817
- promised for months — "its body **and its headers**" — against a schema
818
- with no such property. It is a subset and the description says which:
819
- `message-id`, `in-reply-to`, `references`, `date`, `reply-to`,
820
- `return-path`, the four list and auto-reply headers, `x-mailer` and
821
- `x-priority`. The whole envelope is `GET /messages/{id}/raw`. The
822
- threading three are new to the kept set, because _will my reply land in
823
- the right conversation_ is the question people open this for and nothing
824
- answered it for mail between two Pidgeon addresses.
825
- - `authentication` — `spf`, `dkim`, `dmarc`. `/docs/rules` has said since it
826
- was written that if you need to be certain who sent something you should
827
- _"read the authentication results on the message rather than its `From:`"_.
828
- There were none in the contract: no such field anywhere. The columns have
829
- been written since inbound mail existed. **Null means not reported, not
830
- failed** — rendering an absent verdict as a failed one is worse than
831
- showing nothing.
832
- - `delivered_to` is the envelope recipient on every message. It was null
833
- unless routing had moved the mail, while `message.received` carried it
834
- every time, so the event and the read disagreed about the same message.
835
-
836
- **Added to `Thread`.** `folder`, `from`, `from_name`, `preview` and
837
- `has_attachments`, from the newest message. `GET /threads` is the only
838
- workspace-wide listing and a row could say which conversations exist without
839
- being able to draw one — so a merged inbox had to come from
840
- `GET /mailboxes/{folder}`, which takes one address and one folder. Three
841
- addresses and four folders is twelve calls for one screen, against a free
842
- plan's 120 requests a minute. It is one call now.
843
-
844
- **Added to `MailboxChange`.** `identity_id`, which was null on every row of
845
- the only endpoint whose first required parameter is the mailbox.
846
-
847
- **New error codes.** `blocked` and `not_permitted`, both `403`.
848
- `/docs/rules`: _"a refusal tells you which kind it was… an agent debugging a
849
- send needs to know which."_ Both answered `forbidden` and neither word
850
- appeared in the response, so the only way to tell was to match the sentence.
851
- The fix is different for each — remove a rule, or change the send policy —
852
- which is the whole reason to separate them.
853
-
854
- **Corrected.** Two descriptions that described something the API does not do:
855
-
856
- - `rejected` on a send is **what the provider would not accept at hand-off**,
857
- not a recipient your own rules forbid. That refuses the whole send with
858
- `403`, and nothing goes to anybody. The old sentence told callers to handle
859
- a partial send that never happens, and not to expect the exception they
860
- actually get.
861
- - `is_read` on `PATCH /messages/{id}`, and `read`/`unread` on
862
- `POST /messages/actions`, are declared refused for an API key. They always
863
- were — read state belongs to a person — but three surfaces advertised them
864
- with no hint, including the MCP tool, whose description argued for a
865
- capability it does not have to the one consumer that cannot check first.
866
-
867
- **Widened.** `colour` on a label now has to be one of the eight; the
868
- refusal's sentence is unchanged.
869
-
870
- ## 1.3.0 — a day of API that never reached a registry
871
-
872
- **Additive, and one fix that was a blocker.**
873
-
874
- 1.2.0 went out on 14 October and then the contract moved for a day without
875
- this number moving with it. A field test on 15 October installed the published
876
- package, called a search the live API had been accepting since the morning,
877
- and got a `TypeError` for an argument the contract no longer requires. It
878
- built what it needed with a hand-written HTTP client instead. Everything below
879
- had already shipped; none of it was installable.
880
-
881
- **Fixed.** `verifyWebhook` reads the signature headers whatever case the
882
- framework spells them in. The lookup was `headers[name] ?? headers[name
883
- .toLowerCase()]` and `name` is already a lowercase constant — so it read the
884
- same key twice, and a plain object keyed `X-Pidgeon-Signature` was rejected as
885
- unsigned. Every existing test passed, because they all hand it a `Headers` or
886
- a lowercase object and both are already normalised. The broken branch is
887
- reached by an object somebody built themselves, which is what API Gateway
888
- hands a Lambda. `pidgeon` on PyPI was always right about this.
889
-
890
- **Added.**
891
-
892
- - `meGet`. What a key is, what it may do, and how many addresses it reaches —
893
- the first call a credential can make about itself.
894
- - `eventsStream`'s endpoint is in the document. The client does not wrap SSE,
895
- because a generated client has nowhere to put a long-lived connection; the
896
- path, the cursor header and the event shape are typed so hand-rolling it is
897
- twenty lines rather than a reverse-engineering exercise.
898
- - `thread.created` is emitted and subscribable. It was declared, accepted by
899
- `POST /webhooks`, and had never once fired.
900
- - `from_self` on `message.received`. A workspace with several addresses sees
901
- its own outbound mail arrive at the others, genuinely inbound, with nothing
902
- to distinguish it from a stranger — so a handler written the obvious way
903
- answers its own reply. Check it before you reply.
904
- - Quota pacing on a refusal: `Retry-After` and `X-RateLimit-*-Day`, so a
905
- client refused a send can compute when it may try again instead of guessing
906
- a day.
907
-
908
- **Declared, having always been returned.** Three fields the API sends and the
909
- document did not mention, so the generated types dropped them and a caller had
910
- to cast to reach them:
911
-
912
- - `sync_cursor` on a folder listing. `GET /mailboxes/changes` documents
913
- `since` as "the `sync_cursor` from a listing" and no listing declared one,
914
- so the change feed was unreachable from a typed client without defeating
915
- its own types.
916
- - `folder` on a search hit, and `identity` beside `identity_id` — the address
917
- rather than the uuid, which is what the rest of the API already carries on a
918
- thread row, on an event and on `GET /messages/{id}`. A search is the one
919
- endpoint that spans mailboxes, so it was the one that most needed to name
920
- them and the only one that would not. A hit is now its own type,
921
- `SearchHit`, rather than a `MessageListItem` with two fields missing.
922
- - `colour` is the eight-value enum it has always been enforced as, not
923
- `string`. The palette existed only in the refusal, so the first call
924
- anybody writes fails — somebody who has written CSS passes a hex. The
925
- refusal was already good and is kept word for word.
926
-
927
- **Widened.** `messagesSearch` no longer requires `identity_id`. It searches
928
- every address the credential reaches, which is what it has always done on the
929
- server and what `skill.md` has always said; the document said "one mailbox at
930
- a time" in prose while declaring the parameter optional, and the generator
931
- followed the prose. `MessageListItem` carries `identity_id`, `to`,
932
- `counterparty` and `counterparty_name`, so a hit can be attributed to a
933
- mailbox without a second call.
934
-
935
- **Also.** `identitiesCreate` on the shared domain, a 404 that stopped
936
- pretending an address it had just listed did not exist, and `repository`
937
- fields that resolve — all four packages pointed at a private repository that
938
- 404s for everybody who installs one.
939
-
940
- ## 1.2.0 — the document says what its fields mean
941
-
942
- **Additive, and a correction.**
943
-
944
- **Added.** Every request field that means one thing everywhere now carries a
945
- description, so the types say what `from`, `to`, `attachment_ids` and twenty
946
- others are for — 0 of 136 had one before.
947
-
948
- **Corrected.** `messagesSend` is typed `Sent` at `202`, which is what the API
949
- has always answered. It was declared `Message` at `201`, a response that never
950
- arrives — so a caller reading `data.subject` off a send got `undefined`, and
951
- `send` and `reply` appeared to disagree about their shape when they never did.
952
- Minor rather than major because nothing could have depended on a status code
953
- the server does not send.
954
-
955
- ## 1.1.0 — the domain an address is on
956
-
957
- Additive. Nothing here changes a call that already works.
958
-
959
- **Added**
960
-
961
- - `Identity.domain_id`. Every address now says which domain it is on, not
962
- only its name. This exists because the id was otherwise unlearnable: an
963
- account whose only domain is the shared one gets `[]` from `GET /domains`,
964
- correctly — that endpoint lists what a workspace _owns_ — and `domain_id`
965
- is what `identitiesCreate` requires. A customer building against production
966
- read the uuid out of the database to get past it.
967
- - `identitiesCreate` takes `domain` (a name) or `address` (a whole one) in
968
- place of `domain_id`. Pass exactly one. `address` also supplies the local
969
- part, which is the form `skills/pidgeon/SKILL.md` has documented since it
970
- was written.
971
- - `threadsList` takes `identity_id`, `status`, `owner_type` and
972
- `assignee_id`. The API has honoured all four since it was written and the
973
- contract declared none of them, so no generated client could offer them.
974
- `assignee_id` takes a person's id or the literal `unassigned`.
975
-
976
- ## 1.0.0 — one name per operation, generated
977
-
978
- **Published without an entry here**, which is how a changelog stops being
979
- read. Recorded after the fact, on 13 October, when a customer found the
980
- package README describing a class the package does not export.
981
-
982
- **Breaking.** The hand-written client is gone. There is no `Pidgeon` class
983
- and no `PidgeonError`: the package is generated from `openapi.json`, one
984
- function per operation named for its tag — `messagesSend`, `messagesGet`,
985
- `threadsUpdate` — sharing one client you configure at startup with
986
- `client.setConfig`. A call resolves to `{ data, error }` rather than
987
- throwing, or pass `throwOnError: true`.
988
-
989
- Both clients are generated from the same document, so an operation has the
990
- same name in TypeScript and in Python. `decisions.md` §343 is the argument,
991
- including why the stutter in `messagesSend` is accepted.
992
-
993
- ## 0.2.0 — the mailbox, and the credentials to reach it
994
-
995
- A minor rather than a patch, because one signature changed. In `0.x` semver
996
- that is what a minor is for, and the alternative — leaving the old shape
997
- beside the new one — would have shipped two ways to search that disagree
998
- about what the second argument is.
999
-
1000
- **Breaking**
1001
-
1002
- - `messages.search(identityId, q, options)` is now
1003
- `messages.search(identityId, options)`, with `q` inside the options beside
1004
- six filters. Search takes more than words now, and a positional query in
1005
- front of an options bag would have been the only parameter in the client
1006
- that works that way.
1007
- - `messages.update` no longer accepts `is_read` from an API key — the field
1008
- is still in the type, is still readable, and the API refuses to set it.
1009
- Read state belongs to a person and a key is not one; it used to return
1010
- `200` and change nothing, which is worse. Archive the conversation, or
1011
- track what you have seen with `mailboxes.changes`.
1012
-
1013
- **New resources**
1014
-
1015
- - `mailboxes` — `list`, `list_folder`, `changes`, `empty_trash`. The folders
1016
- with their counts, one folder by keyset cursor, what changed since a marker,
1017
- and emptying the trash.
1018
- - `routing` — `list`, `create`, `update`, `delete`. Per-customer addresses,
1019
- delivered into an inbox you already have or into a webhook with no inbox
1020
- at all.
1021
- - `keys` — `list`, `create`, `revoke`. A key can mint a narrower key, and
1022
- revoking one revokes everything it minted.
1023
- - `appPasswords` — `list`, `create`, `revoke`. Working IMAP and SMTP
1024
- credentials for one address, which is how you hand a customer a mailbox
1025
- they can open in a mail client.
1026
- - `workspace.get` — which account this key is for, and the plan that sets its
1027
- limits.
1028
-
1029
- **New on what was already there**
1030
-
1031
- - `domains` gained `create`, `get`, `verify` and `delete`. `create` returns
1032
- the records to publish alongside the domain, because showing them to your
1033
- own customer is the one thing every caller does next.
1034
- - `webhooks` gained `update` (enable and disable), `deliveries` and `replay`.
1035
- - `attachments.upload`, and `html` and `attachment_ids` on `messages.send`.
1036
- - `messages.act`, `messages.undo`, `threads.update`.
1037
-
1038
- **New types** — `ApiKey`, `AppPassword`, `Delivery`, `DnsRecord`, `Mailbox`,
1039
- `MailboxChange`, `Member`, `MessageActionName`, `MessageListItem`,
1040
- `UploadedAttachment`, `Workspace`. `RoutingRule` gained `domain_id` and
1041
- `destination_id`, and its `match_type` documentation said `exact`, which was
1042
- never a value the API emits.
1043
-
1044
- ## 0.1.0
1045
-
1046
- First release.
1047
-
1048
- - `Pidgeon` — a typed client over `/v1`: `identities`, `messages`,
1049
- `attachments`, `threads`, `webhooks`, `events`, `domains`.
1050
- - `verifyWebhook` — the receiving half of the signature scheme, tested
1051
- against payloads signed by the server's own implementation.
1052
- - `PidgeonError` — one error class, carrying the API's `code`, HTTP
1053
- `status`, the offending `field` on a validation failure, and the request
1054
- id.
1055
- - ESM and CommonJS builds with per-condition type declarations. Zero
1056
- runtime dependencies; needs only `fetch` and `crypto.subtle`.
3
+ ## 2.0.0
4
+
5
+ For the new Pidgeon: Passport, Bouncer, Email and Auth. A new major version,
6
+ because nothing of 1.x carries over: 1.x spoke the old email API at
7
+ `/api/v1`, which is retired seven days after the switch. Stay on 1.68.0 until
8
+ you move.
9
+
10
+ - `Pidgeon`, the API client, grouped by product: `agents` (with `setUp`:
11
+ register, make the key here, publish it signed with itself), `verify` and
12
+ `report`, `inboxes`, `messages`, `drafts`, `rules`, `suppressions`, `sites`,
13
+ `mandates`, `events`, `pods`, and `request` for any `/v1` call. It takes an
14
+ API key or an OAuth access token (`getToken`, refreshed per request).
15
+ - Signing as an agent (Web Bot Auth, RFC 9421): `signedFetch`, `agentFromEnv`,
16
+ `generateAgentKey`, `signAgentRequest`, `verifyAgentRequest`.
17
+ - `@pidgeon-ai/sdk/auth`: Sign in with Pidgeon. `signInAsAgent`,
18
+ `verifyIdToken`, `verifyAgentSignIn`, `requestIdJag`.
19
+ - `@pidgeon-ai/sdk/node`: signing in from a terminal through Pidgeon's OAuth
20
+ server, and agent keys kept on this machine (`setUpAgent`, `addAgentKey`,
21
+ `agentFromKeyFile`). What the CLI and the MCP server share.
22
+ - `verifyWebhook` for webhook signatures.