@pidgeon-ai/sdk 1.37.0 → 1.39.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,33 @@ 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.39.0 — what happened to a send
11
+
12
+ - Every `Message` carries `delivery`: `state`, the worst any recipient has
13
+ reached (`queued` through `delivered`, `bounced` or `complained`),
14
+ `delivered_at`, and each recipient's `state`, `bounce_type` and
15
+ `diagnostic`. Null for mail that arrived and for a send nobody has
16
+ reported on yet. `/docs/test-mode` called it `delivery_state`; it is
17
+ `delivery.state`.
18
+ - `to`, `cc` and `bcc` take one address or several on `draftsCreate`,
19
+ `draftsUpdate`, `messagesReply`, `messagesReplyAll` and
20
+ `messagesForward`, as they did on `messagesSend`.
21
+ - `draftsUpdate` adds the uploads named in `attachment_ids`. It took them
22
+ and did nothing. A create refused for an upload that does not exist no
23
+ longer saves the draft first.
24
+ - `message.delivered`, `message.bounced`, `message.rejected` and
25
+ `message.complained`, and the calendar events an invitation makes, carry
26
+ `thread_id`.
27
+
28
+ ## 1.38.0 — a Gmail forward Google vouched for
29
+
30
+ `authentication` gains `arc`: `{ sealer: "google.com", dmarc: "pass" }` on a
31
+ message forwarded through Gmail or Workspace whose sender failed DMARC here
32
+ (it signs nothing, and SPF passed for Google, not for it), when Google's ARC
33
+ seal verified and recorded DMARC pass for the same domain as `From:`. Such a
34
+ message counts as authenticated for allow lists, sender rules and
35
+ `messagesAwait`'s `from`. Null otherwise. Additive.
36
+
10
37
  ## 1.37.0 — every endpoint keeps the API's promises
11
38
 
12
39
  - **Every write takes an `Idempotency-Key` header**, not only the sends and
package/dist/index.d.cts CHANGED
@@ -497,7 +497,7 @@ type Message = {
497
497
  [key: string]: string;
498
498
  };
499
499
  /**
500
- * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
500
+ * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`, or `arc` is set.
501
501
  */
502
502
  authentication: {
503
503
  spf: string | null;
@@ -507,6 +507,16 @@ type Message = {
507
507
  * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
508
508
  */
509
509
  signature: string | null;
510
+ /**
511
+ * Set when `dmarc` did not pass here, but the message was forwarded by a sealer Pidgeon trusts (Google, for a Gmail or Workspace forward), its ARC chain verified, and that sealer recorded DMARC pass for the `From:` domain. Null otherwise.
512
+ */
513
+ arc: {
514
+ /**
515
+ * The forwarder that sealed it, such as `google.com`.
516
+ */
517
+ sealer: string;
518
+ dmarc: 'pass';
519
+ } | null;
510
520
  };
511
521
  /**
512
522
  * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -553,6 +563,22 @@ type Message = {
553
563
  */
554
564
  downloadable: boolean;
555
565
  }>;
566
+ /**
567
+ * What happened to mail we sent, per recipient and overall. Null for mail that arrived, and for a send nobody has reported on yet. `message.delivered` and `message.bounced` say the same as events.
568
+ */
569
+ delivery: {
570
+ /**
571
+ * `queued`, `sent`, `delivered`, `deferred`, `rejected`, `bounced` or `complained`: the worst any recipient has reached, so one bounce shows through a delivery.
572
+ */
573
+ state: string;
574
+ delivered_at: string | null;
575
+ recipients: Array<{
576
+ address: string;
577
+ state: string;
578
+ bounce_type: string | null;
579
+ diagnostic: string | null;
580
+ }>;
581
+ } | null;
556
582
  /**
557
583
  * The calendar part this message carried, or null — the invitation, who was asked, and what they answered.
558
584
  */
@@ -717,7 +743,7 @@ type AwaitedMessage = {
717
743
  [key: string]: string;
718
744
  };
719
745
  /**
720
- * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
746
+ * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`, or `arc` is set.
721
747
  */
