Class MailpitClient

Client for interacting with the Mailpit API.

Example

import { MailpitClient } from "mailpit-api";
const mailpit = new MailpitClient("http://localhost:8025");
console.log(await mailpit.getInfo());

Constructors

constructor

new MailpitClient(
baseURL: string,
options?: MailpitClientOptions,
): MailpitClient
Creates an instance of MailpitClient.
Parameters
- baseURL: string
  The base URL of the Mailpit API.
- Optionaloptions: MailpitClientOptions
  Optional configuration including auth credentials and fetch options.
  
  Options for a MailpitClient instance.
  - Optionalauth?: MailpitAuthCredentials
    Optional basic auth credentials.
  - OptionalfetchOptions?: Omit<RequestInit, "method" | "body">
    Optional fetch options merged into every request. method and body are managed internally and cannot be overridden. Any headers provided here are merged with internally managed headers (Authorization, Content-Type), with internal headers taking precedence.
    
    Example: Setting cookies
    { fetchOptions: { headers: { Cookie: "session=abc123" } } }
    
    Example: Disabling TLS verification in Node.js (undici `Agent`)
    import { Agent } from "undici"; { fetchOptions: { dispatcher: new Agent({ connect: { rejectUnauthorized: false } }) } }
Returns MailpitClient
Example: No Auth
```
const mailpit = new MailpitClient("http://localhost:8025");
```
Example: Basic Auth
```
const mailpit = new MailpitClient("http://localhost:8025", {
  auth: { username: "admin", password: "supersecret" }
});
```
Example: Custom cookies and disabled TLS verification (Node.js only)
```
import { Agent } from "undici";
const mailpit = new MailpitClient("https://localhost:8025", {
  fetchOptions: {
    headers: { Cookie: "session=abc123" },
    dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
  }
});
```
- Defined in index.ts:564

Methods

deleteMessages

deleteMessages(deleteRequest?: MailpitDatabaseIDsRequest): Promise<string>
Delete individual or all messages.
Parameters
- OptionaldeleteRequest: MailpitDatabaseIDsRequest
  The request containing the message database IDs to delete.
Returns Promise<string>
Plain text "ok" response
Remarks
If no IDs are provided then all messages are deleted.
Example
```
// Delete all messages
await mailpit.deleteMessages();

// Delete specific messages
await mailpit.deleteMessages({ IDs: ["1", "2", "3"] });
```
- Defined in index.ts:924

deleteMessagesBySearch

deleteMessagesBySearch(search: MailpitSearchRequest): Promise<string>
Delete all messages matching a search.
Parameters
- search: MailpitSearchRequest
  The search request containing the query.
Returns Promise<string>
Plain text "ok" response
See
Search filters
Example
```
// Delete all messages from the domain example.test
await mailpit.deleteMessagesBySearch({query: "from:example.test"});
```
- Defined in index.ts:1098

deleteTag

deleteTag(tag: string): Promise<string>
Deletes a tag from all messages.
Parameters
- tag: string
  The name of the tag to delete.
Returns Promise<string>
Plain text "ok" response
Remarks
This does NOT delete any messages
Example
```
await mailpit.deleteTag("Tag 1");
```
- Defined in index.ts:1229

getAttachmentThumbnail

getAttachmentThumbnail(id: string, partID: string): Promise<Blob>
Generates a cropped 180x120 JPEG thumbnail of an image attachment from a message. Only image attachments are supported.
Parameters
- id: string
  Message database ID or "latest"
- partID: string
  The attachment part ID
Returns Promise<Blob>
The thumbnail as a Blob. Use blob.type for the MIME type (always image/jpeg).
Remarks
If the image is smaller than 180x120 then the image is padded. If the attachment is not an image then a blank image is returned.
Example
```
const message = await mailpit.getMessageSummary();
if (message.Attachments.length) {
  const blob = await mailpit.getAttachmentThumbnail(message.ID, message.Attachments[0].PartID);
  // Browser: const url = URL.createObjectURL(blob);
  // Node.js: const buffer = Buffer.from(await blob.arrayBuffer());
}
```
- Defined in index.ts:778

getChaosTriggers

getChaosTriggers(): Promise<MailpitChaosTriggersResponse>
Retrieves the current Chaos triggers configuration (if enabled).

