Message

Search for messages

Filter messages from a mailbox folder by search options. Search is performed against a specific folder and not for the entire account.

post/v1/account/{account}/search

Request

  • Base URL: https://your-emailengine-host
  • URL: https://your-emailengine-host/v1/account/{account}/search
  • Auth: HTTP bearer

Path parameters

accountstring required

Unique identifier for the email account

Example:user123

Query parameters

pathstring required

Mailbox folder path. Can use special use labels like "\Sent". Special value "\All" is available for Gmail IMAP, Gmail API, MS Graph API accounts.

Example:INBOX
cursorstring

Paging cursor from nextPageCursor or prevPageCursor value

Example:imap_kcQIji3UobDDTxc
pageinteger

Page number (zero-indexed, so use 0 for the first page). Only supported for IMAP accounts

pageSizeinteger

How many entries per page

Example:20
useOutlookSearchboolean

MS Graph only. Use the $search parameter for search queries instead of $filter

Headers

x-ee-timeoutinteger

Request timeout in milliseconds. Raises the command timeout above the EENGINE_TIMEOUT default for a long-running request; a value below the default has no effect

Example:30000

Request body

Example request

{
  "search": {
    "unseen": true,
    "flagged": true,
    "from": "nyan.cat@example.com",
    "body": "Hello world",
    "subject": "Hello world",
    "sentBefore": "2024-08-09",
    "sentSince": "2022-08-09",
    "emailId": "1278455344230334865",
    "threadId": "1266894439832287888",
    "header": {
      "Message-ID": "<12345@example.com>"
    },
    "gmailRaw": "has:attachment in:unread",
    "labels": {
      "has": [
        "Important"
      ],
      "not": [
        "Horizon"
      ]
    }
  }
}

Response

Returns a page of matching messages, newest first.

totalinteger

Total number of messages matching the query (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)

pageinteger

Current page number (zero-based)

pagesinteger

Total number of pages available (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)

nextPageCursorstring nullable

Cursor for fetching the next page (null when no more pages)

prevPageCursorstring nullable

Cursor for fetching the previous page

Example response

{
  "total": 120,
  "pages": 24,
  "nextPageCursor": "imap_kcQIji3UobDDTxc",
  "prevPageCursor": "imap_kcQIji3UobDDTxc",
  "messages": [
    {
      "id": "AAAAAgAACrI",
      "uid": 12345,
      "emailId": "1278455344230334865",
      "threadId": "1694936993596975454",
      "path": "INBOX",
      "date": "2021-03-22T13:13:31.000Z",
      "unseen": true,
      "flagged": true,
      "size": 1040,
      "subject": "What a wonderful message",
      "from": {
        "name": "From Me",
        "address": "sender@example.com"
      },
      "replyTo": [
        {
          "name": "Some Name",
          "address": "user@example.com"
        }
      ],
      "to": [
        {
          "name": "Some Name",
          "address": "user@example.com"
        }
      ],
      "cc": [
        {
          "name": "Some Name",
          "address": "user@example.com"
        }
      ],
      "messageId": "<test123@example.com>",
      "inReplyTo": "<7JBUMt0WOn+_==MOkaCOQ@mail.gmail.com>",
      "flags": [
        "\\Seen"
      ],
      "labels": [
        "\\Important"
      ],
      "attachments": [
        {
          "id": "AAAAAgAACrIyLjI",
          "contentType": "image/gif",
          "encodedSize": 48,
          "embedded": true,
          "inline": true,
          "contentId": "<unique-image-id@localhost>",
          "filename": "image.png",
          "method": "REQUEST"
        }
      ],
      "text": {
        "id": "AAAAAgAACqiTkaExkaEykA",
        "encodedSize": {
          "plain": 1013,
          "html": 1013
        }
      },
      "preview": "Hello, here is the report you asked for",
      "category": "primary",
      "messageSpecialUse": "\\Sent"
    }
  ]
}

Changes

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