@pidgeon-ai/sdk 1.24.0 → 1.25.0

package/dist/index.d.cts

@@ -868,7 +868,7 @@ type AwaitedMessage = {
      */
     cursor: string;
     /**
-     * What matched and was not returned. A wait that times out with `spam` above zero did not miss the message: it was filed as spam.
+     * 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.
      */
     held_back: {
         /**
@@ -876,7 +876,11 @@ type AwaitedMessage = {
          */
         spam: number;
         /**
-         * Their ids, for `GET /messages/{id}`.
+         * Messages that matched `from` but did not pass DMARC, so their From may be forged.
+         */
+        unauthenticated: number;
+        /**
+         * Their ids, spam first, for `GET /messages/{id}`.
          */
         message_ids: Array<string>;
         /**
@@ -1625,7 +1629,7 @@ type ReceiveRules = {
     rules: Array<{
         id: string;
         /**
-         * reject refuses before the message is stored. spam, trash and archive file it. inbox means never classify this sender as spam.
+         * reject refuses before the message is stored. spam, trash and archive file it. inbox means never file this sender as spam, for mail that passes DMARC.
          */
         action: string;
         match_type: 'address' | 'domain';
@@ -3883,6 +3887,10 @@ type MessagesAwaitData = {
          * Also return a matching message filed as spam. Without it, one is counted in `held_back` instead, with its id.
          */
         include_spam?: 'true' | 'false';
+        /**
+         * With `from`, also return a match that did not pass DMARC, whose From may be forged. Without it, one is counted in `held_back.unauthenticated` instead, with its id.
+         */
+        include_unauthenticated?: 'true' | 'false';
         /**
          * Only messages that arrived after this: the `cursor` a previous call returned, or `now`. Without it, the wait first looks back 2 minutes and returns the newest matching message from then, so a code that beat you to the call is not missed.
          */
@@ -8708,7 +8716,7 @@ declare const identitiesReceiveRulesGet: <ThrowOnError extends boolean = false>(
  *
  * `value` is an address or a domain and the string says which: `billing@acme.com` matches one person, `acme.com` matches everybody there. **The more specific rule wins**, and an address’s own rule wins over a workspace-wide one. Adding **replaces** any rule already there for that value.
  *
- * `action` is `reject`, `spam`, `trash`, `archive` or `inbox`. **`reject` refuses before the message is stored** — no row, no thread, no storage charged and no webhook — which is what an address nobody will ever open wants. The other four file it, and `inbox` means *never classify this sender as spam*.
+ * `action` is `reject`, `spam`, `trash`, `archive` or `inbox`. **`reject` refuses before the message is stored** — no row, no thread, no storage charged and no webhook — which is what an address nobody will ever open wants. The other four file it, and `inbox` means *never file this sender as spam*. A rule takes a message out of spam only when it passed DMARC, because the rule matches a `From:` anybody can write.
  *
  * **It is not a security control.** The `From:` header is written by the sender, and anybody blocked can change it for the price of a new address. What this buys is not paying for mail from senders who have not bothered.
  */
@@ -8814,7 +8822,7 @@ declare const messagesUndo: <ThrowOnError extends boolean = false>(options: Opti
 /**
  * Wait for the next message
  *
- * Holds the request open until a message matching the filters arrives at the address, or `timeout` seconds pass — one call where you would otherwise poll. The message carries `extracted`: verification codes and links, most likely first. Without `after`, it first looks back 2 minutes and returns the newest matching message from then, because a code often lands before the call is made; narrow it with `from`, `subject_contains` or `has_code` so an earlier email is not taken for the one you want, or pass `after=now` to wait only for new mail. Pass the returned `cursor` as `after` on the next call so nothing arriving between calls is missed. Answers 200 with `message: null` and `timed_out: true` when nothing came. A matching message filed as spam is not returned unless you pass `include_spam=true`; it is counted in `held_back`, with its id, so a timeout never hides mail that arrived.
+ * Holds the request open until a message matching the filters arrives at the address, or `timeout` seconds pass — one call where you would otherwise poll. The message carries `extracted`: verification codes and links, most likely first. Without `after`, it first looks back 2 minutes and returns the newest matching message from then, because a code often lands before the call is made; narrow it with `from`, `subject_contains` or `has_code` so an earlier email is not taken for the one you want, or pass `after=now` to wait only for new mail. Pass the returned `cursor` as `after` on the next call so nothing arriving between calls is missed. Answers 200 with `message: null` and `timed_out: true` when nothing came. A matching message filed as spam is not returned unless you pass `include_spam=true`; it is counted in `held_back`, with its id, so a timeout never hides mail that arrived. A message matches `from` only when it passed DMARC, because anybody can write a `From:`; one that did not is counted in `held_back.unauthenticated`, and `include_unauthenticated=true` returns it.
  */
 declare const messagesAwait: <ThrowOnError extends boolean = false>(options: Options<MessagesAwaitData, ThrowOnError>) => RequestResult<MessagesAwaitResponses, MessagesAwaitErrors, ThrowOnError>;
 /**

package/dist/index.d.ts

@@ -868,7 +868,7 @@ type AwaitedMessage = {
      */
     cursor: string;
     /**
-     * What matched and was not returned. A wait that times out with `spam` above zero did not miss the message: it was filed as spam.
+     * 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.
      */
     held_back: {
         /**
@@ -876,7 +876,11 @@ type AwaitedMessage = {
          */
         spam: number;
         /**
-         * Their ids, for `GET /messages/{id}`.
+         * Messages that matched `from` but did not pass DMARC, so their From may be forged.
+         */
+        unauthenticated: number;
+        /**
+         * Their ids, spam first, for `GET /messages/{id}`.
          */
         message_ids: Array<string>;
         /**
@@ -1625,7 +1629,7 @@ type ReceiveRules = {
     rules: Array<{
         id: string;
         /**
-         * reject refuses before the message is stored. spam, trash and archive file it. inbox means never classify this sender as spam.
+         * reject refuses before the message is stored. spam, trash and archive file it. inbox means never file this sender as spam, for mail that passes DMARC.
          */
         action: string;
         match_type: 'address' | 'domain';
@@ -3883,6 +3887,10 @@ type MessagesAwaitData = {
          * Also return a matching message filed as spam. Without it, one is counted in `held_back` instead, with its id.
          */
         include_spam?: 'true' | 'false';
+        /**
+         * With `from`, also return a match that did not pass DMARC, whose From may be forged. Without it, one is counted in `held_back.unauthenticated` instead, with its id.
+         */
+        include_unauthenticated?: 'true' | 'false';
         /**
          * Only messages that arrived after this: the `cursor` a previous call returned, or `now`. Without it, the wait first looks back 2 minutes and returns the newest matching message from then, so a code that beat you to the call is not missed.
          */
@@ -8708,7 +8716,7 @@ declare const identitiesReceiveRulesGet: <ThrowOnError extends boolean = false>(
  *
  * `value` is an address or a domain and the string says which: `billing@acme.com` matches one person, `acme.com` matches everybody there. **The more specific rule wins**, and an address’s own rule wins over a workspace-wide one. Adding **replaces** any rule already there for that value.
  *
- * `action` is `reject`, `spam`, `trash`, `archive` or `inbox`. **`reject` refuses before the message is stored** — no row, no thread, no storage charged and no webhook — which is what an address nobody will ever open wants. The other four file it, and `inbox` means *never classify this sender as spam*.
+ * `action` is `reject`, `spam`, `trash`, `archive` or `inbox`. **`reject` refuses before the message is stored** — no row, no thread, no storage charged and no webhook — which is what an address nobody will ever open wants. The other four file it, and `inbox` means *never file this sender as spam*. A rule takes a message out of spam only when it passed DMARC, because the rule matches a `From:` anybody can write.
  *
  * **It is not a security control.** The `From:` header is written by the sender, and anybody blocked can change it for the price of a new address. What this buys is not paying for mail from senders who have not bothered.
  */
@@ -8814,7 +8822,7 @@ declare const messagesUndo: <ThrowOnError extends boolean = false>(options: Opti
 /**
  * Wait for the next message
  *
- * Holds the request open until a message matching the filters arrives at the address, or `timeout` seconds pass — one call where you would otherwise poll. The message carries `extracted`: verification codes and links, most likely first. Without `after`, it first looks back 2 minutes and returns the newest matching message from then, because a code often lands before the call is made; narrow it with `from`, `subject_contains` or `has_code` so an earlier email is not taken for the one you want, or pass `after=now` to wait only for new mail. Pass the returned `cursor` as `after` on the next call so nothing arriving between calls is missed. Answers 200 with `message: null` and `timed_out: true` when nothing came. A matching message filed as spam is not returned unless you pass `include_spam=true`; it is counted in `held_back`, with its id, so a timeout never hides mail that arrived.
+ * Holds the request open until a message matching the filters arrives at the address, or `timeout` seconds pass — one call where you would otherwise poll. The message carries `extracted`: verification codes and links, most likely first. Without `after`, it first looks back 2 minutes and returns the newest matching message from then, because a code often lands before the call is made; narrow it with `from`, `subject_contains` or `has_code` so an earlier email is not taken for the one you want, or pass `after=now` to wait only for new mail. Pass the returned `cursor` as `after` on the next call so nothing arriving between calls is missed. Answers 200 with `message: null` and `timed_out: true` when nothing came. A matching message filed as spam is not returned unless you pass `include_spam=true`; it is counted in `held_back`, with its id, so a timeout never hides mail that arrived. A message matches `from` only when it passed DMARC, because anybody can write a `From:`; one that did not is counted in `held_back.unauthenticated`, and `include_unauthenticated=true` returns it.
  */
 declare const messagesAwait: <ThrowOnError extends boolean = false>(options: Options<MessagesAwaitData, ThrowOnError>) => RequestResult<MessagesAwaitResponses, MessagesAwaitErrors, ThrowOnError>;
 /**