Returns Promise<MailpitChaosTriggersResponse>
The Chaos triggers configuration
Remarks
This will return an error if Chaos is not enabled at runtime.
Example
```
const triggers = await mailpit.getChaosTriggers();
```
- Defined in index.ts:1245

getConfiguration

getConfiguration(): Promise<MailpitConfigurationResponse>
Retrieves the configuration of the Mailpit web UI.

Returns Promise<MailpitConfigurationResponse>
Configuration settings
Remarks
Intended for web UI only!
Example
```
const config = await mailpit.getConfiguration();
```
- Defined in index.ts:693

getInfo

getInfo(): Promise<MailpitInfoResponse>
Retrieves information about the Mailpit instance.

Returns Promise<MailpitInfoResponse>
Basic runtime information, message totals and latest release version.
Example
```
const info = await mailpit.getInfo();
```
- Defined in index.ts:680

getMessageAttachment

getMessageAttachment(id: string, partID: string): Promise<Blob>

Retrieves a specific attachment from a message.

Parameters

id: string
Message database ID or "latest"
partID: string
The attachment part ID

Returns Promise<Blob>

The attachment as a Blob. Use blob.type for the MIME type.

Example

const message = await mailpit.getMessageSummary();
if (message.Attachments.length) {
  const blob = await mailpit.getMessageAttachment(message.ID, message.Attachments[0].PartID);
  console.log(blob.type); // e.g. "application/pdf"
  // Browser: const url = URL.createObjectURL(blob);
  // Node.js: const buffer = Buffer.from(await blob.arrayBuffer());
}

getMessageHeaders

getMessageHeaders(id?: string): Promise<MailpitMessageHeadersResponse>
Retrieves the headers of a specific message.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<MailpitMessageHeadersResponse>
Message headers
Remarks
Header keys are returned alphabetically.
Example
```
const headers = await mailpit.getMessageHeaders();
```
- Defined in index.ts:728

getMessageSource

getMessageSource(id?: string): Promise<string>
Retrieves the full email message source as plain text.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<string>
Plain text message source
Example
```
const messageSource = await mailpit.getMessageSource();
```
- Defined in index.ts:798

getMessageSummary

getMessageSummary(id?: string): Promise<MailpitMessageSummaryResponse>
Retrieves a summary of a specific message and marks it as read.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<MailpitMessageSummaryResponse>
Message summary
Example
```
const message = await mailpit.getMessageSummary();
```
- Defined in index.ts:709

getTags

getTags(): Promise<string[]>
Retrieves a list of all the unique tags.

Returns Promise<string[]>
All unique message tags
Example
```
const tags = await mailpit.getTags();
```
- Defined in index.ts:1172

htmlCheck

htmlCheck(id?: string): Promise<MailpitHTMLCheckResponse>
Performs an HTML check on a specific message.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<MailpitHTMLCheckResponse>
The summary of the message HTML checker
Example
```
const htmlCheck = await mailpit.htmlCheck();
```
- Defined in index.ts:1116

linkCheck

linkCheck(id?: string, follow?: boolean): Promise<MailpitLinkCheckResponse>
Performs a link check on a specific message.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
- follow: boolean = false
  Whether to follow links. Defaults to false.
Returns Promise<MailpitLinkCheckResponse>
The summary of the message Link checker.
Example
```
const linkCheck = await mailpit.linkCheck();
```
- Defined in index.ts:1135

listMessages

listMessages(
start?: number,
limit?: number,
): Promise<MailpitMessagesSummaryResponse>
Retrieves a list of message summaries ordered from newest to oldest.
Parameters
- start: number = 0
  The pagination offset. Defaults to 0.
- limit: number = 50
  The number of messages to retrieve. Defaults to 50.
Returns Promise<MailpitMessagesSummaryResponse>
A list of message summaries
Remarks
Only contains the number of attachments and a snippet of the message body.

See
getMessageSummary() for more attachment and body details for a specific message.
Example
```
const messages = await mailpit.listMessages();
```
- Defined in index.ts:860

releaseMessage

releaseMessage(id: string, relayTo: { To: string[] }): Promise<string>
Release a message via a pre-configured external SMTP server.
Parameters
- id: string
  The message database ID. Use latest to return the latest message.
- relayTo: { To: string[] }
  Array of email addresses to relay the message to
