@pidgeon-ai/sdk 1.68.0 → 2.1.1
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 +42 -1060
- package/LICENSE +55 -21
- package/README.md +113 -188
- package/dist/auth.d.ts +115 -0
- package/dist/auth.js +150 -0
- package/dist/credential.d.ts +61 -0
- package/dist/credential.js +135 -0
- package/dist/index.d.ts +670 -13914
- package/dist/index.js +464 -2036
- package/dist/node.d.ts +137 -0
- package/dist/node.js +403 -0
- package/package.json +35 -41
- package/dist/index.cjs +0 -2239
- package/dist/index.cjs.map +0 -1
- package/dist/index.d.cts +0 -13967
- package/dist/index.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,1062 +1,44 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
## 1.
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
with
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
- `
|
|
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.1.1
|
|
4
|
+
|
|
5
|
+
- `calendar.create` and `calendar.update` take `attendees` and `sendInvites`,
|
|
6
|
+
and `calendar.remove` takes `{ sendInvites }`: the attendees get an
|
|
7
|
+
invitation, an update or a cancellation from the inbox. `CalendarEvent` has
|
|
8
|
+
`organizer`, `attendees` and, after a write that sent, `invites`.
|
|
9
|
+
|
|
10
|
+
## 2.1.0
|
|
11
|
+
|
|
12
|
+
All of Email, and webhooks. Additive: 2.0 code runs unchanged.
|
|
13
|
+
|
|
14
|
+
- `messages`: `list`, `get` (`body: 'clean'` for the Firewall's cleaned text),
|
|
15
|
+
`markSeen`, `await` (wait for mail), `search`; sending takes `attachmentIds`.
|
|
16
|
+
- `threads` (list, read, file, star, hand to a person, delete, labels),
|
|
17
|
+
`labels`, `contacts`, `attachments` (`upload`, which goes straight to
|
|
18
|
+
storage over 4 MB; `get`, a five-minute link), `calendar`, `domains` (mail
|
|
19
|
+
on your own domain), `appPasswords` (for mail apps), `storage()`,
|
|
20
|
+
`testInbound()` (with a test key), and `webhooks`.
|
|
21
|
+
- `inboxes.create` takes `domain`; `inboxes.holdSuspicious`.
|
|
22
|
+
- Types follow the API: an inbox's `kind` is `agent` or `events`, and it has
|
|
23
|
+
`hold_suspicious` (no `owner_id`).
|
|
24
|
+
|
|
25
|
+
## 2.0.0
|
|
26
|
+
|
|
27
|
+
For the new Pidgeon: Passport, Bouncer, Email and Auth. A new major version,
|
|
28
|
+
because nothing of 1.x carries over: 1.x spoke the old email API at
|
|
29
|
+
`/api/v1`, which is retired seven days after the switch. Stay on 1.68.0 until
|
|
30
|
+
you move.
|
|
31
|
+
|
|
32
|
+
- `Pidgeon`, the API client, grouped by product: `agents` (with `setUp`:
|
|
33
|
+
register, make the key here, publish it signed with itself), `verify` and
|
|
34
|
+
`report`, `inboxes`, `messages`, `drafts`, `rules`, `suppressions`, `sites`,
|
|
35
|
+
`mandates`, `events`, `pods`, and `request` for any `/v1` call. It takes an
|
|
36
|
+
API key or an OAuth access token (`getToken`, refreshed per request).
|
|
37
|
+
- Signing as an agent (Web Bot Auth, RFC 9421): `signedFetch`, `agentFromEnv`,
|
|
38
|
+
`generateAgentKey`, `signAgentRequest`, `verifyAgentRequest`.
|
|
39
|
+
- `@pidgeon-ai/sdk/auth`: Sign in with Pidgeon. `signInAsAgent`,
|
|
40
|
+
`verifyIdToken`, `verifyAgentSignIn`, `requestIdJag`.
|
|
41
|
+
- `@pidgeon-ai/sdk/node`: signing in from a terminal through Pidgeon's OAuth
|
|
42
|
+
server, and agent keys kept on this machine (`setUpAgent`, `addAgentKey`,
|
|
43
|
+
`agentFromKeyFile`). What the CLI and the MCP server share.
|
|
44
|
+
- `verifyWebhook` for webhook signatures.
|