mailpit-api 1.0.5 → 1.1.0

package/README.md

@@ -1,3 +1,29 @@
 # mailpit-api
 
-A NodeJS client library, written in TypeScript, to interact with the Mailpit API.
+A NodeJS client library, written in TypeScript, to interact with the Mailpit API.
+
+[![npm version](https://img.shields.io/npm/v/mailpit-api.svg)](https://www.npmjs.com/package/mailpit-api)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+This package provides a convenient way to interact with [Mailpit](https://github.com/axllent/mailpit) from your NodeJS applications.
+
+## Installation
+
+```bash
+npm install mailpit-api
+```
+
+## Example
+
+```typescript
+import { MailpitClient } from "mailpit-api";
+
+// Initialize the API client
+const mailpit = new MailpitClient("http://localhost:8025");
+
+// Get all messages
+const messages = await mailpit.listMessages();
+
+// Delete all messages
+await mailpit.deleteMessages();
+```

package/dist/cjs/eslint.config.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("@typescript-eslint/utils/dist/ts-eslint").FlatConfig.ConfigArray;
+export default _default;

package/dist/cjs/{index.d.ts → src/index.d.ts}

@@ -1,3 +1,22 @@
+interface Address {
+    Address: string;
+    Name: string;
+}
+interface Email {
+    Email: string;
+    Name: string;
+}
+interface Attachment {
+    ContentID: string;
+    ContentType: string;
+    FileName: string;
+    PartID: string;
+    Size: number;
+}
+interface ChaosTrigger {
+    ErrorCode: number;
+    Probability: number;
+}
 export interface MailpitInfoResponse {
     Database: string;
     DatabaseSize: number;
@@ -30,49 +49,22 @@ export interface MailpitConfigurationResponse {
     };
 }
 export interface MailpitMessageSummaryResponse {
-    Attachments: {
-        ContentID: string;
-        ContentType: string;
-        FileName: string;
-        PartID: string;
-        Size: number;
-    }[];
-    Bcc: {
-        Address: string;
-        Name: string;
-    }[];
-    Cc: {
-        Address: string;
-        Name: string;
-    }[];
+    Attachments: Attachment[];
+    Bcc: Address[];
+    Cc: Address[];
     Date: string;
-    From: {
-        Address: string;
-        Name: string;
-    };
+    From: Address;
     HTML: string;
     ID: string;
-    Inline: {
-        ContentID: string;
-        ContentType: string;
-        FileName: string;
-        PartID: string;
-        Size: number;
-    }[];
+    Inline: Attachment[];
     MessageID: string;
-    ReplyTo: {
-        Address: string;
-        Name: string;
-    }[];
+    ReplyTo: Address[];
     ReturnPath: string;
     Size: number;
     Subject: string;
     Tags: string[];
     Text: string;
-    To: {
-        Address: string;
-        Name: string;
-    }[];
+    To: Address[];
 }
 export interface MailpitMessagesSummaryResponse {
     messages: {
@@ -84,26 +76,11 @@ export interface MailpitMessagesSummaryResponse {
         ID: string;
         MessageID: string;
         Read: boolean;
-        Bcc: {
-            Address: string;
-            Name: string;
-        }[];
-        Cc: {
-            Address: string;
-            Name: string;
-        }[];
-        From: {
-            Address: string;
-            Name: string;
-        };
-        ReplyTo: {
-            Address: string;
-            Name: string;
-        }[];
-        To: {
-            Address: string;
-            Name: string;
-        }[];
+        Bcc: Address[];
+        Cc: Address[];
+        From: Address;
+        ReplyTo: Address[];
+        To: Address[];
     }[];
     messages_count: number;
     start: number;
@@ -120,29 +97,17 @@ export interface MailpitSendRequest {
         Filename: string;
     }[];
     Bcc: string[];
-    Cc: {
-        Email: string;
-        Name: string;
-    }[];
-    From: {
-        Email: string;
-        Name: string;
-    };
+    Cc: Email[];
+    From: Email;
     HTML: string;
     Headers: {
         [key: string]: string;
     };
-    ReplyTo: {
-        Email: string;
-        Name: string;
-    }[];
+    ReplyTo: Email[];
     Subject: string;
     Tags: string[];
     Text: string;
-    To: {
-        Email: string;
-        Name: string;
-    }[];
+    To: Email[];
 }
 export interface MailpitSendMessageConfirmationResponse {
     ID: string;
@@ -224,17 +189,34 @@ export interface MailpitSetTagsRequest {
     IDs: string[];
     Tags: string[];
 }
+export interface ChaosTriggersRequest {
+    Authentication?: ChaosTrigger;
+    Recipient?: ChaosTrigger;
+    Sender?: ChaosTrigger;
+}
+export interface ChaosTriggersResponse {
+    Authentication: ChaosTrigger;
+    Recipient?: ChaosTrigger;
+    Sender?: ChaosTrigger;
+}
+interface AttachmentResponse {
+    data: ArrayBuffer;
+    contentType: string;
+}
 export declare class MailpitClient {
     private axiosInstance;
-    constructor(baseURL: string);
+    constructor(baseURL: string, auth?: {
+        username: string;
+        password: string;
+    });
     private handleRequest;
     getInfo(): Promise<MailpitInfoResponse>;
     getConfiguration(): Promise<MailpitConfigurationResponse>;
     getMessageSummary(id?: string): Promise<MailpitMessageSummaryResponse>;
     getMessageHeaders(id?: string): Promise<MailpitMessageHeadersResponse>;
-    getMessageAttachment(id: string, partID: string): Promise<string>;
+    getMessageAttachment(id: string, partID: string): Promise<AttachmentResponse>;
     getMessageSource(id?: string): Promise<string>;
-    getAttachmentThumbnail(id: string, partID: string): Promise<string>;
+    getAttachmentThumbnail(id: string, partID: string): Promise<AttachmentResponse>;
     releaseMessage(id: string, releaseRequest: {
         To: string[];
     }): Promise<string>;
@@ -251,6 +233,9 @@ export declare class MailpitClient {
     setTags(request: MailpitSetTagsRequest): Promise<string>;
     renameTag(tag: string, newTagName: string): Promise<string>;
     deleteTag(tag: string): Promise<string>;
-    renderMessageHTML(id?: string): Promise<string>;
+    renderMessageHTML(id?: string, embed?: 1): Promise<string>;
     renderMessageText(id?: string): Promise<string>;
+    getChaosTriggers(): Promise<ChaosTriggersResponse>;
+    setChaosTriggers(triggers?: ChaosTriggersRequest): Promise<ChaosTriggersResponse>;
 }
+export {};

package/dist/cjs/src/index.js

@@ -0,0 +1,239 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailpitClient = void 0;
+const axios_1 = __importStar(require("axios"));
+class MailpitClient {
+    constructor(baseURL, auth) {
+        this.axiosInstance = axios_1.default.create({
+            baseURL,
+            auth,
+            validateStatus: function (status) {
+                return status === 200;
+            },
+        });
+    }
+    handleRequest(request_1) {
+        return __awaiter(this, arguments, void 0, function* (request, options = { fullResponse: false }) {
+            var _a, _b, _c;
+            try {
+                const response = yield request();
+                return options.fullResponse ? response : response.data;
+            }
+            catch (error) {
+                if ((0, axios_1.isAxiosError)(error)) {
+                    const url = ((_a = error.config) === null || _a === void 0 ? void 0 : _a.url) || "UNKNOWN URL";
+                    const method = ((_c = (_b = error.config) === null || _b === void 0 ? void 0 : _b.method) === null || _c === void 0 ? void 0 : _c.toUpperCase()) || "UNKNOWN METHOD";
+                    if (error.response) {
+                        // Server responded with a status other than 2xx
+                        throw new Error(`Mailpit API Error: ${error.response.status.toString()} ${error.response.statusText} at ${method} ${url}: ${JSON.stringify(error.response.data)}`);
+                    }
+                    else if (error.request) {
+                        // Request was made but no response was received
+                        throw new Error(`Mailpit API Error: No response received from server at ${method} ${url}`);
+                    }
+                    else {
+                        // Something happened in setting up the request
+                        throw new Error(`Mailpit API Error: ${error.toString()} at ${method} ${url}`);
+                    }
+                }
+                else {
+                    throw new Error(`Unexpected Error: ${error}`);
+                }
+            }
+        });
+    }
+    // Application
+    getInfo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.get("/api/v1/info"));
+        });
+    }
+    getConfiguration() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.get("/api/v1/webui"));
+        });
+    }
+    // Message
+    getMessageSummary() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}`));
+        });
+    }
+    getMessageHeaders() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/headers`));
+        });
+    }
+    getMessageAttachment(id, partID) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/part/${partID}`, { responseType: "arraybuffer" }), { fullResponse: true });
+            return {
+                data: response.data,
+                contentType: response.headers["content-type"],
+            };
+        });
+    }
+    getMessageSource() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/raw`));
+        });
+    }
+    getAttachmentThumbnail(id, partID) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/part/${partID}/thumb`, {
+                responseType: "arraybuffer",
+            }), { fullResponse: true });
+            return {
+                data: response.data,
+                contentType: response.headers["content-type"],
+            };
+        });
+    }
+    releaseMessage(id, releaseRequest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.post(`/api/v1/message/${id}/release`, releaseRequest));
+        });
+    }
+    sendMessage(sendReqest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.post(`/api/v1/send`, sendReqest));
+        });
+    }
+    // Other
+    htmlCheck() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/html-check`));
+        });
+    }
+    linkCheck() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest", follow = "false") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/link-check`, { params: { follow } }));
+        });
+    }
+    spamAssassinCheck() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/sa-check`));
+        });
+    }
+    // Messages
+    listMessages() {
+        return __awaiter(this, arguments, void 0, function* (start = 0, limit = 50) {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/messages`, { params: { start, limit } }));
+        });
+    }
+    setReadStatus(readStatus) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus));
+        });
+    }
+    deleteMessages(deleteRequest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.delete(`/api/v1/messages`, {
+                data: deleteRequest,
+            }));
+        });
+    }
+    // See https://mailpit.axllent.org/docs/usage/search-filters/
+    searchMessages(search) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/search`, {
+                params: search,
+            }));
+        });
+    }
+    // See https://mailpit.axllent.org/docs/usage/search-filters/
+    deleteMessagesBySearch(search) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.delete(`/api/v1/search`, { params: search }));
+        });
+    }
+    // Tags
+    getTags() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/api/v1/tags`));
+        });
+    }
+    setTags(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.put(`/api/v1/tags`, request));
+        });
+    }
+    renameTag(tag, newTagName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const encodedTag = encodeURI(tag);
+            return yield this.handleRequest(() => this.axiosInstance.put(`/api/v1/tags/${encodedTag}`, {
+                Name: newTagName,
+            }));
+        });
+    }
+    deleteTag(tag) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const encodedTag = encodeURI(tag);
+            return yield this.handleRequest(() => this.axiosInstance.delete(`/api/v1/tags/${encodedTag}`));
+        });
+    }
+    // Testing
+    renderMessageHTML() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest", embed) {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/view/${id}.html`, { params: { embed } }));
+        });
+    }
+    renderMessageText() {
+        return __awaiter(this, arguments, void 0, function* (id = "latest") {
+            return yield this.handleRequest(() => this.axiosInstance.get(`/view/${id}.txt`));
+        });
+    }
+    getChaosTriggers() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.handleRequest(() => this.axiosInstance.get("/api/v1/chaos"));
+        });
+    }
+    setChaosTriggers() {
+        return __awaiter(this, arguments, void 0, function* (triggers = {}) {
+            return yield this.handleRequest(() => this.axiosInstance.put("/api/v1/chaos", triggers));
+        });
+    }
+}
+exports.MailpitClient = MailpitClient;