722
748
  authentication: {
723
749
  spf: string | null;
@@ -727,6 +753,16 @@ type AwaitedMessage = {
727
753
  * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
728
754
  */
729
755
  signature: string | null;
756
+ /**
757
+ * Set when `dmarc` did not pass here, but the message was forwarded by a sealer Pidgeon trusts (Google, for a Gmail or Workspace forward), its ARC chain verified, and that sealer recorded DMARC pass for the `From:` domain. Null otherwise.
758
+ */
759
+ arc: {
760
+ /**
761
+ * The forwarder that sealed it, such as `google.com`.
762
+ */
763
+ sealer: string;
764
+ dmarc: 'pass';
765
+ } | null;
730
766
  };
731
767
  /**
732
768
  * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -773,6 +809,22 @@ type AwaitedMessage = {
773
809
  */
774
810
  downloadable: boolean;
775
811
  }>;
812
+ /**
813
+ * What happened to mail we sent, per recipient and overall. Null for mail that arrived, and for a send nobody has reported on yet. `message.delivered` and `message.bounced` say the same as events.
814
+ */
815
+ delivery: {
816
+ /**
817
+ * `queued`, `sent`, `delivered`, `deferred`, `rejected`, `bounced` or `complained`: the worst any recipient has reached, so one bounce shows through a delivery.
818
+ */
819
+ state: string;
820
+ delivered_at: string | null;
821
+ recipients: Array<{
822
+ address: string;
823
+ state: string;
824
+ bounce_type: string | null;
825
+ diagnostic: string | null;
826
+ }>;
827
+ } | null;
776
828
  /**
777
829
  * The calendar part this message carried, or null — the invitation, who was asked, and what they answered.
778
830
  */
