@pidgeon-ai/sdk 1.41.1 → 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 CHANGED
@@ -7,6 +7,20 @@ 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
+
10
24
  ## 1.41.1 — a refusal for what a key read
11
25
 
12
26
  - A send can be refused `403 exfiltration_blocked`: it carries text an API
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
  */
@@ -493,6 +497,10 @@ type Message = {
493
497
  reply_text: string;
494
498
  is_read: boolean;
495
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;
496
504
  /**
497
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.
498
506
  */
@@ -626,7 +634,7 @@ type Message = {
626
634
  */
627
635
  firewall: {
628
636
  /**
629
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
630
638
  */
631
639
  verdict: 'clean' | 'suspicious';
632
640
  /**
@@ -742,6 +750,10 @@ type AwaitedMessage = {
742
750
  reply_text: string;
743
751
  is_read: boolean;
744
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;
745
757
  /**
746
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.
747
759
  */
@@ -875,7 +887,7 @@ type AwaitedMessage = {
875
887
  */
876
888
  firewall: {
877
889
  /**
878
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
879
891
  */
880
892
  verdict: 'clean' | 'suspicious';
881
893
  /**
@@ -942,7 +954,7 @@ type AwaitedMessage = {
942
954
  */
943
955
  cursor: string;
944
956
  /**
945
- * What matched and was not returned. A wait that times out with `spam` or `unauthenticated` above zero did not miss the message: it was held back.
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.
946
958
  */
947
959
  held_back: {
948
960
  /**
@@ -953,6 +965,10 @@ type AwaitedMessage = {
953
965
  * Messages that matched `from` but did not pass DMARC, so their From may be forged.
954
966
  */
955
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;
956
972
  /**
957
973
  * Their ids, spam first, for `GET /messages/{id}`.
958
974
  */
@@ -1820,6 +1836,10 @@ type MailboxChange = {
1820
1836
  is_starred?: boolean;
1821
1837
  is_draft?: boolean;
1822
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;
1823
1843
  has_attachments?: boolean;
1824
1844
  attachment_count?: number;
1825
1845
  message_count?: number;
@@ -1884,6 +1904,10 @@ type MessageListItem = {
1884
1904
  is_starred: boolean;
1885
1905
  is_draft: boolean;
1886
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;
1887
1911
  has_attachments: boolean;
1888
1912
  attachment_count: number;
1889
1913
  message_count: number;
@@ -2029,6 +2053,10 @@ type SearchHit = {
2029
2053
  is_starred: boolean;
2030
2054
  is_draft: boolean;
2031
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;
2032
2060
  has_attachments: boolean;
2033
2061
  attachment_count: number;
2034
2062
  message_count: number;
@@ -2131,6 +2159,10 @@ type PodCreated = {
2131
2159
  * Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
2132
2160
  */
2133
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;
2134
2166
  /**
2135
2167
  * Your own opaque grouping for this address. Never parsed here.
2136
2168
  */
@@ -2240,7 +2272,7 @@ type AttachmentText = {
2240
2272
  */
2241
2273
  firewall: {
2242
2274
  /**
2243
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
2244
2276
  */
2245
2277
  verdict: 'clean' | 'suspicious';
2246
2278
  /**
@@ -2772,6 +2804,10 @@ type IdentitiesUpdateData = {
2772
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.
2773
2805
  */
2774
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;
2775
2811
  /**
2776
2812
  * Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
2777
2813
  */
@@ -7538,7 +7574,7 @@ type WebhooksCreateData = {
7538
7574
  * The address this belongs to.
7539
7575
  */
7540
7576
  identity_id?: string | null;
7541
- 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'>;
7542
7578
  };
7543
7579
  headers?: {
7544
7580
  /**
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
  */
@@ -493,6 +497,10 @@ type Message = {
493
497
  reply_text: string;
494
498
  is_read: boolean;
495
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;
496
504
  /**
497
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.
498
506
  */
@@ -626,7 +634,7 @@ type Message = {
626
634
  */
627
635
  firewall: {
628
636
  /**
629
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
630
638
  */
631
639
  verdict: 'clean' | 'suspicious';
632
640
  /**
@@ -742,6 +750,10 @@ type AwaitedMessage = {
742
750
  reply_text: string;
743
751
  is_read: boolean;
744
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;
745
757
  /**
746
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.
747
759
  */
@@ -875,7 +887,7 @@ type AwaitedMessage = {
875
887
  */
876
888
  firewall: {
877
889
  /**
878
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
879
891
  */
880
892
  verdict: 'clean' | 'suspicious';
881
893
  /**
@@ -942,7 +954,7 @@ type AwaitedMessage = {
942
954
  */
943
955
  cursor: string;
944
956
  /**
945
- * What matched and was not returned. A wait that times out with `spam` or `unauthenticated` above zero did not miss the message: it was held back.
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.
946
958
  */
947
959
  held_back: {
948
960
  /**
@@ -953,6 +965,10 @@ type AwaitedMessage = {
953
965
  * Messages that matched `from` but did not pass DMARC, so their From may be forged.
954
966
  */
955
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;
956
972
  /**
957
973
  * Their ids, spam first, for `GET /messages/{id}`.
958
974
  */
@@ -1820,6 +1836,10 @@ type MailboxChange = {
1820
1836
  is_starred?: boolean;
1821
1837
  is_draft?: boolean;
1822
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;
1823
1843
  has_attachments?: boolean;
1824
1844
  attachment_count?: number;
1825
1845
  message_count?: number;
@@ -1884,6 +1904,10 @@ type MessageListItem = {
1884
1904
  is_starred: boolean;
1885
1905
  is_draft: boolean;
1886
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;
1887
1911
  has_attachments: boolean;
1888
1912
  attachment_count: number;
1889
1913
  message_count: number;
@@ -2029,6 +2053,10 @@ type SearchHit = {
2029
2053
  is_starred: boolean;
2030
2054
  is_draft: boolean;
2031
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;
2032
2060
  has_attachments: boolean;
2033
2061
  attachment_count: number;
2034
2062
  message_count: number;
@@ -2131,6 +2159,10 @@ type PodCreated = {
2131
2159
  * Who may write to it: open, or list (only senders with an inbox rule, on mail that passes DMARC).
2132
2160
  */
2133
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;
2134
2166
  /**
2135
2167
  * Your own opaque grouping for this address. Never parsed here.
2136
2168
  */
@@ -2240,7 +2272,7 @@ type AttachmentText = {
2240
2272
  */
2241
2273
  firewall: {
2242
2274
  /**
2243
- * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
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`.
2244
2276
  */
2245
2277
  verdict: 'clean' | 'suspicious';
2246
2278
  /**
@@ -2772,6 +2804,10 @@ type IdentitiesUpdateData = {
2772
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.
2773
2805
  */
2774
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;
2775
2811
  /**
2776
2812
  * Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
2777
2813
  */
@@ -7538,7 +7574,7 @@ type WebhooksCreateData = {
7538
7574
  * The address this belongs to.
7539
7575
  */
7540
7576
  identity_id?: string | null;
7541
- 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'>;
7542
7578
  };
7543
7579
  headers?: {
7544
7580
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pidgeon-ai/sdk",
3
- "version": "1.41.1",
3
+ "version": "1.42.0",
4
4
  "description": "Email inboxes for AI agents — TypeScript SDK for Pidgeon: create addresses, send, receive and reply.",
5
5
  "keywords": [
6
6
  "email",