List Emails based on Search Parameters

Purpose

The API retrieves the list of emails, based on the custom search terms and parameters.

OAuth Scope

Use the scope

ZohoMail.messages.ALL (or) ZohoMail.messages.READ

to generate the Authtoken.

ALL - Grants full access to messages.

READ - Grants access to read messages.

Request URL

Method: GET

https://mail.zoho.com/api/accounts/{accountId}/messages/search

Path Parameters

accountId* long
- This key is used to identify the account from which the emails have to be retrieved. It is generated during account addition.
- This parameter can be fetched from Get All User Accounts API.

Query Parameters

searchKey* string
- Specifies the search criteria.
- Ensure that the searchKey is constructed using the search syntax defined in this help page.
- For example: To search for new emails, provide the searchKey as newMails.
receivedTime long
- Specifies the time before which emails were received. It allows users to filter emails based on their received timestamp.
- Format: Unix timestamp in milliseconds
  Example: 1609459200000
- By default, the API retrieves emails received before 2 minutes from the current time unless a specific timestamp is provided.
start int
- Specifies the starting sequence number of the emails to be retrieved.
- The default value is 1.
limit int
- Specifies the number of emails to be retrieved from the start value mentioned.
- Allowed values : Min. value: 1 and max. value: 200.
- The default value is 10.
includeto boolean
- Specifies whether To details need to be included or not on the list of emails retrieved.
- The value can be
  - true, to include To details
  - false, to not include To details.
- The default value is false.

* - Mandatory parameter

Response Codes

Refer here for the response codes and their meaning.

Sample Request

Copiedcurl "https://mail.zoho.com/api/accounts/123456789/messages/search?searchKey=newMails&receivedTime=1609459200000&start=1&limit=10&includeto=true" \
-X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization:Zoho-oauthtoken *****"

Sample Response

Copied{
  "status": {
    "code": 200,
    "description": "success"
  },
  "data": [
    {
      "URI": "https://mail.zoho.com/api/accounts/123456789/folders/9000000000905/messages/9000000019029",
      "hasAttachment": 0,
      "fromAddress": "rebecca@zylker.com",
      "folderId": 9000000000905,
      "messageId": 9000000019029,
      "sender": "Maria Daniel",
      "summary": "It is extremely important for us to focus on",
      "status2": "reply",
      "sentDateInGMT": 1270171976000,
      "size": 540,
      "status": "read",
      "priority": 3,
      "threadCount": 0,
      "flagid": 2,
      "subject": "Marketing Strategy",
      "threadId": 1,
      "receivedtime": 1425388373920
    },
    {
      "URI": "https://mail.zoho.com/api/accounts/123456789/folders/9000000000905/messages/9000000046832",
      "hasAttachment": 0,
      "fromAddress": "paula@zylker.com",
      "folderId": 9000000000905,
      "messageId": 9000000046832,
      "sender": "Van Tsuan",
      "summary": "Can we have an additional discount",
      "status2": "none",
      "sentDateInGMT": 1270171976000,
      "size": 540,
      "status": "unread",
      "priority": 3,
      "flagid": 2,
      "subject": "Re:Quote for 1000 users",
      "threadId": 0,
      "receivedtime": 1425388373741
    },
    {
      "URI": "https://mail.zoho.com/api/accounts/123456789/folders/9000000000905/messages/900000001482014",
      "hasAttachment": 0,
      "fromAddress": "david@zylker.com",
      "folderId": 9000000000905,
      "messageId": 900000001482014,
      "sender": "singh",
      "summary": "Since it is a 1000 user deal, offer 5% more ",
      "status2": "none",
      "sentDateInGMT": 1270171976000,
      "size": 540,
      "status": "unread",
      "priority": 3,
      "flagid": 2,
      "subject": "Re:Fw:Re:Quote for 1000 users",
      "threadId": 0,
      "receivedtime": 1425388373581
    }
  ]
}