---
title: "List and search messages"
method: GET
path: "/v1/messages"
tags: ["Messages"]
---

# List and search messages

`GET /v1/messages`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/messages`
- Auth: HTTP basic

Retrieve a list of messages with advanced search and filtering capabilities. This endpoint supports pagination and comprehensive search across message content, headers, flags, and metadata. You can search by folder, flags, content, headers, date ranges, size, and more.

## Query parameters

- `page` integer
- `limit` integer
- `folder` string
- `is_unread` boolean
- `is_flagged` boolean
- `is_deleted` boolean
- `is_draft` boolean
- `is_junk` boolean
- `is_copied` boolean
- `is_encrypted` boolean
- `is_searchable` boolean
- `is_expired` boolean
- `has_attachments` boolean
- `has_attachment` boolean
- `subject` string
- `body` string
- `text` string
- `headers` string
- `message_id` string
- `search` string
- `q` string
- `since` string, date-time
- `before` string, date-time
- `min_size` integer
- `max_size` integer
- `from` string
- `to` string
- `cc` string
- `bcc` string
- `date` string
- `reply-to` string
- `lightweight` 'true' | 'false'

## Response `200`

Messages retrieved successfully

- Message[]
  - `id` string, required: Message ID
  - `root_id` string, required: Root message ID for threading
  - `folder_id` string, required: Folder ID containing the message
  - `folder_path` string, required: Folder path containing the message
  - `thread_id` string, required: Thread ID for conversation grouping
  - `header_message_id` string, required: Message-ID header value
  - `is_unread` boolean, required: Whether message is unread
  - `is_flagged` boolean, required: Whether message is flagged
  - `is_deleted` boolean, required: Whether message is deleted
  - `is_draft` boolean, required: Whether message is a draft
  - `is_junk` boolean, required: Whether message is junk/spam
  - `is_copied` boolean, required: Whether message is copied
  - `is_encrypted` boolean, required: Whether message is encrypted (PGP/MIME or S/MIME)
  - `is_searchable` boolean, required: Whether message is searchable
  - `is_expired` boolean, required: Whether message is expired
  - `has_attachment` boolean, required: Whether message has attachments
  - `retention_date` string, date-time, nullable, required: Message retention date
  - `internal_date` string, date-time, required: Internal date (IMAP)
  - `header_date` string, date-time, required: Date from message headers
  - `subject` string, required: Message subject
  - `flags` string[], required: IMAP flags
  - `labels` string[], required: User-defined labels (lowercase, max 10)
  - `size` integer, required: Message size in bytes
  - `uid` integer, required: IMAP UID
  - `modseq` integer, required: Modification sequence
  - `transaction` string, required: Transaction type
  - `remote_address` string, required: Remote IP address
  - `created_at` string, date-time, required: Message creation timestamp
  - `updated_at` string, date-time, required: Message last update timestamp
  - `nodemailer` object: Parsed message object (included by default, set ?nodemailer=false to exclude)
  - `raw` string: Raw message content (included by default, set ?raw=false to exclude)
  - `object` 'message', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)