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,
auth?: { password: string; username: string },
): MailpitClient
Creates an instance of MailpitClient.
Parameters
- baseURL: string
  The base URL of the Mailpit API.
- Optionalauth: { password: string; username: string }
  Optional authentication credentials.
  - password: string
    The password for basic authentication.
  - username: string
    The username for basic authentication.
Returns MailpitClient
Example: No Auth
```
const mailpit = new MailpitClient("http://localhost:8025");
```
Example: Basic Auth
```
const mailpit = new MailpitClient("http://localhost:8025", {
 username: "admin",
 password: "supersecret",
});
```
- Defined in index.ts:476

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:809

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:853

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
```
await mailpit.deleteTag("Tag 1");
```
Remarks
This does NOT delete any messages
- Defined in index.ts:987

getAttachmentThumbnail

getAttachmentThumbnail(
id: string,
partID: string,
): Promise<MailpitAttachmentDataResponse>
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<MailpitAttachmentDataResponse>
Image attachment thumbnail as binary data and the content type
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 thumbnail = await mailpit.getAttachmentThumbnail(message.ID, message.Attachments[0].PartID);
 // Do something with the thumbnail data
}
```
- Defined in index.ts:653

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:1003

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:558

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:543

getMessageAttachment

getMessageAttachment(
id: string,
partID: string,
): Promise<MailpitAttachmentDataResponse>
Retrieves a specific attachment from a message.
Parameters
- id: string
  Message database ID or "latest"
- partID: string
  The attachment part ID
Returns Promise<MailpitAttachmentDataResponse>
Attachment as binary data and the content type
Example
```
const message = await mailpit.getMessageSummary();
if (message.Attachments.length) {
 const attachment = await mailpit.getMessageAttachment(message.ID, message.Attachments[0].PartID);
 // Do something with the attachment data
}
```
- Defined in index.ts:617

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:593

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:682

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:573

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:929

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:870

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:890

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.listMessages();
```
- Defined in index.ts:744

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:699

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:969

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:1051

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:1069

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:832

sendMessage

sendMessage(
sendReqest: MailpitSendRequest,
): Promise<MailpitSendMessageConfirmationResponse>
Sends a message
Parameters
- sendReqest: MailpitSendRequest
  The request containing the message details.
Returns Promise<MailpitSendMessageConfirmationResponse>
Response containing database messsage 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:721

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:1022

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:784

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:950

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:911

Class MailpitClient

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

password: string

username: string

Returns MailpitClient

Example: No Auth

Example: Basic Auth

Methods

deleteMessages

Parameters

Returns Promise<string>

Remarks

Example

deleteMessagesBySearch

Parameters

Returns Promise<string>

See

Example

deleteTag

Parameters

Returns Promise<string>

Remarks

getAttachmentThumbnail

Parameters

Returns Promise<MailpitAttachmentDataResponse>

Remarks

Example

getChaosTriggers

Returns Promise<MailpitChaosTriggersResponse>

Remarks

Example

getConfiguration

Returns Promise<MailpitConfigurationResponse>

Remarks

Example

getInfo

Returns Promise<MailpitInfoResponse>

Example

getMessageAttachment

Parameters

Returns Promise<MailpitAttachmentDataResponse>

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

See

Example

releaseMessage

Parameters

`Optional`IDs?: string[]

`Optional`Read?: boolean

`Optional`Search?: string