Messages

Search messages

Search messages in a folder. Filters in body; pagination and sort via query (page, perPage, sort).

post/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/search

Request

  • Base URL: https://api.mail.hostinger.com
  • URL: https://api.mail.hostinger.com/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/search
  • Auth: HTTP bearer

Path parameters

mailboxResourceIdstring required

Resource ID of the managed mailbox the bearer token is authorized for.

folderstring required

Folder path (URL-encoded).

Query parameters

pageinteger

Page number (1-based).

perPageinteger

Items per page (max 100).

sortstring

Sort field with optional - prefix for descending. Allowed: uid, date, size.

Request body

sincestring date

Only messages received on or after this date (YYYY-MM-DD).

beforestring date

Only messages received before this date (YYYY-MM-DD).

flagsstring[]

Only messages carrying all of these IMAP flags, e.g. \Seen, \Flagged, \Answered, $forwarded.

uidstring

IMAP UID set: single UID, range (1:100), open range (100:*), or comma-separated list.

subjectstring

Case-insensitive substring match on the Subject header. OR-combined with from/to/cc/body.

fromstring

Case-insensitive substring match on the From header. OR-combined with subject/to/cc/body.

tostring

Case-insensitive substring match on the To header. OR-combined with subject/from/cc/body.

ccstring

Case-insensitive substring match on the Cc header. OR-combined with subject/from/to/body.

bodystring

Case-insensitive substring match on the message body only (headers excluded). OR-combined with subject/from/to/cc.

headerstring

Match a specific header as Name:value, e.g. X-Custom-Header:value. Value match is a substring.

largerinteger

Only messages larger than this size in bytes.

smallerinteger

Only messages smaller than this size in bytes.

textstring

Case-insensitive substring match across headers and body.

Example request

{
  "since": "2024-01-01",
  "before": "2024-12-31",
  "flags": [
    "\\Seen",
    "\\Flagged"
  ],
  "uid": "1:100",
  "subject": "meeting",
  "from": "john@example.com",
  "to": "jane@example.com",
  "cc": "team@example.com",
  "body": "important",
  "header": "X-Custom-Header:value",
  "larger": 1024,
  "smaller": 1048576,
  "text": "urgent"
}

Response

Paginated list of matching messages.

Example response

{
  "data": [
    {
      "uid": 123,
      "path": "INBOX",
      "date": "2024-01-15T10:30:00.000Z",
      "flags": [
        "\\Seen",
        "\\Flagged"
      ],
      "size": 2048,
      "subject": "Test Email Subject",
      "from": {
        "name": "John Doe",
        "address": "john@example.com"
      },
      "to": [
        {
          "name": "John Doe",
          "address": "john@example.com"
        }
      ],
      "cc": [
        {
          "name": "John Doe",
          "address": "john@example.com"
        }
      ],
      "bcc": [
        {
          "name": "John Doe",
          "address": "john@example.com"
        }
      ],
      "messageId": "<1234567890@example.com>",
      "inReplyTo": "<0987654321@example.com>",
      "attachments": [
        {
          "id": "YXR0YWNobWVudDpJTkJPWDoxMjM6MS4y",
          "contentType": "application/pdf",
          "sizeBytes": 1024,
          "filename": "document.pdf",
          "contentId": "<attachment@example.com>"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 137,
    "totalPages": 6
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.