mailpit-api 1.2.0 → 1.3.1

package/README.md

@@ -28,4 +28,6 @@ const messages = await mailpit.listMessages();
 await mailpit.deleteMessages();
 ```
 
-## [Documentation](https://github.com/mpspahr/mailpit-api/wiki/)
+## Documentation
+
+[mailpit-api wiki](https://github.com/mpspahr/mailpit-api/wiki/)

package/dist/cjs/index.d.ts

@@ -44,9 +44,12 @@ export interface MailpitChaosTrigger {
     Probability: number;
 }
 /** Common request parameters for APIs with a search query */
-export interface MailpitSearchRequest {
+export interface MailpitSearchRequest extends MailpitTimeZoneRequest {
     /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search query} */
     query: string;
+}
+/** Common request parameters for APIs with a search query and time zone option */
+export interface MailpitTimeZoneRequest {
     /** {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones | Timezone identifier} used only for `before:` & `after:` searches (eg: "Pacific/Auckland"). */
     tz?: string;
 }
@@ -135,6 +138,17 @@ export interface MailpitMessageSummaryResponse {
     ID: string;
     /** Inline message attachements */
     Inline: MailpitEmailAddressResponse[];
+    /** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
+    ListUnsubscribe: {
+        /** Validation errors (if any) */
+        Errors: string;
+        /** List-Unsubscrobe header value */
+        Header: string;
+        /** List-Unsubscribe-Post valie (if set) */
+        HeaderPost: string;
+        /** Detected links, maximum one email and one HTTP(S) link  */
+        Links: string[];
+    };
     /** Message ID */
     MessageID: string;
     /** ReplyTo addresses */
@@ -187,6 +201,8 @@ export interface MailpitMessagesSummaryResponse {
     }[];
     /** Total number of messages matching the current query */
     messages_count: number;
+    /** Total number of unread messages matching current query */
+    messages_unread: number;
     /** Pagination offset */
     start: number;
     /** All current tags */
@@ -341,6 +357,8 @@ export interface MailpitReadStatusRequest extends MailpitDatabaseIDsRequest {
      * @defaultValue false
      */
     Read?: boolean;
+    /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filter} */
+    Search?: string;
 }
 /** Request parameters for the {@link MailpitClient.searchMessages | searchMessages()} API. */
 export interface MailpitSearchMessagesRequest extends MailpitSearchRequest {
@@ -550,9 +568,13 @@ export declare class MailpitClient {
     listMessages(start?: number, limit?: number): Promise<MailpitMessagesSummaryResponse>;
     /**
      * Set the read status of messages.
-     * @param readStatus - The request containing the message database IDs and read status.
+     * @remarks You can optionally provide an array of `IDs` **OR** a `Search` filter. If neither is  set then all messages are updated.
+     * @param readStatus - The request containing the message database IDs/search string and the read status.
      * @param readStatus.Read - The read status to set. Defaults to `false`.
-     * @param readStatus.IDs - The IDs of the messages to update. If not set then all messages are updated.
+     * @param readStatus.IDs - The optional IDs of the messages to update.
+     * @param readStatus.Search - The optional search string to filter messages.
+     * @param params - Optional parameters for defining the time zone when using the `before:` and `after:` search filters.
+     * @see {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filters}
      * @returns Plain text "ok" response
      * @example
      * ```typescript
