mailpit-api 1.4.0 → 1.5.1
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/README.md +72 -10
- package/dist/index.d.mts +13 -5
- package/dist/index.d.ts +13 -5
- package/dist/index.js +1 -1
- package/dist/index.mjs +1 -1
- package/package.json +48 -21
package/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Mailpit API Client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/mailpit-api)
|
|
4
|
+
[](https://github.com/mpspahr/mailpit-api/actions/workflows/npm-publish.yml)
|
|
5
|
+
[](https://codecov.io/gh/mpspahr/mailpit-api)
|
|
6
|
+
[](https://mpspahr.github.io/mailpit-api/)
|
|
4
7
|
|
|
5
|
-
[
|
|
6
|
-
[](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
|
-
##
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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,10 @@ interface MailpitConfigurationResponse {
|
|
|
112
114
|
Enabled: boolean;
|
|
113
115
|
/** Overrides the "From" address for all relayed messages */
|
|
114
116
|
OverrideFrom: string;
|
|
117
|
+
/** Preserve the original Message-IDs when relaying messages */
|
|
118
|
+
PreserveMessageIDs: boolean;
|
|
119
|
+
/** @deprecated Refer to `AllowedRecipients` instead. No longer documented upstream */
|
|
120
|
+
RecipientAllowlist: string;
|
|
115
121
|
/** Enforced Return-Path (if set) for relay bounces */
|
|
116
122
|
ReturnPath: string;
|
|
117
123
|
/** The configured SMTP server address */
|
|
@@ -137,7 +143,7 @@ interface MailpitMessageSummaryResponse {
|
|
|
137
143
|
/** Database ID */
|
|
138
144
|
ID: string;
|
|
139
145
|
/** Inline message attachements */
|
|
140
|
-
Inline:
|
|
146
|
+
Inline: MailpitAttachmentResponse[];
|
|
141
147
|
/** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
|
|
142
148
|
ListUnsubscribe: {
|
|
143
149
|
/** Validation errors (if any) */
|
|
@@ -211,6 +217,8 @@ interface MailpitMessagesSummaryResponse {
|
|
|
211
217
|
total: number;
|
|
212
218
|
/** Total number of unread messages in mailbox */
|
|
213
219
|
unread: number;
|
|
220
|
+
/** @deprecated No longer documented upstream */
|
|
221
|
+
count: number;
|
|
214
222
|
}
|
|
215
223
|
/** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
|
|
216
224
|
interface MailpitMessageHeadersResponse {
|
|
@@ -335,7 +343,7 @@ interface MailpitLinkCheckResponse {
|
|
|
335
343
|
/** Response from the {@link MailpitClient.spamAssassinCheck | spamAssassinCheck()} API containing containing SpamAssassin check results. */
|
|
336
344
|
interface MailpitSpamAssassinResponse {
|
|
337
345
|
/** If populated will return an error string */
|
|
338
|
-
|
|
346
|
+
Error: string;
|
|
339
347
|
/** Whether the message is spam or not */
|
|
340
348
|
IsSpam: boolean;
|
|
341
349
|
/** Spam rules triggered */
|
|
@@ -395,7 +403,7 @@ interface MailpitChaosTriggersResponse {
|
|
|
395
403
|
/** Response for the {@link MailpitClient.getMessageAttachment |getMessageAttachment()} and {@link MailpitClient.getAttachmentThumbnail | getAttachmentThumbnail()} APIs containing attachment data */
|
|
396
404
|
interface MailpitAttachmentDataResponse {
|
|
397
405
|
/** The attachment binary data */
|
|
398
|
-
data: ArrayBuffer;
|
|
406
|
+
data: ArrayBuffer | Buffer;
|
|
399
407
|
/** The attachment MIME type */
|
|
400
408
|
contentType: string;
|
|
401
409
|
}
|
|
@@ -409,7 +417,7 @@ interface MailpitAttachmentDataResponse {
|
|
|
409
417
|
* ```
|
|
410
418
|
*/
|
|
411
419
|
declare class MailpitClient {
|
|
412
|
-
private axiosInstance;
|
|
420
|
+
private readonly axiosInstance;
|
|
413
421
|
/**
|
|
414
422
|
* Creates an instance of {@link MailpitClient}.
|
|
415
423
|
* @param baseURL - The base URL of the Mailpit API.
|
|
@@ -656,7 +664,7 @@ declare class MailpitClient {
|
|
|
656
664
|
* const linkCheck = await mailpit.linkCheck();
|
|
657
665
|
* ```
|
|
658
666
|
*/
|
|
659
|
-
linkCheck(id?: string, follow?:
|
|
667
|
+
linkCheck(id?: string, follow?: boolean): Promise<MailpitLinkCheckResponse>;
|
|
660
668
|
/**
|
|
661
669
|
* Performs a SpamAssassin check (if enabled) on a specific message.
|
|
662
670
|
* @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,10 @@ interface MailpitConfigurationResponse {
|
|
|
112
114
|
Enabled: boolean;
|
|
113
115
|
/** Overrides the "From" address for all relayed messages */
|
|
114
116
|
OverrideFrom: string;
|
|
117
|
+
/** Preserve the original Message-IDs when relaying messages */
|
|
118
|
+
PreserveMessageIDs: boolean;
|
|
119
|
+
/** @deprecated Refer to `AllowedRecipients` instead. No longer documented upstream */
|
|
120
|
+
RecipientAllowlist: string;
|
|
115
121
|
/** Enforced Return-Path (if set) for relay bounces */
|
|
116
122
|
ReturnPath: string;
|
|
117
123
|
/** The configured SMTP server address */
|
|
@@ -137,7 +143,7 @@ interface MailpitMessageSummaryResponse {
|
|
|
137
143
|
/** Database ID */
|
|
138
144
|
ID: string;
|
|
139
145
|
/** Inline message attachements */
|
|
140
|
-
Inline:
|
|
146
|
+
Inline: MailpitAttachmentResponse[];
|
|
141
147
|
/** ListUnsubscribe contains a summary of List-Unsubscribe & List-Unsubscribe-Post headers including validation of the link structure */
|
|
142
148
|
ListUnsubscribe: {
|
|
143
149
|
/** Validation errors (if any) */
|
|
@@ -211,6 +217,8 @@ interface MailpitMessagesSummaryResponse {
|
|
|
211
217
|
total: number;
|
|
212
218
|
/** Total number of unread messages in mailbox */
|
|
213
219
|
unread: number;
|
|
220
|
+
/** @deprecated No longer documented upstream */
|
|
221
|
+
count: number;
|
|
214
222
|
}
|
|
215
223
|
/** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
|
|
216
224
|
interface MailpitMessageHeadersResponse {
|
|
@@ -335,7 +343,7 @@ interface MailpitLinkCheckResponse {
|
|
|
335
343
|
/** Response from the {@link MailpitClient.spamAssassinCheck | spamAssassinCheck()} API containing containing SpamAssassin check results. */
|
|
336
344
|
interface MailpitSpamAssassinResponse {
|
|
337
345
|
/** If populated will return an error string */
|
|
338
|
-
|
|
346
|
+
Error: string;
|
|
339
347
|
/** Whether the message is spam or not */
|
|
340
348
|
IsSpam: boolean;
|
|
341
349
|
/** Spam rules triggered */
|
|
@@ -395,7 +403,7 @@ interface MailpitChaosTriggersResponse {
|
|
|
395
403
|
/** Response for the {@link MailpitClient.getMessageAttachment |getMessageAttachment()} and {@link MailpitClient.getAttachmentThumbnail | getAttachmentThumbnail()} APIs containing attachment data */
|
|
396
404
|
interface MailpitAttachmentDataResponse {
|
|
397
405
|
/** The attachment binary data */
|
|
398
|
-
data: ArrayBuffer;
|
|
406
|
+
data: ArrayBuffer | Buffer;
|
|
399
407
|
/** The attachment MIME type */
|
|
400
408
|
contentType: string;
|
|
401
409
|
}
|
|
@@ -409,7 +417,7 @@ interface MailpitAttachmentDataResponse {
|
|
|
409
417
|
* ```
|
|
410
418
|
*/
|
|
411
419
|
declare class MailpitClient {
|
|
412
|
-
private axiosInstance;
|
|
420
|
+
private readonly axiosInstance;
|
|
413
421
|
/**
|
|
414
422
|
* Creates an instance of {@link MailpitClient}.
|
|
415
423
|
* @param baseURL - The base URL of the Mailpit API.
|
|
@@ -656,7 +664,7 @@ declare class MailpitClient {
|
|
|
656
664
|
* const linkCheck = await mailpit.linkCheck();
|
|
657
665
|
* ```
|
|
658
666
|
*/
|
|
659
|
-
linkCheck(id?: string, follow?:
|
|
667
|
+
linkCheck(id?: string, follow?: boolean): Promise<MailpitLinkCheckResponse>;
|
|
660
668
|
/**
|
|
661
669
|
* Performs a SpamAssassin check (if enabled) on a specific message.
|
|
662
670
|
* @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 =
|
|
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 =
|
|
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,54 +1,81 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mailpit-api",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "A
|
|
3
|
+
"version": "1.5.1",
|
|
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
|
+
},
|
|
13
|
+
"publishConfig": {
|
|
14
|
+
"registry": "https://registry.npmjs.org/",
|
|
15
|
+
"provenance": true
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=18.0.0"
|
|
19
|
+
},
|
|
9
20
|
"main": "dist/index.js",
|
|
10
21
|
"module": "dist/index.mjs",
|
|
11
22
|
"exports": {
|
|
12
23
|
".": {
|
|
13
|
-
"import":
|
|
14
|
-
|
|
24
|
+
"import": {
|
|
25
|
+
"types": "./dist/index.d.mts",
|
|
26
|
+
"default": "./dist/index.mjs"
|
|
27
|
+
},
|
|
28
|
+
"require": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"default": "./dist/index.js"
|
|
31
|
+
}
|
|
15
32
|
}
|
|
16
33
|
},
|
|
17
34
|
"scripts": {
|
|
18
|
-
"test
|
|
35
|
+
"test:unit": "jest **/index.spec.ts",
|
|
36
|
+
"test:e2e": "jest **/e2e/index.e2e.spec.ts --runInBand",
|
|
37
|
+
"test": "jest",
|
|
38
|
+
"coverage": "jest --coverage",
|
|
19
39
|
"build": "tsup src/index.ts --dts --format esm,cjs --outDir dist",
|
|
20
40
|
"pretty": "npx prettier . --write",
|
|
21
|
-
"lint": "npx eslint --fix src",
|
|
22
|
-
"docs": "typedoc
|
|
41
|
+
"lint": "npx eslint --fix src tests",
|
|
42
|
+
"docs": "typedoc"
|
|
23
43
|
},
|
|
24
44
|
"keywords": [
|
|
25
|
-
"mailpit-api",
|
|
26
45
|
"mailpit",
|
|
27
46
|
"api",
|
|
28
47
|
"client",
|
|
29
|
-
"library",
|
|
30
|
-
"wrapper",
|
|
31
48
|
"email",
|
|
49
|
+
"smtp",
|
|
32
50
|
"typescript",
|
|
33
|
-
"
|
|
51
|
+
"test",
|
|
52
|
+
"playwright",
|
|
53
|
+
"e2e",
|
|
54
|
+
"nodejs",
|
|
55
|
+
"testing",
|
|
56
|
+
"automation",
|
|
57
|
+
"integration"
|
|
34
58
|
],
|
|
35
59
|
"author": "Matthew Spahr",
|
|
36
60
|
"license": "MIT",
|
|
37
61
|
"dependencies": {
|
|
38
|
-
"axios": "^1.
|
|
62
|
+
"axios": "^1.10.0"
|
|
39
63
|
},
|
|
40
64
|
"devDependencies": {
|
|
41
|
-
"@eslint/js": "^9.
|
|
42
|
-
"@
|
|
43
|
-
"
|
|
44
|
-
"
|
|
65
|
+
"@eslint/js": "^9.29.0",
|
|
66
|
+
"@jest/globals": "^30.0.0",
|
|
67
|
+
"@types/node": "^22.15.31",
|
|
68
|
+
"dotenv": "^16.5.0",
|
|
69
|
+
"eslint": "^9.29.0",
|
|
70
|
+
"eslint-plugin-jest": "^28.14.0",
|
|
71
|
+
"jest": "^30.0.0",
|
|
45
72
|
"prettier": "3.5.3",
|
|
73
|
+
"ts-jest": "^29.4.0",
|
|
46
74
|
"tsup": "^8.5.0",
|
|
47
|
-
"tsx": "^4.
|
|
48
|
-
"typedoc": "^0.28.
|
|
49
|
-
"typedoc-github-
|
|
50
|
-
"typedoc-plugin-markdown": "^4.6.3",
|
|
75
|
+
"tsx": "^4.20.3",
|
|
76
|
+
"typedoc": "^0.28.5",
|
|
77
|
+
"typedoc-github-theme": "^0.3.0",
|
|
51
78
|
"typescript": "^5.8.3",
|
|
52
|
-
"typescript-eslint": "^8.
|
|
79
|
+
"typescript-eslint": "^8.34.0"
|
|
53
80
|
}
|
|
54
81
|
}
|