Messages

List and search messages

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.

get/v1/messages

Request

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

Query parameters

pageinteger

Page of results to return. If not specified, value will be 1. Must be a number greater than or equal to 1.

limitinteger

Number of results to return per page. Defaults to 25 if not specified. Must be a number greater than or equal to 1, and less than or equal to 100.

folderstring

Filter messages by folder path

is_unreadboolean

Filter by read status

is_flaggedboolean

Filter by flagged status

is_deletedboolean

Filter by deleted status

is_draftboolean

Filter by draft status

is_junkboolean

Filter by junk/spam status

is_copiedboolean

Filter by copied status

is_encryptedboolean

Filter by encryption status (PGP/MIME or S/MIME)

is_searchableboolean

Filter by searchable status

is_expiredboolean

Filter by expired status

has_attachmentsboolean

Filter by attachment presence

has_attachmentboolean

Filter by attachment presence (alias for has_attachments)

subjectstring

Search in message subject

bodystring

Search in message body/text

textstring

Search in message text (alias for body)

headersstring

Search in all message headers

message_idstring

Search by Message-ID header

searchstring

General search across headers and text

qstring

General search (alias for search)

sincestring date-time

Filter messages since this date (ISO 8601 format)

beforestring date-time

Filter messages before this date (ISO 8601 format)

min_sizeinteger

Filter messages with minimum size in bytes

max_sizeinteger

Filter messages with maximum size in bytes

fromstring

Search by From header

tostring

Search by To header

ccstring

Search by CC header

bccstring

Search by BCC header

datestring

Search by Date header

reply-tostring

Search by Reply-To header

lightweight'true' | 'false'

When set to "true", returns metadata-only responses without nodemailer or raw fields. This significantly improves performance by skipping full MIME tree reconstruction and attachment body fetching. Useful for building message lists where only metadata (subject, flags, dates, folder, size) is needed.

Response

Messages retrieved successfully

idstring required

Message ID

root_idstring required

Root message ID for threading

folder_idstring required

Folder ID containing the message

folder_pathstring required

Folder path containing the message

thread_idstring required

Thread ID for conversation grouping

header_message_idstring required

Message-ID header value

is_unreadboolean required

Whether message is unread

is_flaggedboolean required

Whether message is flagged

is_deletedboolean required

Whether message is deleted

is_draftboolean required

Whether message is a draft

is_junkboolean required

Whether message is junk/spam

is_copiedboolean required

Whether message is copied

is_encryptedboolean required

Whether message is encrypted (PGP/MIME or S/MIME)

is_searchableboolean required

Whether message is searchable

is_expiredboolean required

Whether message is expired

has_attachmentboolean required

Whether message has attachments

retention_datestring date-time nullable required

Message retention date

internal_datestring date-time required

Internal date (IMAP)

header_datestring date-time required

Date from message headers

subjectstring required

Message subject

flagsstring[] required

IMAP flags

labelsstring[] required

User-defined labels (lowercase, max 10)

sizeinteger required

Message size in bytes

uidinteger required

IMAP UID

modseqinteger required

Modification sequence

transactionstring required

Transaction type

remote_addressstring required

Remote IP address

created_atstring date-time required

Message creation timestamp

updated_atstring date-time required

Message last update timestamp

nodemailerobject

Parsed message object (included by default, set ?nodemailer=false to exclude)

rawstring

Raw message content (included by default, set ?raw=false to exclude)

object'message' required

Example response

[
  {
    "id": "message123",
    "root_id": "root123",
    "folder_id": "folder123",
    "folder_path": "INBOX",
    "thread_id": "thread123",
    "header_message_id": "<message123@example.com>",
    "is_unread": true,
    "is_flagged": false,
    "is_deleted": false,
    "is_draft": false,
    "is_junk": false,
    "is_copied": false,
    "is_encrypted": false,
    "is_searchable": true,
    "is_expired": false,
    "has_attachment": false,
    "retention_date": null,
    "internal_date": "2025-01-01T00:00:00.000Z",
    "header_date": "2025-01-01T00:00:00.000Z",
    "subject": "Test Message",
    "flags": [
      "\\Seen"
    ],
    "size": 1024,
    "uid": 1,
    "modseq": 1,
    "transaction": "API",
    "remote_address": "127.0.0.1",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "object": "message"
  }
]

Changes

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