@pidgeon-ai/sdk 1.41.0 → 1.42.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 +22 -0
- package/dist/index.d.cts +57 -15
- package/dist/index.d.ts +57 -15
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,28 @@ the two would publish a release for every unrelated product deploy.
|
|
|
7
7
|
Semver applies to **this package's own surface** — the exported names, the
|
|
8
8
|
call shapes, the result shape — not to the API behind it.
|
|
9
9
|
|
|
10
|
+
## 1.42.0 — suspicious mail is held for a person
|
|
11
|
+
|
|
12
|
+
- `Message.is_held` and `MessageListItem.is_held`. A held message's content is
|
|
13
|
+
empty to a key — `subject`, `text`, `html`, `headers`, `data`,
|
|
14
|
+
`attachments` — and `firewall` keeps the verdict and each signal's `kind`
|
|
15
|
+
and `where`. `messagesGet`, `messagesGetRaw`, `attachmentsGet` and
|
|
16
|
+
`attachmentsGetText` on it answer `403` with `error.code: "held"`, and a
|
|
17
|
+
reply or forward to it is refused the same way.
|
|
18
|
+
- `Identity.hold_suspicious`, settable on `identitiesUpdate`. A key can turn it
|
|
19
|
+
on, never off.
|
|
20
|
+
- Two event types: `message.held` (instead of `message.received`, with ids,
|
|
21
|
+
the verdict and signal kinds, never content) and `message.released`, when a
|
|
22
|
+
person lets the agent read it.
|
|
23
|
+
|
|
24
|
+
## 1.41.1 — a refusal for what a key read
|
|
25
|
+
|
|
26
|
+
- A send can be refused `403 exfiltration_blocked`: it carries text an API
|
|
27
|
+
key read in another conversation, and the message names that
|
|
28
|
+
conversation. Bodies read with a key carry an invisible canary token for
|
|
29
|
+
this; a reply in the same conversation has it removed before sending.
|
|
30
|
+
Descriptions only: no type changed.
|
|
31
|
+
|
|
10
32
|
## 1.41.0 — files larger than a request body
|
|
11
33
|
|
|
12
34
|
- `attachmentsCreateUpload` takes `identity_id`, `filename`, `content_type`
|
package/dist/index.d.cts
CHANGED
|
@@ -429,6 +429,10 @@ type Identity = {
|
|
|
429
429
|
* Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
|
|
430
430
|
*/
|
|
431
431
|
receive_policy: string;
|
|
432
|
+
/**
|
|
433
|
+
* Whether Pidgeon Firewall holds suspicious mail here for a person: stored, and unreadable with a key until a person releases it from the dashboard. On by default for workspaces made from 27 October 2026.
|
|
434
|
+
*/
|
|
435
|
+
hold_suspicious: boolean;
|
|
432
436
|
/**
|
|
433
437
|
* Your own opaque grouping for this address. Never parsed here.
|
|
434
438
|
*/
|
|
@@ -471,6 +475,9 @@ type Message = {
|
|
|
471
475
|
* The envelope recipient, which is not always in `to`.
|
|
472
476
|
*/
|
|
473
477
|
delivered_to: string | null;
|
|
478
|
+
/**
|
|
479
|
+
* Read with an API key, every body field carries an invisible canary token tied to this conversation. Quote it in a reply here and it is removed before sending; send it anywhere else and the send is refused `exfiltration_blocked`. See /docs/firewall.
|
|
480
|
+
*/
|
|
474
481
|
text: string | null;
|
|
475
482
|
/**
|
|
476
483
|
* Sanitised server-side: our policy travels with the content.
|
|
@@ -490,6 +497,10 @@ type Message = {
|
|
|
490
497
|
reply_text: string;
|
|
491
498
|
is_read: boolean;
|
|
492
499
|
is_spam: boolean;
|
|
500
|
+
/**
|
|
501
|
+
* Pidgeon Firewall held it for a person. To a key, every content field is empty — subject, text, html, headers, data, attachments — and `firewall` keeps the verdict and where each signal fired, without quotes. A person releases it from the dashboard, and `message.released` fires.
|
|
502
|
+
*/
|
|
503
|
+
is_held: boolean;
|
|
493
504
|
/**
|
|
494
505
|
* The headers we keep, lowercased: `message-id`, `in-reply-to`, `references`, `date`, `reply-to`, `return-path`, `list-id`, `list-unsubscribe`, `precedence`, `auto-submitted`, `x-auto-response-suppress`, `x-mailer` and `x-priority`. Not the whole envelope — that is `GET /messages/{id}/raw`. Empty when none were present.
|
|
495
506
|
*/
|
|
@@ -623,7 +634,7 @@ type Message = {
|
|
|
623
634
|
*/
|
|
624
635
|
firewall: {
|
|
625
636
|
/**
|
|
626
|
-
* `suspicious` when any signal fired.
|
|
637
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
627
638
|
*/
|
|
628
639
|
verdict: 'clean' | 'suspicious';
|
|
629
640
|
/**
|
|
@@ -717,6 +728,9 @@ type AwaitedMessage = {
|
|
|
717
728
|
* The envelope recipient, which is not always in `to`.
|
|
718
729
|
*/
|
|
719
730
|
delivered_to: string | null;
|
|
731
|
+
/**
|
|
732
|
+
* Read with an API key, every body field carries an invisible canary token tied to this conversation. Quote it in a reply here and it is removed before sending; send it anywhere else and the send is refused `exfiltration_blocked`. See /docs/firewall.
|
|
733
|
+
*/
|
|
720
734
|
text: string | null;
|
|
721
735
|
/**
|
|
722
736
|
* Sanitised server-side: our policy travels with the content.
|
|
@@ -736,6 +750,10 @@ type AwaitedMessage = {
|
|
|
736
750
|
reply_text: string;
|
|
737
751
|
is_read: boolean;
|
|
738
752
|
is_spam: boolean;
|
|
753
|
+
/**
|
|
754
|
+
* Pidgeon Firewall held it for a person. To a key, every content field is empty — subject, text, html, headers, data, attachments — and `firewall` keeps the verdict and where each signal fired, without quotes. A person releases it from the dashboard, and `message.released` fires.
|
|
755
|
+
*/
|
|
756
|
+
is_held: boolean;
|
|
739
757
|
/**
|
|
740
758
|
* The headers we keep, lowercased: `message-id`, `in-reply-to`, `references`, `date`, `reply-to`, `return-path`, `list-id`, `list-unsubscribe`, `precedence`, `auto-submitted`, `x-auto-response-suppress`, `x-mailer` and `x-priority`. Not the whole envelope — that is `GET /messages/{id}/raw`. Empty when none were present.
|
|
741
759
|
*/
|
|
@@ -869,7 +887,7 @@ type AwaitedMessage = {
|
|
|
869
887
|
*/
|
|
870
888
|
firewall: {
|
|
871
889
|
/**
|
|
872
|
-
* `suspicious` when any signal fired.
|
|
890
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
873
891
|
*/
|
|
874
892
|
verdict: 'clean' | 'suspicious';
|
|
875
893
|
/**
|
|
@@ -936,7 +954,7 @@ type AwaitedMessage = {
|
|
|
936
954
|
*/
|
|
937
955
|
cursor: string;
|
|
938
956
|
/**
|
|
939
|
-
* What matched and was not returned. A wait that times out with `spam` or `
|
|
957
|
+
* What matched and was not returned. A wait that times out with `spam`, `unauthenticated` or `held` above zero did not miss the message: it was held back.
|
|
940
958
|
*/
|
|
941
959
|
held_back: {
|
|
942
960
|
/**
|
|
@@ -947,6 +965,10 @@ type AwaitedMessage = {
|
|
|
947
965
|
* Messages that matched `from` but did not pass DMARC, so their From may be forged.
|
|
948
966
|
*/
|
|
949
967
|
unauthenticated: number;
|
|
968
|
+
/**
|
|
969
|
+
* Messages Pidgeon Firewall held for a person. Matched on `from` alone; returned by a later wait once a person releases them. Absent before 1.42.0.
|
|
970
|
+
*/
|
|
971
|
+
held?: number;
|
|
950
972
|
/**
|
|
951
973
|
* Their ids, spam first, for `GET /messages/{id}`.
|
|
952
974
|
*/
|
|
@@ -1814,6 +1836,10 @@ type MailboxChange = {
|
|
|
1814
1836
|
is_starred?: boolean;
|
|
1815
1837
|
is_draft?: boolean;
|
|
1816
1838
|
is_spam?: boolean;
|
|
1839
|
+
/**
|
|
1840
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
1841
|
+
*/
|
|
1842
|
+
is_held?: boolean;
|
|
1817
1843
|
has_attachments?: boolean;
|
|
1818
1844
|
attachment_count?: number;
|
|
1819
1845
|
message_count?: number;
|
|
@@ -1878,6 +1904,10 @@ type MessageListItem = {
|
|
|
1878
1904
|
is_starred: boolean;
|
|
1879
1905
|
is_draft: boolean;
|
|
1880
1906
|
is_spam: boolean;
|
|
1907
|
+
/**
|
|
1908
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
1909
|
+
*/
|
|
1910
|
+
is_held: boolean;
|
|
1881
1911
|
has_attachments: boolean;
|
|
1882
1912
|
attachment_count: number;
|
|
1883
1913
|
message_count: number;
|
|
@@ -2023,6 +2053,10 @@ type SearchHit = {
|
|
|
2023
2053
|
is_starred: boolean;
|
|
2024
2054
|
is_draft: boolean;
|
|
2025
2055
|
is_spam: boolean;
|
|
2056
|
+
/**
|
|
2057
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
2058
|
+
*/
|
|
2059
|
+
is_held: boolean;
|
|
2026
2060
|
has_attachments: boolean;
|
|
2027
2061
|
attachment_count: number;
|
|
2028
2062
|
message_count: number;
|
|
@@ -2125,6 +2159,10 @@ type PodCreated = {
|
|
|
2125
2159
|
* Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
|
|
2126
2160
|
*/
|
|
2127
2161
|
receive_policy: string;
|
|
2162
|
+
/**
|
|
2163
|
+
* Whether Pidgeon Firewall holds suspicious mail here for a person: stored, and unreadable with a key until a person releases it from the dashboard. On by default for workspaces made from 27 October 2026.
|
|
2164
|
+
*/
|
|
2165
|
+
hold_suspicious: boolean;
|
|
2128
2166
|
/**
|
|
2129
2167
|
* Your own opaque grouping for this address. Never parsed here.
|
|
2130
2168
|
*/
|
|
@@ -2234,7 +2272,7 @@ type AttachmentText = {
|
|
|
2234
2272
|
*/
|
|
2235
2273
|
firewall: {
|
|
2236
2274
|
/**
|
|
2237
|
-
* `suspicious` when any signal fired.
|
|
2275
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
2238
2276
|
*/
|
|
2239
2277
|
verdict: 'clean' | 'suspicious';
|
|
2240
2278
|
/**
|
|
@@ -2766,6 +2804,10 @@ type IdentitiesUpdateData = {
|
|
|
2766
2804
|
* Who may write to it. `list` accepts only senders with an `inbox` receive rule whose mail passes DMARC, and refuses everybody else before anything is stored. A key with admin on the address may tighten it; loosening needs its owner.
|
|
2767
2805
|
*/
|
|
2768
2806
|
receive_policy?: 'open' | 'list';
|
|
2807
|
+
/**
|
|
2808
|
+
* Whether Pidgeon Firewall holds suspicious mail for a person. A key may turn it on; turning it off is a person’s, from the dashboard, because the agent it protects should not be able to.
|
|
2809
|
+
*/
|
|
2810
|
+
hold_suspicious?: boolean;
|
|
2769
2811
|
/**
|
|
2770
2812
|
* Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
|
|
2771
2813
|
*/
|
|
@@ -4372,7 +4414,7 @@ type MessagesSendErrors = {
|
|
|
4372
4414
|
*/
|
|
4373
4415
|
401: Error;
|
|
4374
4416
|
/**
|
|
4375
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4417
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4376
4418
|
*/
|
|
4377
4419
|
403: Error;
|
|
4378
4420
|
/**
|
|
@@ -4872,7 +4914,7 @@ type MessagesReplyErrors = {
|
|
|
4872
4914
|
*/
|
|
4873
4915
|
401: Error;
|
|
4874
4916
|
/**
|
|
4875
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4917
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4876
4918
|
*/
|
|
4877
4919
|
403: Error;
|
|
4878
4920
|
/**
|
|
@@ -4972,7 +5014,7 @@ type MessagesReplyAllErrors = {
|
|
|
4972
5014
|
*/
|
|
4973
5015
|
401: Error;
|
|
4974
5016
|
/**
|
|
4975
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5017
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4976
5018
|
*/
|
|
4977
5019
|
403: Error;
|
|
4978
5020
|
/**
|
|
@@ -5072,7 +5114,7 @@ type MessagesForwardErrors = {
|
|
|
5072
5114
|
*/
|
|
5073
5115
|
401: Error;
|
|
5074
5116
|
/**
|
|
5075
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5117
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5076
5118
|
*/
|
|
5077
5119
|
403: Error;
|
|
5078
5120
|
/**
|
|
@@ -7532,7 +7574,7 @@ type WebhooksCreateData = {
|
|
|
7532
7574
|
* The address this belongs to.
|
|
7533
7575
|
*/
|
|
7534
7576
|
identity_id?: string | null;
|
|
7535
|
-
event_types?: Array<'message.received' | 'message.sent' | 'message.delivered' | 'message.bounced' | 'message.rejected' | 'message.complained' | 'message.read' | 'message.handed_off' | 'message.spam' | 'message.invitation' | 'message.archived' | 'message.deleted' | 'calendar.event.created' | 'calendar.event.updated' | 'calendar.event.deleted' | 'calendar.event.starting' | 'calendar.event.ending' | 'calendar.event.responded' | 'thread.created' | 'thread.updated' | 'thread.assigned' | 'thread.unassigned' | 'identity.created' | 'identity.updated' | 'identity.suspended' | 'identity.transferred' | 'domain.verified'>;
|
|
7577
|
+
event_types?: Array<'message.received' | 'message.sent' | 'message.delivered' | 'message.bounced' | 'message.rejected' | 'message.complained' | 'message.read' | 'message.handed_off' | 'message.spam' | 'message.held' | 'message.released' | 'message.invitation' | 'message.archived' | 'message.deleted' | 'calendar.event.created' | 'calendar.event.updated' | 'calendar.event.deleted' | 'calendar.event.starting' | 'calendar.event.ending' | 'calendar.event.responded' | 'thread.created' | 'thread.updated' | 'thread.assigned' | 'thread.unassigned' | 'identity.created' | 'identity.updated' | 'identity.suspended' | 'identity.transferred' | 'domain.verified'>;
|
|
7536
7578
|
};
|
|
7537
7579
|
headers?: {
|
|
7538
7580
|
/**
|
|
@@ -8043,7 +8085,7 @@ type MessagesRespondToInvitationErrors = {
|
|
|
8043
8085
|
*/
|
|
8044
8086
|
401: Error;
|
|
8045
8087
|
/**
|
|
8046
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8088
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8047
8089
|
*/
|
|
8048
8090
|
403: Error;
|
|
8049
8091
|
/**
|
|
@@ -8322,7 +8364,7 @@ type CalendarCreateEventErrors = {
|
|
|
8322
8364
|
*/
|
|
8323
8365
|
401: Error;
|
|
8324
8366
|
/**
|
|
8325
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8367
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8326
8368
|
*/
|
|
8327
8369
|
403: Error;
|
|
8328
8370
|
/**
|
|
@@ -8393,7 +8435,7 @@ type CalendarRespondToEventErrors = {
|
|
|
8393
8435
|
*/
|
|
8394
8436
|
401: Error;
|
|
8395
8437
|
/**
|
|
8396
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8438
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8397
8439
|
*/
|
|
8398
8440
|
403: Error;
|
|
8399
8441
|
/**
|
|
@@ -8605,7 +8647,7 @@ type CalendarDeleteEventErrors = {
|
|
|
8605
8647
|
*/
|
|
8606
8648
|
401: Error;
|
|
8607
8649
|
/**
|
|
8608
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8650
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8609
8651
|
*/
|
|
8610
8652
|
403: Error;
|
|
8611
8653
|
/**
|
|
@@ -8763,7 +8805,7 @@ type CalendarUpdateEventErrors = {
|
|
|
8763
8805
|
*/
|
|
8764
8806
|
401: Error;
|
|
8765
8807
|
/**
|
|
8766
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8808
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8767
8809
|
*/
|
|
8768
8810
|
403: Error;
|
|
8769
8811
|
/**
|
|
@@ -9223,7 +9265,7 @@ type DraftsSendErrors = {
|
|
|
9223
9265
|
*/
|
|
9224
9266
|
401: Error;
|
|
9225
9267
|
/**
|
|
9226
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
9268
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
9227
9269
|
*/
|
|
9228
9270
|
403: Error;
|
|
9229
9271
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -429,6 +429,10 @@ type Identity = {
|
|
|
429
429
|
* Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
|
|
430
430
|
*/
|
|
431
431
|
receive_policy: string;
|
|
432
|
+
/**
|
|
433
|
+
* Whether Pidgeon Firewall holds suspicious mail here for a person: stored, and unreadable with a key until a person releases it from the dashboard. On by default for workspaces made from 27 October 2026.
|
|
434
|
+
*/
|
|
435
|
+
hold_suspicious: boolean;
|
|
432
436
|
/**
|
|
433
437
|
* Your own opaque grouping for this address. Never parsed here.
|
|
434
438
|
*/
|
|
@@ -471,6 +475,9 @@ type Message = {
|
|
|
471
475
|
* The envelope recipient, which is not always in `to`.
|
|
472
476
|
*/
|
|
473
477
|
delivered_to: string | null;
|
|
478
|
+
/**
|
|
479
|
+
* Read with an API key, every body field carries an invisible canary token tied to this conversation. Quote it in a reply here and it is removed before sending; send it anywhere else and the send is refused `exfiltration_blocked`. See /docs/firewall.
|
|
480
|
+
*/
|
|
474
481
|
text: string | null;
|
|
475
482
|
/**
|
|
476
483
|
* Sanitised server-side: our policy travels with the content.
|
|
@@ -490,6 +497,10 @@ type Message = {
|
|
|
490
497
|
reply_text: string;
|
|
491
498
|
is_read: boolean;
|
|
492
499
|
is_spam: boolean;
|
|
500
|
+
/**
|
|
501
|
+
* Pidgeon Firewall held it for a person. To a key, every content field is empty — subject, text, html, headers, data, attachments — and `firewall` keeps the verdict and where each signal fired, without quotes. A person releases it from the dashboard, and `message.released` fires.
|
|
502
|
+
*/
|
|
503
|
+
is_held: boolean;
|
|
493
504
|
/**
|
|
494
505
|
* The headers we keep, lowercased: `message-id`, `in-reply-to`, `references`, `date`, `reply-to`, `return-path`, `list-id`, `list-unsubscribe`, `precedence`, `auto-submitted`, `x-auto-response-suppress`, `x-mailer` and `x-priority`. Not the whole envelope — that is `GET /messages/{id}/raw`. Empty when none were present.
|
|
495
506
|
*/
|
|
@@ -623,7 +634,7 @@ type Message = {
|
|
|
623
634
|
*/
|
|
624
635
|
firewall: {
|
|
625
636
|
/**
|
|
626
|
-
* `suspicious` when any signal fired.
|
|
637
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
627
638
|
*/
|
|
628
639
|
verdict: 'clean' | 'suspicious';
|
|
629
640
|
/**
|
|
@@ -717,6 +728,9 @@ type AwaitedMessage = {
|
|
|
717
728
|
* The envelope recipient, which is not always in `to`.
|
|
718
729
|
*/
|
|
719
730
|
delivered_to: string | null;
|
|
731
|
+
/**
|
|
732
|
+
* Read with an API key, every body field carries an invisible canary token tied to this conversation. Quote it in a reply here and it is removed before sending; send it anywhere else and the send is refused `exfiltration_blocked`. See /docs/firewall.
|
|
733
|
+
*/
|
|
720
734
|
text: string | null;
|
|
721
735
|
/**
|
|
722
736
|
* Sanitised server-side: our policy travels with the content.
|
|
@@ -736,6 +750,10 @@ type AwaitedMessage = {
|
|
|
736
750
|
reply_text: string;
|
|
737
751
|
is_read: boolean;
|
|
738
752
|
is_spam: boolean;
|
|
753
|
+
/**
|
|
754
|
+
* Pidgeon Firewall held it for a person. To a key, every content field is empty — subject, text, html, headers, data, attachments — and `firewall` keeps the verdict and where each signal fired, without quotes. A person releases it from the dashboard, and `message.released` fires.
|
|
755
|
+
*/
|
|
756
|
+
is_held: boolean;
|
|
739
757
|
/**
|
|
740
758
|
* The headers we keep, lowercased: `message-id`, `in-reply-to`, `references`, `date`, `reply-to`, `return-path`, `list-id`, `list-unsubscribe`, `precedence`, `auto-submitted`, `x-auto-response-suppress`, `x-mailer` and `x-priority`. Not the whole envelope — that is `GET /messages/{id}/raw`. Empty when none were present.
|
|
741
759
|
*/
|
|
@@ -869,7 +887,7 @@ type AwaitedMessage = {
|
|
|
869
887
|
*/
|
|
870
888
|
firewall: {
|
|
871
889
|
/**
|
|
872
|
-
* `suspicious` when any signal fired.
|
|
890
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
873
891
|
*/
|
|
874
892
|
verdict: 'clean' | 'suspicious';
|
|
875
893
|
/**
|
|
@@ -936,7 +954,7 @@ type AwaitedMessage = {
|
|
|
936
954
|
*/
|
|
937
955
|
cursor: string;
|
|
938
956
|
/**
|
|
939
|
-
* What matched and was not returned. A wait that times out with `spam` or `
|
|
957
|
+
* What matched and was not returned. A wait that times out with `spam`, `unauthenticated` or `held` above zero did not miss the message: it was held back.
|
|
940
958
|
*/
|
|
941
959
|
held_back: {
|
|
942
960
|
/**
|
|
@@ -947,6 +965,10 @@ type AwaitedMessage = {
|
|
|
947
965
|
* Messages that matched `from` but did not pass DMARC, so their From may be forged.
|
|
948
966
|
*/
|
|
949
967
|
unauthenticated: number;
|
|
968
|
+
/**
|
|
969
|
+
* Messages Pidgeon Firewall held for a person. Matched on `from` alone; returned by a later wait once a person releases them. Absent before 1.42.0.
|
|
970
|
+
*/
|
|
971
|
+
held?: number;
|
|
950
972
|
/**
|
|
951
973
|
* Their ids, spam first, for `GET /messages/{id}`.
|
|
952
974
|
*/
|
|
@@ -1814,6 +1836,10 @@ type MailboxChange = {
|
|
|
1814
1836
|
is_starred?: boolean;
|
|
1815
1837
|
is_draft?: boolean;
|
|
1816
1838
|
is_spam?: boolean;
|
|
1839
|
+
/**
|
|
1840
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
1841
|
+
*/
|
|
1842
|
+
is_held?: boolean;
|
|
1817
1843
|
has_attachments?: boolean;
|
|
1818
1844
|
attachment_count?: number;
|
|
1819
1845
|
message_count?: number;
|
|
@@ -1878,6 +1904,10 @@ type MessageListItem = {
|
|
|
1878
1904
|
is_starred: boolean;
|
|
1879
1905
|
is_draft: boolean;
|
|
1880
1906
|
is_spam: boolean;
|
|
1907
|
+
/**
|
|
1908
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
1909
|
+
*/
|
|
1910
|
+
is_held: boolean;
|
|
1881
1911
|
has_attachments: boolean;
|
|
1882
1912
|
attachment_count: number;
|
|
1883
1913
|
message_count: number;
|
|
@@ -2023,6 +2053,10 @@ type SearchHit = {
|
|
|
2023
2053
|
is_starred: boolean;
|
|
2024
2054
|
is_draft: boolean;
|
|
2025
2055
|
is_spam: boolean;
|
|
2056
|
+
/**
|
|
2057
|
+
* Held by Pidgeon Firewall for a person. To a key, `subject`, `preview` and `from_name` are null until a person releases it.
|
|
2058
|
+
*/
|
|
2059
|
+
is_held: boolean;
|
|
2026
2060
|
has_attachments: boolean;
|
|
2027
2061
|
attachment_count: number;
|
|
2028
2062
|
message_count: number;
|
|
@@ -2125,6 +2159,10 @@ type PodCreated = {
|
|
|
2125
2159
|
* Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
|
|
2126
2160
|
*/
|
|
2127
2161
|
receive_policy: string;
|
|
2162
|
+
/**
|
|
2163
|
+
* Whether Pidgeon Firewall holds suspicious mail here for a person: stored, and unreadable with a key until a person releases it from the dashboard. On by default for workspaces made from 27 October 2026.
|
|
2164
|
+
*/
|
|
2165
|
+
hold_suspicious: boolean;
|
|
2128
2166
|
/**
|
|
2129
2167
|
* Your own opaque grouping for this address. Never parsed here.
|
|
2130
2168
|
*/
|
|
@@ -2234,7 +2272,7 @@ type AttachmentText = {
|
|
|
2234
2272
|
*/
|
|
2235
2273
|
firewall: {
|
|
2236
2274
|
/**
|
|
2237
|
-
* `suspicious` when any signal fired.
|
|
2275
|
+
* `suspicious` when any signal fired. At an address that holds suspicious mail (`hold_suspicious`) the message is also held for a person: `is_held`.
|
|
2238
2276
|
*/
|
|
2239
2277
|
verdict: 'clean' | 'suspicious';
|
|
2240
2278
|
/**
|
|
@@ -2766,6 +2804,10 @@ type IdentitiesUpdateData = {
|
|
|
2766
2804
|
* Who may write to it. `list` accepts only senders with an `inbox` receive rule whose mail passes DMARC, and refuses everybody else before anything is stored. A key with admin on the address may tighten it; loosening needs its owner.
|
|
2767
2805
|
*/
|
|
2768
2806
|
receive_policy?: 'open' | 'list';
|
|
2807
|
+
/**
|
|
2808
|
+
* Whether Pidgeon Firewall holds suspicious mail for a person. A key may turn it on; turning it off is a person’s, from the dashboard, because the agent it protects should not be able to.
|
|
2809
|
+
*/
|
|
2810
|
+
hold_suspicious?: boolean;
|
|
2769
2811
|
/**
|
|
2770
2812
|
* Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
|
|
2771
2813
|
*/
|
|
@@ -4372,7 +4414,7 @@ type MessagesSendErrors = {
|
|
|
4372
4414
|
*/
|
|
4373
4415
|
401: Error;
|
|
4374
4416
|
/**
|
|
4375
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4417
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4376
4418
|
*/
|
|
4377
4419
|
403: Error;
|
|
4378
4420
|
/**
|
|
@@ -4872,7 +4914,7 @@ type MessagesReplyErrors = {
|
|
|
4872
4914
|
*/
|
|
4873
4915
|
401: Error;
|
|
4874
4916
|
/**
|
|
4875
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4917
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4876
4918
|
*/
|
|
4877
4919
|
403: Error;
|
|
4878
4920
|
/**
|
|
@@ -4972,7 +5014,7 @@ type MessagesReplyAllErrors = {
|
|
|
4972
5014
|
*/
|
|
4973
5015
|
401: Error;
|
|
4974
5016
|
/**
|
|
4975
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5017
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
4976
5018
|
*/
|
|
4977
5019
|
403: Error;
|
|
4978
5020
|
/**
|
|
@@ -5072,7 +5114,7 @@ type MessagesForwardErrors = {
|
|
|
5072
5114
|
*/
|
|
5073
5115
|
401: Error;
|
|
5074
5116
|
/**
|
|
5075
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5117
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
5076
5118
|
*/
|
|
5077
5119
|
403: Error;
|
|
5078
5120
|
/**
|
|
@@ -7532,7 +7574,7 @@ type WebhooksCreateData = {
|
|
|
7532
7574
|
* The address this belongs to.
|
|
7533
7575
|
*/
|
|
7534
7576
|
identity_id?: string | null;
|
|
7535
|
-
event_types?: Array<'message.received' | 'message.sent' | 'message.delivered' | 'message.bounced' | 'message.rejected' | 'message.complained' | 'message.read' | 'message.handed_off' | 'message.spam' | 'message.invitation' | 'message.archived' | 'message.deleted' | 'calendar.event.created' | 'calendar.event.updated' | 'calendar.event.deleted' | 'calendar.event.starting' | 'calendar.event.ending' | 'calendar.event.responded' | 'thread.created' | 'thread.updated' | 'thread.assigned' | 'thread.unassigned' | 'identity.created' | 'identity.updated' | 'identity.suspended' | 'identity.transferred' | 'domain.verified'>;
|
|
7577
|
+
event_types?: Array<'message.received' | 'message.sent' | 'message.delivered' | 'message.bounced' | 'message.rejected' | 'message.complained' | 'message.read' | 'message.handed_off' | 'message.spam' | 'message.held' | 'message.released' | 'message.invitation' | 'message.archived' | 'message.deleted' | 'calendar.event.created' | 'calendar.event.updated' | 'calendar.event.deleted' | 'calendar.event.starting' | 'calendar.event.ending' | 'calendar.event.responded' | 'thread.created' | 'thread.updated' | 'thread.assigned' | 'thread.unassigned' | 'identity.created' | 'identity.updated' | 'identity.suspended' | 'identity.transferred' | 'domain.verified'>;
|
|
7536
7578
|
};
|
|
7537
7579
|
headers?: {
|
|
7538
7580
|
/**
|
|
@@ -8043,7 +8085,7 @@ type MessagesRespondToInvitationErrors = {
|
|
|
8043
8085
|
*/
|
|
8044
8086
|
401: Error;
|
|
8045
8087
|
/**
|
|
8046
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8088
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8047
8089
|
*/
|
|
8048
8090
|
403: Error;
|
|
8049
8091
|
/**
|
|
@@ -8322,7 +8364,7 @@ type CalendarCreateEventErrors = {
|
|
|
8322
8364
|
*/
|
|
8323
8365
|
401: Error;
|
|
8324
8366
|
/**
|
|
8325
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8367
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8326
8368
|
*/
|
|
8327
8369
|
403: Error;
|
|
8328
8370
|
/**
|
|
@@ -8393,7 +8435,7 @@ type CalendarRespondToEventErrors = {
|
|
|
8393
8435
|
*/
|
|
8394
8436
|
401: Error;
|
|
8395
8437
|
/**
|
|
8396
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8438
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8397
8439
|
*/
|
|
8398
8440
|
403: Error;
|
|
8399
8441
|
/**
|
|
@@ -8605,7 +8647,7 @@ type CalendarDeleteEventErrors = {
|
|
|
8605
8647
|
*/
|
|
8606
8648
|
401: Error;
|
|
8607
8649
|
/**
|
|
8608
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8650
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8609
8651
|
*/
|
|
8610
8652
|
403: Error;
|
|
8611
8653
|
/**
|
|
@@ -8763,7 +8805,7 @@ type CalendarUpdateEventErrors = {
|
|
|
8763
8805
|
*/
|
|
8764
8806
|
401: Error;
|
|
8765
8807
|
/**
|
|
8766
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8808
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
8767
8809
|
*/
|
|
8768
8810
|
403: Error;
|
|
8769
8811
|
/**
|
|
@@ -9223,7 +9265,7 @@ type DraftsSendErrors = {
|
|
|
9223
9265
|
*/
|
|
9224
9266
|
401: Error;
|
|
9225
9267
|
/**
|
|
9226
|
-
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
9268
|
+
* Refused, and nothing was sent to anybody. `error.code` says why: `blocked` (a rule), `not_permitted` (the send policy), `abuse_blocked` (a sending limit), `exfiltration_blocked` (it carries text a key read in another conversation; the message names it) or `forbidden` (the address is not one this key can send from, or is not active).
|
|
9227
9269
|
*/
|
|
9228
9270
|
403: Error;
|
|
9229
9271
|
/**
|