package/dist/mjs/eslint.config.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("@typescript-eslint/utils/dist/ts-eslint").FlatConfig.ConfigArray;
+export default _default;

package/dist/mjs/{index.d.ts → src/index.d.ts}

@@ -1,3 +1,22 @@
+interface Address {
+    Address: string;
+    Name: string;
+}
+interface Email {
+    Email: string;
+    Name: string;
+}
+interface Attachment {
+    ContentID: string;
+    ContentType: string;
+    FileName: string;
+    PartID: string;
+    Size: number;
+}
+interface ChaosTrigger {
+    ErrorCode: number;
+    Probability: number;
+}
 export interface MailpitInfoResponse {
     Database: string;
     DatabaseSize: number;
@@ -30,49 +49,22 @@ export interface MailpitConfigurationResponse {
     };
 }
 export interface MailpitMessageSummaryResponse {
-    Attachments: {
-        ContentID: string;
-        ContentType: string;
-        FileName: string;
-        PartID: string;
-        Size: number;
-    }[];
-    Bcc: {
-        Address: string;
-        Name: string;
-    }[];
-    Cc: {
-        Address: string;
-        Name: string;
-    }[];
+    Attachments: Attachment[];
+    Bcc: Address[];
+    Cc: Address[];
     Date: string;
-    From: {
-        Address: string;
-        Name: string;
-    };
+    From: Address;
     HTML: string;
     ID: string;
-    Inline: {
-        ContentID: string;
-        ContentType: string;
-        FileName: string;
-        PartID: string;
-        Size: number;
-    }[];
+    Inline: Attachment[];
     MessageID: string;
-    ReplyTo: {
-        Address: string;
-        Name: string;
-    }[];
+    ReplyTo: Address[];
     ReturnPath: string;
     Size: number;
     Subject: string;
     Tags: string[];
     Text: string;
-    To: {
-        Address: string;
-        Name: string;
-    }[];
+    To: Address[];
 }
 export interface MailpitMessagesSummaryResponse {
     messages: {
@@ -84,26 +76,11 @@ export interface MailpitMessagesSummaryResponse {
         ID: string;
         MessageID: string;
         Read: boolean;
-        Bcc: {
-            Address: string;
-            Name: string;
-        }[];
-        Cc: {
-            Address: string;
-            Name: string;
-        }[];
-        From: {
-            Address: string;
-            Name: string;
-        };
-        ReplyTo: {
-            Address: string;
-            Name: string;
-        }[];
-        To: {
-            Address: string;
-            Name: string;
-        }[];
+        Bcc: Address[];
+        Cc: Address[];
+        From: Address;
+        ReplyTo: Address[];
+        To: Address[];
     }[];
     messages_count: number;
     start: number;
@@ -120,29 +97,17 @@ export interface MailpitSendRequest {
         Filename: string;
     }[];
     Bcc: string[];
-    Cc: {
-        Email: string;
-        Name: string;
-    }[];
-    From: {
-        Email: string;
-        Name: string;
-    };
+    Cc: Email[];
+    From: Email;
     HTML: string;
     Headers: {
         [key: string]: string;
     };
-    ReplyTo: {
-        Email: string;
-        Name: string;
-    }[];
+    ReplyTo: Email[];
     Subject: string;
     Tags: string[];
     Text: string;
-    To: {
-        Email: string;
-        Name: string;
-    }[];
+    To: Email[];
 }
 export interface MailpitSendMessageConfirmationResponse {
     ID: string;
@@ -224,17 +189,34 @@ export interface MailpitSetTagsRequest {
     IDs: string[];
     Tags: string[];
 }
+export interface ChaosTriggersRequest {
+    Authentication?: ChaosTrigger;
+    Recipient?: ChaosTrigger;
+    Sender?: ChaosTrigger;
+}
+export interface ChaosTriggersResponse {
+    Authentication: ChaosTrigger;
+    Recipient?: ChaosTrigger;
+    Sender?: ChaosTrigger;
+}
+interface AttachmentResponse {
+    data: ArrayBuffer;
+    contentType: string;
+}
 export declare class MailpitClient {
     private axiosInstance;
-    constructor(baseURL: string);
+    constructor(baseURL: string, auth?: {
+        username: string;
+        password: string;
+    });
     private handleRequest;
     getInfo(): Promise<MailpitInfoResponse>;
     getConfiguration(): Promise<MailpitConfigurationResponse>;
     getMessageSummary(id?: string): Promise<MailpitMessageSummaryResponse>;
     getMessageHeaders(id?: string): Promise<MailpitMessageHeadersResponse>;
-    getMessageAttachment(id: string, partID: string): Promise<string>;
+    getMessageAttachment(id: string, partID: string): Promise<AttachmentResponse>;
     getMessageSource(id?: string): Promise<string>;
-    getAttachmentThumbnail(id: string, partID: string): Promise<string>;
+    getAttachmentThumbnail(id: string, partID: string): Promise<AttachmentResponse>;
     releaseMessage(id: string, releaseRequest: {
         To: string[];
     }): Promise<string>;
@@ -251,6 +233,9 @@ export declare class MailpitClient {
     setTags(request: MailpitSetTagsRequest): Promise<string>;
     renameTag(tag: string, newTagName: string): Promise<string>;
     deleteTag(tag: string): Promise<string>;
-    renderMessageHTML(id?: string): Promise<string>;
+    renderMessageHTML(id?: string, embed?: 1): Promise<string>;
     renderMessageText(id?: string): Promise<string>;
+    getChaosTriggers(): Promise<ChaosTriggersResponse>;
+    setChaosTriggers(triggers?: ChaosTriggersRequest): Promise<ChaosTriggersResponse>;
 }
+export {};