mailpit-api 1.4.0 → 1.5.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.
Files changed (6) hide show
  1. package/README.md +72 -10
  2. package/dist/index.d.mts +11 -5
  3. package/dist/index.d.ts +11 -5
  4. package/dist/index.js +1 -1
  5. package/dist/index.mjs +1 -1
  6. package/package.json +38 -18
package/README.md CHANGED
@@ -1,11 +1,11 @@
1
- # mailpit-api
1
+ # Mailpit API Client
2
2
 
3
- A NodeJS client library, written in TypeScript, to interact with the Mailpit API.
3
+ [![Package Version](https://img.shields.io/npm/v/mailpit-api.svg?label=npm)](https://www.npmjs.com/package/mailpit-api)
4
+ [![Test Suite](https://github.com/mpspahr/mailpit-api/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mpspahr/mailpit-api/actions/workflows/npm-publish.yml)
5
+ [![Code Coverage](https://codecov.io/gh/mpspahr/mailpit-api/branch/main/graph/badge.svg)](https://codecov.io/gh/mpspahr/mailpit-api)
6
+ [![Documentation](https://github.com/mpspahr/mailpit-api/actions/workflows/deploy-docs.yml/badge.svg?branch=main&label=docs)](https://mpspahr.github.io/mailpit-api/)
4
7
 
5
- [![npm version](https://img.shields.io/npm/v/mailpit-api.svg)](https://www.npmjs.com/package/mailpit-api)
6
- [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
7
-
8
- This package provides a convenient way to interact with [Mailpit](https://github.com/axllent/mailpit) from your NodeJS applications.
8
+ A TypeScript client for interacting with [Mailpit](https://mailpit.axllent.org/)'s [REST API](https://mailpit.axllent.org/docs/api-v1/view.html#get-/api/v1/info). Ideal for automating your email testing.
9
9
 
10
10
  ## Installation
11
11
 
@@ -13,7 +13,15 @@ This package provides a convenient way to interact with [Mailpit](https://github
13
13
  npm install mailpit-api
14
14
  ```
15
15
 
16
- ## Example
16
+ ## Documentation
17
+
18
+ [Detailed documentation](https://mpspahr.github.io/mailpit-api/), including all available methods and type definitions, is available.
19
+
20
+ ## Examples
21
+
22
+ **Prerequisites:** These examples require a Mailpit installation. See the [Mailpit installation guide](https://mailpit.axllent.org/docs/install/).
23
+
24
+ ### Basic Usage with NodeJS
17
25
 
18
26
  ```typescript
19
27
  import { MailpitClient } from "mailpit-api";
@@ -21,13 +29,67 @@ import { MailpitClient } from "mailpit-api";
21
29
  // Initialize the API client
22
30
  const mailpit = new MailpitClient("http://localhost:8025");
23
31
 
24
- // Get all messages
32
+ // Send a message
33
+ await mailpit.sendMessage({
34
+ From: { Email: "user@example.test" },
35
+ To: [{ Email: "rec@example.test" }],
36
+ Subject: "Test Email",
37
+ });
38
+
39
+ // Get a summary of all messages
25
40
  const messages = await mailpit.listMessages();
26
41
 
27
42
  // Delete all messages
28
43
  await mailpit.deleteMessages();
29
44
  ```
30
45
 
31
- ## Documentation
46
+ ### Using with Playwright Tests
47
+
48
+ Use `mailpit-api` with [Playwright](https://playwright.dev/) as a custom [test fixture](https://playwright.dev/docs/test-fixtures) to handle email testing.
49
+
50
+ ```typescript
51
+ // fixtures.ts
52
+ import { test as base } from "@playwright/test";
53
+ import { MailpitClient } from "mailpit-api";
54
+
55
+ type MyFixtures = {
56
+ mailpit: MailpitClient;
57
+ };
58
+
59
+ export const test = base.extend<MyFixtures>({
60
+ mailpit: async ({}, use) => {
61
+ const mailpit = new MailpitClient("http://localhost:8025");
62
+ await mailpit.deleteMessages();
63
+ await use(mailpit);
64
+ },
65
+ });
32
66
 
33
- [mailpit-api wiki](https://github.com/mpspahr/mailpit-api/wiki/)
67
+ export { expect } from "@playwright/test";
68
+ ```
69
+
70
+ ```typescript
71
+ // tests/register.spec.ts
72
+ import { test, expect } from "../fixtures";
73
+
74
+ test("should receive welcome email after registration", async ({
75
+ page,
76
+ mailpit,
77
+ }) => {
78
+ // Register
79
+ await page.goto("/register");
80
+ await page.getByTestId("email").fill("test@example.test");
81
+ await page.getByTestId("password").fill("password123");
82
+ await page.getByTestId("submit").click();
83
+
84
+ // Wait for success message on page
85
+ await expect(page.getByTestId("success-message")).toBeVisible();
86
+
87
+ // Get the welcome email
88
+ const message = await mailpit.getMessageSummary();
89
+
90
+ expect(message.To[0].Address).toBe("test@example.test");
91
+ expect(message.From.Address).toBe("no-reply@your-app.test");
92
+ expect(message.Subject).toBe("Welcome to Our App");
93
+ expect(message.Text).toContain("Thank you for registering with our app!");
94
+ });
95
+ ```
package/dist/index.d.mts CHANGED
@@ -101,6 +101,8 @@ interface MailpitConfigurationResponse {
101
101
  ChaosEnabled: boolean;
102
102
  /** Whether messages with duplicate IDs are ignored */
103
103
  DuplicatesIgnored: boolean;
104
+ /** Whether the delete button should be hidden */
105
+ HideDeleteAllButton: boolean;
104
106
  /** Label to identify this Mailpit instance */
105
107
  Label: string;
106
108
  MessageRelay: {
@@ -112,6 +114,8 @@ interface MailpitConfigurationResponse {
112
114
  Enabled: boolean;
113
115
  /** Overrides the "From" address for all relayed messages */
114
116
  OverrideFrom: string;
117
+ /** @deprecated Refer to `AllowedRecipients` instead. No longer documented upstream */
118
+ RecipientAllowlist: string;
115
119
  /** Enforced Return-Path (if set) for relay bounces */
116
120
  ReturnPath: string;
117
121
  /** The configured SMTP server address */
@@ -137,7 +141,7 @@ interface MailpitMessageSummaryResponse {
137
141
  /** Database ID */
138
142
  ID: string;
139
143
  /** Inline message attachements */
140
- Inline: MailpitEmailAddressResponse[];
144
+ Inline: MailpitAttachmentResponse[];
141
145
  /** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
142
146
  ListUnsubscribe: {
143
147
  /** Validation errors (if any) */
@@ -211,6 +215,8 @@ interface MailpitMessagesSummaryResponse {
211
215
  total: number;
212
216
  /** Total number of unread messages in mailbox */
213
217
  unread: number;
218
+ /** @deprecated No longer documented upstream */
219
+ count: number;
214
220
  }
215
221
  /** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
216
222
  interface MailpitMessageHeadersResponse {
@@ -335,7 +341,7 @@ interface MailpitLinkCheckResponse {
335
341
  /** Response from the {@link MailpitClient.spamAssassinCheck | spamAssassinCheck()} API containing containing SpamAssassin check results. */
336
342
  interface MailpitSpamAssassinResponse {
337
343
  /** If populated will return an error string */
338
- Errors: number;
344
+ Error: string;
339
345
  /** Whether the message is spam or not */
340
346
  IsSpam: boolean;
341
347
  /** Spam rules triggered */
@@ -395,7 +401,7 @@ interface MailpitChaosTriggersResponse {
395
401
  /** Response for the {@link MailpitClient.getMessageAttachment |getMessageAttachment()} and {@link MailpitClient.getAttachmentThumbnail | getAttachmentThumbnail()} APIs containing attachment data */
396
402
  interface MailpitAttachmentDataResponse {
397
403
  /** The attachment binary data */
398
- data: ArrayBuffer;
404
+ data: ArrayBuffer | Buffer;
399
405
  /** The attachment MIME type */
400
406
  contentType: string;
401
407
  }
@@ -409,7 +415,7 @@ interface MailpitAttachmentDataResponse {
409
415
  * ```
410
416
  */
411
417
  declare class MailpitClient {
412
- private axiosInstance;
418
+ private readonly axiosInstance;
413
419
  /**
414
420
  * Creates an instance of {@link MailpitClient}.
415
421
  * @param baseURL - The base URL of the Mailpit API.
@@ -656,7 +662,7 @@ declare class MailpitClient {
656
662
  * const linkCheck = await mailpit.linkCheck();
657
663
  * ```
658
664
  */
659
- linkCheck(id?: string, follow?: "true" | "false"): Promise<MailpitLinkCheckResponse>;
665
+ linkCheck(id?: string, follow?: boolean): Promise<MailpitLinkCheckResponse>;
660
666
  /**
661
667
  * Performs a SpamAssassin check (if enabled) on a specific message.
662
668
  * @param id - The message database ID. Defaults to `latest` to return the latest message.
package/dist/index.d.ts CHANGED
@@ -101,6 +101,8 @@ interface MailpitConfigurationResponse {
101
101
  ChaosEnabled: boolean;
102
102
  /** Whether messages with duplicate IDs are ignored */
103
103
  DuplicatesIgnored: boolean;
104
+ /** Whether the delete button should be hidden */
105
+ HideDeleteAllButton: boolean;
104
106
  /** Label to identify this Mailpit instance */
105
107
  Label: string;
106
108
  MessageRelay: {
@@ -112,6 +114,8 @@ interface MailpitConfigurationResponse {
112
114
  Enabled: boolean;
113
115
  /** Overrides the "From" address for all relayed messages */
114
116
  OverrideFrom: string;
117
+ /** @deprecated Refer to `AllowedRecipients` instead. No longer documented upstream */
118
+ RecipientAllowlist: string;
115
119
  /** Enforced Return-Path (if set) for relay bounces */
116
120
  ReturnPath: string;
117
121
  /** The configured SMTP server address */
@@ -137,7 +141,7 @@ interface MailpitMessageSummaryResponse {
137
141
  /** Database ID */
138
142
  ID: string;
139
143
  /** Inline message attachements */
140
- Inline: MailpitEmailAddressResponse[];
144
+ Inline: MailpitAttachmentResponse[];
141
145
  /** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
142
146
  ListUnsubscribe: {
143
147
  /** Validation errors (if any) */
@@ -211,6 +215,8 @@ interface MailpitMessagesSummaryResponse {
211
215
  total: number;
212
216
  /** Total number of unread messages in mailbox */
213
217
  unread: number;
218
+ /** @deprecated No longer documented upstream */
219
+ count: number;
214
220
  }
215
221
  /** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
216
222
  interface MailpitMessageHeadersResponse {
@@ -335,7 +341,7 @@ interface MailpitLinkCheckResponse {
335
341
  /** Response from the {@link MailpitClient.spamAssassinCheck | spamAssassinCheck()} API containing containing SpamAssassin check results. */
336
342
  interface MailpitSpamAssassinResponse {
337
343
  /** If populated will return an error string */
338
- Errors: number;
344
+ Error: string;
339
345
  /** Whether the message is spam or not */
340
346
  IsSpam: boolean;
341
347
  /** Spam rules triggered */
@@ -395,7 +401,7 @@ interface MailpitChaosTriggersResponse {
395
401
  /** Response for the {@link MailpitClient.getMessageAttachment |getMessageAttachment()} and {@link MailpitClient.getAttachmentThumbnail | getAttachmentThumbnail()} APIs containing attachment data */
396
402
  interface MailpitAttachmentDataResponse {
397
403
  /** The attachment binary data */
398
- data: ArrayBuffer;
404
+ data: ArrayBuffer | Buffer;
399
405
  /** The attachment MIME type */
400
406
  contentType: string;
401
407
  }
@@ -409,7 +415,7 @@ interface MailpitAttachmentDataResponse {
409
415
  * ```
410
416
  */
411
417
  declare class MailpitClient {
412
- private axiosInstance;
418
+ private readonly axiosInstance;
413
419
  /**
414
420
  * Creates an instance of {@link MailpitClient}.
415
421
  * @param baseURL - The base URL of the Mailpit API.
@@ -656,7 +662,7 @@ declare class MailpitClient {
656
662
  * const linkCheck = await mailpit.linkCheck();
657
663
  * ```
658
664
  */
659
- linkCheck(id?: string, follow?: "true" | "false"): Promise<MailpitLinkCheckResponse>;
665
+ linkCheck(id?: string, follow?: boolean): Promise<MailpitLinkCheckResponse>;
660
666
  /**
661
667
  * Performs a SpamAssassin check (if enabled) on a specific message.
662
668
  * @param id - The message database ID. Defaults to `latest` to return the latest message.
package/dist/index.js CHANGED
@@ -399,7 +399,7 @@ var MailpitClient = class {
399
399
  * const linkCheck = await mailpit.linkCheck();
400
400
  * ```
401
401
  */
402
- async linkCheck(id = "latest", follow = "false") {
402
+ async linkCheck(id = "latest", follow = false) {
403
403
  return await this.handleRequest(
404
404
  () => this.axiosInstance.get(
405
405
  `/api/v1/message/${id}/link-check`,
package/dist/index.mjs CHANGED
@@ -367,7 +367,7 @@ var MailpitClient = class {
367
367
  * const linkCheck = await mailpit.linkCheck();
368
368
  * ```
369
369
  */
370
- async linkCheck(id = "latest", follow = "false") {
370
+ async linkCheck(id = "latest", follow = false) {
371
371
  return await this.handleRequest(
372
372
  () => this.axiosInstance.get(
373
373
  `/api/v1/message/${id}/link-check`,
package/package.json CHANGED
@@ -1,36 +1,53 @@
1
1
  {
2
2
  "name": "mailpit-api",
3
- "version": "1.4.0",
4
- "description": "A NodeJS client library, written in TypeScript, to interact with the Mailpit API.",
3
+ "version": "1.5.0",
4
+ "description": "A TypeScript client for interacting with Mailpit's REST API.",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "https://github.com/mpspahr/mailpit-api.git"
8
8
  },
9
+ "homepage": "https://mpspahr.github.io/mailpit-api/",
10
+ "bugs": {
11
+ "url": "https://github.com/mpspahr/mailpit-api/issues"
12
+ },
9
13
  "main": "dist/index.js",
10
14
  "module": "dist/index.mjs",
11
15
  "exports": {
12
16
  ".": {
13
- "import": "./dist/index.mjs",
14
- "require": "./dist/index.js"
17
+ "import": {
18
+ "types": "./dist/index.d.mts",
19
+ "default": "./dist/index.mjs"
20
+ },
21
+ "require": {
22
+ "types": "./dist/index.d.ts",
23
+ "default": "./dist/index.js"
24
+ }
15
25
  }
16
26
  },
17
27
  "scripts": {
18
- "test": "echo \"TODO: Add tests\" && exit 0",
28
+ "test:unit": "jest **/index.spec.ts",
29
+ "test:e2e": "jest **/e2e/index.e2e.spec.ts --runInBand",
30
+ "test": "jest",
31
+ "coverage": "jest --coverage",
19
32
  "build": "tsup src/index.ts --dts --format esm,cjs --outDir dist",
20
33
  "pretty": "npx prettier . --write",
21
- "lint": "npx eslint --fix src",
22
- "docs": "typedoc --readme none"
34
+ "lint": "npx eslint --fix src tests",
35
+ "docs": "typedoc"
23
36
  },
24
37
  "keywords": [
25
- "mailpit-api",
26
38
  "mailpit",
27
39
  "api",
28
40
  "client",
29
- "library",
30
- "wrapper",
31
41
  "email",
42
+ "smtp",
32
43
  "typescript",
33
- "nodejs"
44
+ "test",
45
+ "playwright",
46
+ "e2e",
47
+ "nodejs",
48
+ "testing",
49
+ "automation",
50
+ "integration"
34
51
  ],
35
52
  "author": "Matthew Spahr",
36
53
  "license": "MIT",
@@ -38,17 +55,20 @@
38
55
  "axios": "^1.9.0"
39
56
  },
40
57
  "devDependencies": {
41
- "@eslint/js": "^9.27.0",
42
- "@types/node": "^22.15.18",
43
- "eslint": "^9.27.0",
58
+ "@eslint/js": "^9.28.0",
59
+ "@jest/globals": "^29.7.0",
60
+ "@types/node": "^22.15.30",
61
+ "dotenv": "^16.5.0",
62
+ "eslint": "^9.28.0",
63
+ "eslint-plugin-jest": "^28.13.0",
44
64
  "jest": "^29.7.0",
45
65
  "prettier": "3.5.3",
66
+ "ts-jest": "^29.3.4",
46
67
  "tsup": "^8.5.0",
47
68
  "tsx": "^4.19.4",
48
- "typedoc": "^0.28.4",
49
- "typedoc-github-wiki-theme": "^2.1.0",
50
- "typedoc-plugin-markdown": "^4.6.3",
69
+ "typedoc": "^0.28.5",
70
+ "typedoc-github-theme": "^0.3.0",
51
71
  "typescript": "^5.8.3",
52
- "typescript-eslint": "^8.32.1"
72
+ "typescript-eslint": "^8.33.1"
53
73
  }
54
74
  }