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