Returns Promise<string>
Plain text "ok" response
Remarks
This is only enabled if message relaying has been configured.
Example
```
const message = await mailpit.releaseMessage("latest", ["user1@example.test", "user2@example.test"]);
```
- Defined in index.ts:815

renameTag

renameTag(tag: string, newTagName: string): Promise<string>
Renames an existing tag.
Parameters
- tag: string
  The current name of the tag.
- newTagName: string
  A new name for the tag.
Returns Promise<string>
Plain text "ok" response
Remarks
Tags are limited to the following characters: a-z, A-Z, 0-9, -, ., spaces, and _, and must be a minimum of 1 character. Other characters are silently stripped from the tag.
Example
```
await mailpit.renameTag("Old Tag Name", "New Tag Name");
```
- Defined in index.ts:1211

renderMessageHTML

renderMessageHTML(id?: string, embed?: 1): Promise<string>
Renders the HTML part of a specific message which can be used for UI integration testing.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
- Optionalembed: 1
  Whether this route is to be embedded in an iframe. Defaults to undefined. Set to 1 to embed. The embed parameter will add target="_blank" and rel="noreferrer noopener" to all links. In addition, a small script will be added to the end of the document to post (postMessage()) the height of the document back to the parent window for optional iframe height resizing. Note that this will also transform the message into a full HTML document (if it isn't already), so this option is useful for viewing but not programmatic testing.
Returns Promise<string>
Rendered HTML
Remarks
Attached inline images are modified to link to the API provided they exist. If the message does not contain an HTML part then a 404 error is returned.
Example
```
const html = await mailpit.renderMessageHTML();
```
- Defined in index.ts:1293

renderMessageText

renderMessageText(id?: string): Promise<string>
Renders just the message's text part which can be used for UI integration testing.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<string>
Plain text
Example
```
const html = await mailpit.renderMessageText();
```
- Defined in index.ts:1312

searchMessages

searchMessages(
search: MailpitSearchMessagesRequest,
): Promise<MailpitMessagesSummaryResponse>
Retrieve messages matching a search, sorted by received date (descending).
Parameters
- search: MailpitSearchMessagesRequest
  The search request containing the query and optional parameters.
Returns Promise<MailpitMessagesSummaryResponse>
A list of message summaries matching the search criteria.
See
- Search filters
- getMessageSummary() for more attachment and body details for a specific message.
Remarks
Only contains the number of attachments and a snippet of the message body.
Example
```
// Search for messages from a the domain example.test
const messages = await mailpit.searchMessages({query: "from:example.test"});
```
- Defined in index.ts:946

sendMessage

sendMessage(
sendRequest: MailpitSendRequest,
): Promise<MailpitSendMessageConfirmationResponse>
Sends a message
Parameters
- sendRequest: MailpitSendRequest
  The request containing the message details.
Returns Promise<MailpitSendMessageConfirmationResponse>
Response containing database message ID
Example
```
await mailpit.sendMessage(
 From: { Email: "user@example.test", Name: "First LastName" },
 To: [{ Email: "rec@example.test", Name: "Recipient Name"}, {Email: "another@example.test"}],
 Subject: "Test Email",
);
```
- Defined in index.ts:838

setChaosTriggers

setChaosTriggers(
triggers?: MailpitChaosTriggersRequest,
): Promise<MailpitChaosTriggersResponse>
Sets and/or resets the Chaos triggers configuration (if enabled).
Parameters
- triggers: MailpitChaosTriggersRequest = {}
  The request containing the chaos triggers. Omitted triggers will reset to the default 0% probabibility.
Returns Promise<MailpitChaosTriggersResponse>
The updated Chaos triggers configuration
Remarks
This will return an error if Chaos is not enabled at runtime.
Example
```
// Reset all triggers to `0%` probability
const triggers = await mailpit.setChaosTriggers();
// Set `Sender` and reset `Authentication` and `Recipient` triggers
const triggers = await mailpit.setChaosTriggers({ Sender: { ErrorCode: 451, Probability: 5 } });
```
- Defined in index.ts:1265

setReadStatus

setReadStatus(
readStatus?: MailpitReadStatusRequest,
params?: MailpitTimeZoneRequest,
): Promise<string>
Set the read status of messages.
Parameters
- readStatus: MailpitReadStatusRequest = {}
  The request containing the message database IDs/search string and the read status.
  
  Request parameters for the setReadStatus() API.
  - OptionalIDs?: string[]
    Array of message database IDs
  - OptionalRead?: boolean
    Read status
    
    Default Value
    false
  - OptionalSearch?: string
    Search filter
- Optionalparams: MailpitTimeZoneRequest
  Optional parameters for defining the time zone when using the before: and after: search filters.
Returns Promise<string>
Plain text "ok" response
Remarks
You can optionally provide an array of IDs OR a Search filter. If neither is set then all messages are updated.

See
Search filters
Example
```
// Set all messages as unread
await mailpit.setReadStatus();

// Set all messages as read
await mailpit.setReadStatus({ Read: true });

// 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" });
```
- Defined in index.ts:899

setTags

setTags(request: MailpitSetTagsRequest): Promise<string>
Sets and removes tag(s) on message(s). This will overwrite any existing tags for selected message database IDs.
Parameters
- request: MailpitSetTagsRequest
  The request containing the message IDs and tags. To remove all tags from a message, pass an empty Tags array or exclude Tags entirely.
Returns Promise<string>
Plain text "ok" response
Remarks
Tags are limited to the following characters: a-z, A-Z, 0-9, -, ., spaces, and _, and must be a minimum of 1 character. Other characters are silently stripped from the tag.
Example
```
// Set tags on message(s)
await mailpit.setTags({ IDs: ["1", "2", "3"], Tags: ["tag1", "tag2"] });
// Remove tags from message(s)
await mailpit.setTags({ IDs: ["1", "2", "3"]});
```
- Defined in index.ts:1191

spamAssassinCheck

spamAssassinCheck(id?: string): Promise<MailpitSpamAssassinResponse>
Performs a SpamAssassin check (if enabled) on a specific message.
Parameters
- id: string = "latest"
  The message database ID. Defaults to latest to return the latest message.
Returns Promise<MailpitSpamAssassinResponse>
The SpamAssassin summary (if enabled)
Example
```
const spamAssassinCheck = await mailpit.spamAssassinCheck();
```
- Defined in index.ts:1155

waitForMessage

waitForMessage(
search: MailpitSearchMessagesRequest,
options?: MailpitWaitForMessageRequest,
): Promise<MailpitMessageSummaryResponse>
Waits for at least one message matching a search query, then returns the latest matching message.
Parameters
- search: MailpitSearchMessagesRequest
  The search request containing the query and optional parameters.
- Optionaloptions: MailpitWaitForMessageRequest
  Optional timeout and interval settings.
Returns Promise<MailpitMessageSummaryResponse>
The full message summary of the latest matching message.
Remarks
Polls the searchMessages() API at a configurable interval until at least one message is found, then retrieves the full message details via getMessageSummary(). The promise will reject if the timeout is reached before a matching message is found.

See
Search filters
Example
```
// Trigger an email, then wait for it
await mailpit.sendMessage({
  From: { Email: "test@example.test" },
  To: [{ Email: "recipient@example.test" }],
  Subject: "Welcome",
});
const message = await mailpit.waitForMessage({ query: "subject:Welcome" });
console.log(message.Subject); // "Welcome"
```
- Defined in index.ts:978

waitForMessages

waitForMessages(
options?: MailpitWaitForMessageRequest,
): Promise<MailpitMessagesSummaryResponse>
Waits for a specific number of messages to exist, optionally matching a search query.
Parameters
- Optionaloptions: MailpitWaitForMessageRequest
  Optional timeout and interval settings.
Returns Promise<MailpitMessagesSummaryResponse>
The message list response that satisfied the count condition.
Remarks
Polls the searchMessages() (if search is provided) or listMessages() API at a configurable interval until the count condition is met. The promise will reject if the timeout is reached before the condition is satisfied.

By default, resolves when messages_count >= count. Set exact: true to require messages_count === count. When count is 0, always uses exact match (messages_count === 0) regardless of the exact option.

See
Search filters
Example: Wait for at least two messages matching a search
```
const response = await mailpit.waitForMessages({ query: "to:user@example.test", count: 2 });
console.log(response.messages_count); // 2 or more
```
Example: Wait for exactly three messages matching a search
```
const response = await mailpit.waitForMessages({ query: "from:example.test", count: 3, exact: true });
console.log(response.messages_count); // 3
```
Example: Wait for an empty mailbox
```
await mailpit.deleteMessages();
const response = await mailpit.waitForMessages({ count: 0 });
console.log(response.messages_count); // 0
```
Example: Wait until no messages match a search query
```
await mailpit.deleteMessagesBySearch({ query: "from:example.test" });
const response = await mailpit.waitForMessages({ query: "from:example.test", count: 0 });
console.log(response.messages_count); // 0
```
Example: Wait for at least one message with a custom timeout and interval only
```
const response = await mailpit.waitForMessages({ timeout: 10_000, interval: 1_000 });
console.log(response.messages_count); // 1 or more
```
- Defined in index.ts:1036
waitForMessages(
request: MailpitWaitForMessagesRequest,
options?: MailpitWaitForMessageRequest,
): Promise<MailpitMessagesSummaryResponse>
Waits for a specific number of messages to exist, optionally matching a search query.
Parameters
- request: MailpitWaitForMessagesRequest
- Optionaloptions: MailpitWaitForMessageRequest
  Optional timeout and interval settings.
Returns Promise<MailpitMessagesSummaryResponse>
The message list response that satisfied the count condition.
Remarks
Polls the searchMessages() (if search is provided) or listMessages() API at a configurable interval until the count condition is met. The promise will reject if the timeout is reached before the condition is satisfied.

By default, resolves when messages_count >= count. Set exact: true to require messages_count === count. When count is 0, always uses exact match (messages_count === 0) regardless of the exact option.

See
Search filters
Example: Wait for at least two messages matching a search
```
const response = await mailpit.waitForMessages({ query: "to:user@example.test", count: 2 });
console.log(response.messages_count); // 2 or more
```
Example: Wait for exactly three messages matching a search
```
const response = await mailpit.waitForMessages({ query: "from:example.test", count: 3, exact: true });
console.log(response.messages_count); // 3
```
Example: Wait for an empty mailbox
```
await mailpit.deleteMessages();
const response = await mailpit.waitForMessages({ count: 0 });
console.log(response.messages_count); // 0
```
Example: Wait until no messages match a search query
```
await mailpit.deleteMessagesBySearch({ query: "from:example.test" });
const response = await mailpit.waitForMessages({ query: "from:example.test", count: 0 });
console.log(response.messages_count); // 0
```
Example: Wait for at least one message with a custom timeout and interval only
```
const response = await mailpit.waitForMessages({ timeout: 10_000, interval: 1_000 });
console.log(response.messages_count); // 1 or more
```
- Defined in index.ts:1039

Class MailpitClient

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Optionalauth?: MailpitAuthCredentials

OptionalfetchOptions?: Omit<RequestInit, "method" | "body">

Example: Setting cookies

Example: Disabling TLS verification in Node.js (undici `Agent`)

Returns MailpitClient

Example: No Auth

Example: Basic Auth

Example: Custom cookies and disabled TLS verification (Node.js only)

Methods

deleteMessages

Parameters

Returns Promise<string>

Remarks

Example

deleteMessagesBySearch

Parameters

Returns Promise<string>

See

Example

deleteTag

Parameters

Returns Promise<string>

Remarks

Example

getAttachmentThumbnail

Parameters

Returns Promise<Blob>

Remarks

Example

getChaosTriggers

Returns Promise<MailpitChaosTriggersResponse>

Remarks

Example

getConfiguration

Returns Promise<MailpitConfigurationResponse>

Remarks

Example

getInfo

Returns Promise<MailpitInfoResponse>

Example

getMessageAttachment

Parameters

Returns Promise<Blob>

Example

getMessageHeaders

Parameters

Returns Promise<MailpitMessageHeadersResponse>

Remarks

Example

getMessageSource

Parameters

Returns Promise<string>

Example

getMessageSummary

Parameters

Returns Promise<MailpitMessageSummaryResponse>

Example

getTags

Returns Promise<string[]>

Example

htmlCheck

Parameters

Returns Promise<MailpitHTMLCheckResponse>

Example

linkCheck

Parameters

Returns Promise<MailpitLinkCheckResponse>

Example

listMessages

Parameters

Returns Promise<MailpitMessagesSummaryResponse>

Remarks

`Optional`auth?: MailpitAuthCredentials

`Optional`fetchOptions?: Omit<RequestInit, "method" | "body">

`Optional`IDs?: string[]

`Optional`Read?: boolean

`Optional`Search?: string