@@ -4751,15 +4803,15 @@ type MessagesReplyData = {
4751
4803
  /**
4752
4804
  * One address or several. A string is accepted for the single case.
4753
4805
  */
4754
- to?: Array<string>;
4806
+ to?: string | Array<string>;
4755
4807
  /**
4756
4808
  * Copied, and visible to everybody who receives the message.
4757
4809
  */
4758
- cc?: Array<string>;
4810
+ cc?: string | Array<string>;
4759
4811
  /**
4760
4812
  * Copied, and visible to nobody else.
4761
4813
  */
4762
- bcc?: Array<string>;
4814
+ bcc?: string | Array<string>;
4763
4815
  /**
4764
4816
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4765
4817
  */
@@ -4851,15 +4903,15 @@ type MessagesReplyAllData = {
4851
4903
  /**
4852
4904
  * One address or several. A string is accepted for the single case.
4853
4905
  */
4854
- to?: Array<string>;
4906
+ to?: string | Array<string>;
4855
4907
  /**
4856
4908
  * Copied, and visible to everybody who receives the message.
4857
4909
  */
4858
- cc?: Array<string>;
4910
+ cc?: string | Array<string>;
4859
4911
  /**
4860
4912
  * Copied, and visible to nobody else.
4861
4913
  */
4862
- bcc?: Array<string>;
4914
+ bcc?: string | Array<string>;
4863
4915
  /**
4864
4916
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4865
4917
  */
@@ -4951,15 +5003,15 @@ type MessagesForwardData = {
4951
5003
  /**
4952
5004
  * One address or several. A string is accepted for the single case.
4953
5005
  */
4954
- to?: Array<string>;
5006
+ to?: string | Array<string>;
4955
5007
  /**
4956
5008
  * Copied, and visible to everybody who receives the message.
4957
5009
  */
4958
- cc?: Array<string>;
5010
+ cc?: string | Array<string>;
4959
5011
  /**
4960
5012
  * Copied, and visible to nobody else.
4961
5013
  */
4962
- bcc?: Array<string>;
5014
+ bcc?: string | Array<string>;
4963
5015
  /**
4964
5016
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4965
5017
  */
@@ -8784,15 +8836,15 @@ type DraftsCreateData = {
8784
8836
  /**
8785
8837
  * One address or several. A string is accepted for the single case.
8786
8838
  */
8787
- to?: Array<string>;
8839
+ to?: string | Array<string>;
8788
8840
  /**
8789
8841
  * Copied, and visible to everybody who receives the message.
8790
8842
  */
8791
- cc?: Array<string>;
8843
+ cc?: string | Array<string>;
8792
8844
  /**
8793
8845
  * Copied, and visible to nobody else.
8794
8846
  */
8795
- bcc?: Array<string>;
8847
+ bcc?: string | Array<string>;
8796
8848
  /**
8797
8849
  * Left off a reply, where the thread already has one.
8798
8850
  */
@@ -9008,15 +9060,15 @@ type DraftsUpdateData = {
9008
9060
  /**
9009
9061
  * One address or several. A string is accepted for the single case.
9010
9062
  */
9011
- to?: Array<string>;
9063
+ to?: string | Array<string>;
9012
9064
  /**
9013
9065
  * Copied, and visible to everybody who receives the message.
9014
9066
  */
9015
- cc?: Array<string>;
9067
+ cc?: string | Array<string>;
9016
9068
  /**
9017
9069
  * Copied, and visible to nobody else.
9018
9070
  */
9019
- bcc?: Array<string>;
9071
+ bcc?: string | Array<string>;
9020
9072
  /**
9021
9073
  * Left off a reply, where the thread already has one.
9022
9074
  */
package/dist/index.d.ts CHANGED
@@ -497,7 +497,7 @@ type Message = {
497
497
  [key: string]: string;
498
498
  };
499
499
  /**
500
- * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
500
+ * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`, or `arc` is set.
501
501
  */
502
502
  authentication: {
503
503
  spf: string | null;
@@ -507,6 +507,16 @@ type Message = {
507
507
  * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
508
508
  */
509
509
  signature: string | null;
510
+ /**
511
+ * Set when `dmarc` did not pass here, but the message was forwarded by a sealer Pidgeon trusts (Google, for a Gmail or Workspace forward), its ARC chain verified, and that sealer recorded DMARC pass for the `From:` domain. Null otherwise.
512
+ */
513
+ arc: {
514
+ /**
515
+ * The forwarder that sealed it, such as `google.com`.
516
+ */
517
+ sealer: string;
518
+ dmarc: 'pass';
519
+ } | null;
510
520
  };
511
521
  /**
512
522
  * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -553,6 +563,22 @@ type Message = {
553
563
  */
554
564
  downloadable: boolean;
555
565
  }>;
566
+ /**
567
+ * What happened to mail we sent, per recipient and overall. Null for mail that arrived, and for a send nobody has reported on yet. `message.delivered` and `message.bounced` say the same as events.
568
+ */
569
+ delivery: {
570
+ /**
571
+ * `queued`, `sent`, `delivered`, `deferred`, `rejected`, `bounced` or `complained`: the worst any recipient has reached, so one bounce shows through a delivery.
572
+ */
573
+ state: string;
574
+ delivered_at: string | null;
575
+ recipients: Array<{
576
+ address: string;
577
+ state: string;
578
+ bounce_type: string | null;
579
+ diagnostic: string | null;
580
+ }>;
581
+ } | null;
556
582
  /**
557
583
  * The calendar part this message carried, or null — the invitation, who was asked, and what they answered.
558
584
  */
@@ -717,7 +743,7 @@ type AwaitedMessage = {
717
743
  [key: string]: string;
718
744
  };
719
745
  /**
720
- * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
746
+ * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`, or `arc` is set.
721
747
  */
722
748
  authentication: {
723
749
  spf: string | null;
@@ -727,6 +753,16 @@ type AwaitedMessage = {
727
753
  * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
728
754
  */
729
755
  signature: string | null;
756
+ /**
757
+ * Set when `dmarc` did not pass here, but the message was forwarded by a sealer Pidgeon trusts (Google, for a Gmail or Workspace forward), its ARC chain verified, and that sealer recorded DMARC pass for the `From:` domain. Null otherwise.
758
+ */
759
+ arc: {
760
+ /**
761
+ * The forwarder that sealed it, such as `google.com`.
762
+ */
763
+ sealer: string;
764
+ dmarc: 'pass';
765
+ } | null;
730
766
  };
731
767
  /**
732
768
  * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -773,6 +809,22 @@ type AwaitedMessage = {
773
809
  */
774
810
  downloadable: boolean;
775
811
  }>;
812
+ /**
813
+ * What happened to mail we sent, per recipient and overall. Null for mail that arrived, and for a send nobody has reported on yet. `message.delivered` and `message.bounced` say the same as events.
814
+ */
815
+ delivery: {
816
+ /**
817
+ * `queued`, `sent`, `delivered`, `deferred`, `rejected`, `bounced` or `complained`: the worst any recipient has reached, so one bounce shows through a delivery.
818
+ */
819
+ state: string;
820
+ delivered_at: string | null;
821
+ recipients: Array<{
822
+ address: string;
823
+ state: string;
824
+ bounce_type: string | null;
825
+ diagnostic: string | null;
826
+ }>;
827
+ } | null;
776
828
  /**
777
829
  * The calendar part this message carried, or null — the invitation, who was asked, and what they answered.
778
830
  */
@@ -4751,15 +4803,15 @@ type MessagesReplyData = {
4751
4803
  /**
4752
4804
  * One address or several. A string is accepted for the single case.
4753
4805
  */
4754
- to?: Array<string>;
4806
+ to?: string | Array<string>;
4755
4807
  /**
4756
4808
  * Copied, and visible to everybody who receives the message.
4757
4809
  */
4758
- cc?: Array<string>;
4810
+ cc?: string | Array<string>;
4759
4811
  /**
4760
4812
  * Copied, and visible to nobody else.
4761
4813
  */
4762
- bcc?: Array<string>;
4814
+ bcc?: string | Array<string>;
4763
4815
  /**
4764
4816
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4765
4817
  */
@@ -4851,15 +4903,15 @@ type MessagesReplyAllData = {
4851
4903
  /**
4852
4904
  * One address or several. A string is accepted for the single case.
4853
4905
  */
4854
- to?: Array<string>;
4906
+ to?: string | Array<string>;
4855
4907
  /**
4856
4908
  * Copied, and visible to everybody who receives the message.
4857
4909
  */
4858
- cc?: Array<string>;
4910
+ cc?: string | Array<string>;
4859
4911
  /**
4860
4912
  * Copied, and visible to nobody else.
4861
4913
  */
4862
- bcc?: Array<string>;
4914
+ bcc?: string | Array<string>;
4863
4915
  /**
4864
4916
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4865
4917
  */
@@ -4951,15 +5003,15 @@ type MessagesForwardData = {
4951
5003
  /**
4952
5004
  * One address or several. A string is accepted for the single case.
4953
5005
  */
4954
- to?: Array<string>;
5006
+ to?: string | Array<string>;
4955
5007
  /**
4956
5008
  * Copied, and visible to everybody who receives the message.
4957
5009
  */
4958
- cc?: Array<string>;
5010
+ cc?: string | Array<string>;
4959
5011
  /**
4960
5012
  * Copied, and visible to nobody else.
4961
5013
  */
4962
- bcc?: Array<string>;
5014
+ bcc?: string | Array<string>;
4963
5015
  /**
4964
5016
  * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
4965
5017
  */
@@ -8784,15 +8836,15 @@ type DraftsCreateData = {
8784
8836
  /**
8785
8837
  * One address or several. A string is accepted for the single case.
8786
8838
  */
8787
- to?: Array<string>;
8839
+ to?: string | Array<string>;
8788
8840
  /**
8789
8841
  * Copied, and visible to everybody who receives the message.
8790
8842
  */
8791
- cc?: Array<string>;
8843
+ cc?: string | Array<string>;
8792
8844
  /**
8793
8845
  * Copied, and visible to nobody else.
8794
8846
  */
8795
- bcc?: Array<string>;
8847
+ bcc?: string | Array<string>;
8796
8848
  /**
8797
8849
  * Left off a reply, where the thread already has one.
8798
8850
  */
@@ -9008,15 +9060,15 @@ type DraftsUpdateData = {
9008
9060
  /**
9009
9061
  * One address or several. A string is accepted for the single case.
9010
9062
  */
9011
- to?: Array<string>;
9063
+ to?: string | Array<string>;
9012
9064
  /**
9013
9065
  * Copied, and visible to everybody who receives the message.
9014
9066
  */
9015
- cc?: Array<string>;
9067
+ cc?: string | Array<string>;
9016
9068
  /**
9017
9069
  * Copied, and visible to nobody else.
9018
9070
  */
9019
- bcc?: Array<string>;
9071
+ bcc?: string | Array<string>;
9020
9072
  /**
9021
9073
  * Left off a reply, where the thread already has one.
9022
9074
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pidgeon-ai/sdk",
3
- "version": "1.37.0",
3
+ "version": "1.39.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",