Search messages | mailpit unofficial

4 parameters

querystringrequired

Search query

startstringoptional

Pagination offset

Default:0

limitstringoptional

Limit results

Default:50

tzstringoptional

Optional [timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used only for `before:` & `after:` searches (eg: "Pacific/Auckland").

2 status codes

200Summary of messages

messagesarray<object>optional

Messages summary

messages_countintegeroptional

Total number of messages matching current query

messages_unreadintegeroptional

Total number of unread messages matching current query

startintegeroptional

Pagination offset

tagsarray<string>optional

All current tags

totalintegeroptional

Total number of messages in mailbox

unreadintegeroptional

Total number of unread messages in mailbox

400Server error will return with a 400 status code with the error message in the body

Error handling

A 400 is returned: Server error will return with a 400 status code with the error message in the body.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
});

const result = await client.search.list({
  query: "keyword",
  start: 0,
  limit: 20,
  tz: "example",
});

{
  "messages": [
    {
      "Attachments": 1,
      "Bcc": [
        {
          "Address": "example_value",
          "Name": "Example Name"
        }
      ],
      "Cc": [
        {
          "Address": "example_value",
          "Name": "Example Name"
        }
      ],
      "Created": "2026-01-15T09:00:00Z",
      "From": {
        "Address": "example_value",
        "Name": "Example Name"
      },
      "ID": "550e8400-e29b-41d4-a716-446655440000",
      "MessageID": "550e8400-e29b-41d4-a716-446655440000",
      "Read": true,
      "ReplyTo": [
        {
          "Address": "example_value",
          "Name": "Example Name"
        }
      ],
      "Size": 1,
      "Snippet": "example_value",
      "Subject": "Example Subject",
      "Tags": [
        "example_value"
      ],
      "To": [
        {
          "Address": "example_value",
          "Name": "Example Name"
        }
      ],
      "Username": "janedoe"
    }
  ],
  "messages_count": 42,
  "messages_unread": 1,
  "start": 1,
  "tags": [
    "example_value"
  ],
  "total": 42,
  "unread": 1
}

Request

Response

Errors