@@ -562,11 +584,17 @@ export declare class MailpitClient {
      * // Set all messages as read
      * await mailpit.setReadStatus({ Read: true });
      *
-     * // Set specific messages as read
+     * // Set specific messages as read using IDs
      * await mailpit.setReadStatus({ IDs: ["1", "2", "3"], Read: true });
+     *
+     * // Set specific messages as read using search
+     * await mailpit.setReadStatus({ Search: "from:example.test", Read: true });
+     *
+     * // Set specific messages as read using after: search with time zone
+     * await mailpit.setReadStatus({ Search: "after:2025-04-30", Read: true }, { tz: "America/Chicago" });
      * ```
      */
-    setReadStatus(readStatus: MailpitReadStatusRequest): Promise<string>;
+    setReadStatus(readStatus: MailpitReadStatusRequest, params?: MailpitTimeZoneRequest): Promise<string>;
     /**
      * Delete individual or all messages.
      * @remarks If no `IDs` are provided then all messages are deleted.

package/dist/cjs/index.js

@@ -287,9 +287,13 @@ class MailpitClient {
     }
     /**
      * Set the read status of messages.
-     * @param readStatus - The request containing the message database IDs and read status.
+     * @remarks You can optionally provide an array of `IDs` **OR** a `Search` filter. If neither is  set then all messages are updated.
+     * @param readStatus - The request containing the message database IDs/search string and the read status.
      * @param readStatus.Read - The read status to set. Defaults to `false`.
-     * @param readStatus.IDs - The IDs of the messages to update. If not set then all messages are updated.
+     * @param readStatus.IDs - The optional IDs of the messages to update.
+     * @param readStatus.Search - The optional search string to filter messages.
+     * @param params - Optional parameters for defining the time zone when using the `before:` and `after:` search filters.
+     * @see {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filters}
      * @returns Plain text "ok" response
      * @example
      * ```typescript
@@ -299,13 +303,21 @@ class MailpitClient {
      * // Set all messages as read
      * await mailpit.setReadStatus({ Read: true });
      *
-     * // Set specific messages as read
+     * // Set specific messages as read using IDs
      * await mailpit.setReadStatus({ IDs: ["1", "2", "3"], Read: true });
+     *
+     * // Set specific messages as read using search
+     * await mailpit.setReadStatus({ Search: "from:example.test", Read: true });
+     *
+     * // Set specific messages as read using after: search with time zone
+     * await mailpit.setReadStatus({ Search: "after:2025-04-30", Read: true }, { tz: "America/Chicago" });
      * ```
      */
-    setReadStatus(readStatus) {
+    setReadStatus(readStatus, params) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus));
+            return yield this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus, {
+                params,
+            }));
         });
     }
     /**

package/dist/mjs/index.d.ts

@@ -44,9 +44,12 @@ export interface MailpitChaosTrigger {
     Probability: number;
 }
 /** Common request parameters for APIs with a search query */
-export interface MailpitSearchRequest {
+export interface MailpitSearchRequest extends MailpitTimeZoneRequest {
     /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search query} */
     query: string;
+}
+/** Common request parameters for APIs with a search query and time zone option */
+export interface MailpitTimeZoneRequest {
     /** {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones | Timezone identifier} used only for `before:` & `after:` searches (eg: "Pacific/Auckland"). */
     tz?: string;
 }
@@ -135,6 +138,17 @@ export interface MailpitMessageSummaryResponse {
     ID: string;
     /** Inline message attachements */
     Inline: MailpitEmailAddressResponse[];
+    /** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
+    ListUnsubscribe: {
+        /** Validation errors (if any) */
+        Errors: string;
+        /** List-Unsubscrobe header value */
+        Header: string;
+        /** List-Unsubscribe-Post valie (if set) */
+        HeaderPost: string;
+        /** Detected links, maximum one email and one HTTP(S) link  */
+        Links: string[];
+    };
     /** Message ID */
     MessageID: string;
     /** ReplyTo addresses */
@@ -187,6 +201,8 @@ export interface MailpitMessagesSummaryResponse {
     }[];
     /** Total number of messages matching the current query */
     messages_count: number;
+    /** Total number of unread messages matching current query */
+    messages_unread: number;
     /** Pagination offset */
     start: number;
     /** All current tags */
@@ -341,6 +357,8 @@ export interface MailpitReadStatusRequest extends MailpitDatabaseIDsRequest {
      * @defaultValue false
      */
     Read?: boolean;
+    /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filter} */
+    Search?: string;
 }
 /** Request parameters for the {@link MailpitClient.searchMessages | searchMessages()} API. */
 export interface MailpitSearchMessagesRequest extends MailpitSearchRequest {
@@ -550,9 +568,13 @@ export declare class MailpitClient {
     listMessages(start?: number, limit?: number): Promise<MailpitMessagesSummaryResponse>;
     /**
      * Set the read status of messages.
-     * @param readStatus - The request containing the message database IDs and read status.
+     * @remarks You can optionally provide an array of `IDs` **OR** a `Search` filter. If neither is  set then all messages are updated.
+     * @param readStatus - The request containing the message database IDs/search string and the read status.
      * @param readStatus.Read - The read status to set. Defaults to `false`.
-     * @param readStatus.IDs - The IDs of the messages to update. If not set then all messages are updated.
+     * @param readStatus.IDs - The optional IDs of the messages to update.
+     * @param readStatus.Search - The optional search string to filter messages.
+     * @param params - Optional parameters for defining the time zone when using the `before:` and `after:` search filters.
+     * @see {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filters}
      * @returns Plain text "ok" response
      * @example
      * ```typescript
@@ -562,11 +584,17 @@ export declare class MailpitClient {
      * // Set all messages as read
      * await mailpit.setReadStatus({ Read: true });
      *
-     * // Set specific messages as read
+     * // Set specific messages as read using IDs
      * await mailpit.setReadStatus({ IDs: ["1", "2", "3"], Read: true });
+     *
+     * // Set specific messages as read using search
+     * await mailpit.setReadStatus({ Search: "from:example.test", Read: true });
+     *
+     * // Set specific messages as read using after: search with time zone
+     * await mailpit.setReadStatus({ Search: "after:2025-04-30", Read: true }, { tz: "America/Chicago" });
      * ```
      */
-    setReadStatus(readStatus: MailpitReadStatusRequest): Promise<string>;
+    setReadStatus(readStatus: MailpitReadStatusRequest, params?: MailpitTimeZoneRequest): Promise<string>;
     /**
      * Delete individual or all messages.
      * @remarks If no `IDs` are provided then all messages are deleted.

package/dist/mjs/index.js

@@ -220,9 +220,13 @@ export class MailpitClient {
     }
     /**
      * Set the read status of messages.
-     * @param readStatus - The request containing the message database IDs and read status.
+     * @remarks You can optionally provide an array of `IDs` **OR** a `Search` filter. If neither is  set then all messages are updated.
+     * @param readStatus - The request containing the message database IDs/search string and the read status.
      * @param readStatus.Read - The read status to set. Defaults to `false`.
-     * @param readStatus.IDs - The IDs of the messages to update. If not set then all messages are updated.
+     * @param readStatus.IDs - The optional IDs of the messages to update.
+     * @param readStatus.Search - The optional search string to filter messages.
+     * @param params - Optional parameters for defining the time zone when using the `before:` and `after:` search filters.
+     * @see {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filters}
      * @returns Plain text "ok" response
      * @example
      * ```typescript
@@ -232,12 +236,20 @@ export class MailpitClient {
      * // Set all messages as read
      * await mailpit.setReadStatus({ Read: true });
      *
-     * // Set specific messages as read
+     * // Set specific messages as read using IDs
      * await mailpit.setReadStatus({ IDs: ["1", "2", "3"], Read: true });
+     *
+     * // Set specific messages as read using search
+     * await mailpit.setReadStatus({ Search: "from:example.test", Read: true });
+     *
+     * // Set specific messages as read using after: search with time zone
+     * await mailpit.setReadStatus({ Search: "after:2025-04-30", Read: true }, { tz: "America/Chicago" });
      * ```
      */
-    async setReadStatus(readStatus) {
-        return await this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus));
+    async setReadStatus(readStatus, params) {
+        return await this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus, {
+            params,
+        }));
     }
     /**
      * Delete individual or all messages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailpit-api",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A NodeJS client library, written in TypeScript, to interact with the Mailpit API.",
   "repository": {
     "type": "git",
@@ -35,20 +35,19 @@
   "author": "Matthew Spahr",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.8.1"
+    "axios": "^1.9.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.21.0",
-    "@types/eslint__js": "^8.25.0",
-    "@types/node": "^20.14.15",
-    "eslint": "^9.21.0",
+    "@eslint/js": "^9.27.0",
+    "@types/node": "^22.15.18",
+    "eslint": "^9.27.0",
     "jest": "^29.7.0",
-    "prettier": "3.5.2",
-    "tsx": "^4.19.3",
-    "typedoc": "^0.27.9",
+    "prettier": "3.5.3",
+    "tsx": "^4.19.4",
+    "typedoc": "^0.28.4",
     "typedoc-github-wiki-theme": "^2.1.0",
-    "typedoc-plugin-markdown": "^4.4.2",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.25.0"
+    "typedoc-plugin-markdown": "^4.6.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1"
   }
 }

package/src/index.ts

@@ -56,9 +56,13 @@ export interface MailpitChaosTrigger {
 }
 
 /** Common request parameters for APIs with a search query */
-export interface MailpitSearchRequest {
+export interface MailpitSearchRequest extends MailpitTimeZoneRequest {
   /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search query} */
   query: string;
+}
+
+/** Common request parameters for APIs with a search query and time zone option */
+export interface MailpitTimeZoneRequest {
   /** {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones | Timezone identifier} used only for `before:` & `after:` searches (eg: "Pacific/Auckland"). */
   tz?: string;
 }
@@ -152,6 +156,17 @@ export interface MailpitMessageSummaryResponse {
   ID: string;
   /** Inline message attachements */
   Inline: MailpitEmailAddressResponse[];
+  /** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
+  ListUnsubscribe: {
+    /** Validation errors (if any) */
+    Errors: string;
+    /** List-Unsubscrobe header value */
+    Header: string;
+    /** List-Unsubscribe-Post valie (if set) */
+    HeaderPost: string;
+    /** Detected links, maximum one email and one HTTP(S) link  */
+    Links: string[];
+  };
   /** Message ID */
   MessageID: string;
   /** ReplyTo addresses */
@@ -205,6 +220,8 @@ export interface MailpitMessagesSummaryResponse {
   }[];
   /** Total number of messages matching the current query */
   messages_count: number;
+  /** Total number of unread messages matching current query */
+  messages_unread: number;
   /** Pagination offset */
   start: number;
   /** All current tags */
@@ -366,6 +383,8 @@ export interface MailpitReadStatusRequest extends MailpitDatabaseIDsRequest {
    * @defaultValue false
    */
   Read?: boolean;
+  /** {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filter} */
+  Search?: string;
 }
 
 /** Request parameters for the {@link MailpitClient.searchMessages | searchMessages()} API. */
@@ -724,9 +743,13 @@ export class MailpitClient {
 
   /**
    * Set the read status of messages.
-   * @param readStatus - The request containing the message database IDs and read status.
+   * @remarks You can optionally provide an array of `IDs` **OR** a `Search` filter. If neither is  set then all messages are updated.
+   * @param readStatus - The request containing the message database IDs/search string and the read status.
    * @param readStatus.Read - The read status to set. Defaults to `false`.
-   * @param readStatus.IDs - The IDs of the messages to update. If not set then all messages are updated.
+   * @param readStatus.IDs - The optional IDs of the messages to update.
+   * @param readStatus.Search - The optional search string to filter messages.
+   * @param params - Optional parameters for defining the time zone when using the `before:` and `after:` search filters.
+   * @see {@link https://mailpit.axllent.org/docs/usage/search-filters/ | Search filters}
    * @returns Plain text "ok" response
    * @example
    * ```typescript
@@ -736,15 +759,24 @@ export class MailpitClient {
    * // Set all messages as read
    * await mailpit.setReadStatus({ Read: true });
    *
-   * // Set specific messages as read
+   * // Set specific messages as read using IDs
    * await mailpit.setReadStatus({ IDs: ["1", "2", "3"], Read: true });
+   *
+   * // Set specific messages as read using search
+   * await mailpit.setReadStatus({ Search: "from:example.test", Read: true });
+   *
+   * // Set specific messages as read using after: search with time zone
+   * await mailpit.setReadStatus({ Search: "after:2025-04-30", Read: true }, { tz: "America/Chicago" });
    * ```
    */
   public async setReadStatus(
     readStatus: MailpitReadStatusRequest,
+    params?: MailpitTimeZoneRequest,
   ): Promise<string> {
     return await this.handleRequest(() =>
-      this.axiosInstance.put<string>(`/api/v1/messages`, readStatus),
+      this.axiosInstance.put<string>(`/api/v1/messages`, readStatus, {
+        params,
+      }),
     );
   }