HTTP API

The HTTP server hosts both the Web UI and JSON API on the configured HTTP host and port.

Health

GET /api/health

Returns:

{ "status": "ok" }

Connection settings

GET /api/connection

Returns the SMTP connection settings currently used by the server.

Message events

GET /api/events

Opens a Server-Sent Events stream for mailbox updates.

List messages

GET /api/messages

Supported query parameters:

Parameter	Description
q	Search text.
from	Filter by sender using a case-insensitive partial match.
to	Filter To, Cc, and Bcc recipients using a case-insensitive partial match.
subject	Filter by subject using a case-insensitive partial match.
hasAttachments	Use true or false to filter by attachment presence.
receivedAfter	Filter messages received at or after an ISO 8601 timestamp.
receivedBefore	Filter messages received before an ISO 8601 timestamp.
sortBy	Sort by receivedAt, subject, from, or rawSizeBytes. Defaults to receivedAt.
sortOrder	Sort in asc or desc order. Defaults to desc.
page	Page number starting at 1. Defaults to 1.
pageSize	Messages per page. Defaults to 50 and cannot exceed 100.

The response includes message summaries and pagination metadata:

{
  "messages": [],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 0,
    "totalPages": 0
  }
}

Clear messages

DELETE /api/messages

Deletes all retained messages.

Get a message

GET /api/messages/:id

Returns message details for a captured message.

Delete a message

DELETE /api/messages/:id

Deletes a captured message.

Download an attachment

GET /api/messages/:id/attachments/:attachmentId

Returns the stored attachment content with attachment headers.