List Emails

Purpose

The API retrieves a list of all the emails in a specific folder or a list of emails based on predefined conditions like status/flags/labels, and more. 

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/view

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

  • folderId  long
    • This parameter specifies the unique identifier for the folder from which the emails need to be retrieved. 
    • This can be fetched using the Get all folders API.
  • start int
    • This parameter specifies the starting sequence number of the emails to be retrieved.
    • The default value is 1.
  • limit int
    • This parameter 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.
  • status string
    • Provide this parameter to retrieve emails by read or unread status. 
    • The value can be 
      • read
      • unread
      • all
    • The default value is all.
  • flagid int
    • This parameter specifies the unique identifier for the flag used to retrieve emails based on a specific flag type.
    • Possible values :
      • 0 - flag_not_set
      • 1 - info
      • 2 - important
      • 3 - followup
  • labelid long
    • This parameter specifies the unique identifier for the label used to retrieve emails based on a specific label.
  • threadId long
    • This parameter specifies the unique identifier for the flag used to retrieve emails of the given threadId.
  • sortBy string
    • This parameter specifies on which basis the sorting of the list of emails should be done.
    • The values can be 
      • date 
      • messageId 
      • size
    • The default value is date.
  • sortorder boolean
    • This parameter specifies on which basis the sorting of the list of emails should be done.
    • The value can be 
      • true, for ascending order 
      • false, for descending order
    • The default value is false.
  • includeto boolean
    • This parameter allows you to indicate 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.
  • includesent boolean
    • This parameter allows you to indicate whether sent emails need to be included or not on the list of emails retrieved.
    • The value can be 
      • true, to include sent emails
      • false, to not include sent emails.
    • The default value is false.
  • includearchive boolean
    • This parameter allows you to indicate whether archived emails need to be included or not on the list of emails retrieved.
    • The value can be 
      • true, to include archived emails
      • false, to not include archived emails.
    • The default value is false.
  • attachedMails boolean
    • Provide this parameter to retrieve only the emails with attachments.  
    • The value can be 
      • true, to retrieve the emails with attachments. 
      • false, to retrieve all emails.
    • The default value is false.
  • inlinedMails boolean
    • Provide this parameter to retrieve only the emails with inline images. 
    • The value can be 
      • true, to retrieve the emails with inline images. 
      • false, to retrieve all emails.
    • The default value is false.
  • flaggedMails boolean
    • Provide this parameter to retrieve only flagged emails. 
    • The value can be 
      • true, to retrieve flagged emails.
      • false, to retrieve all emails.
    • The default value is false.
  • respondedMails boolean
    • Provide this parameter to retrieve only emails with replies.
    • The value can be 
      • true, to retrieve emails with replies.
      • false, to retrieve all emails.
    • The default value is false.
  • threadedMails boolean
    • Provide this parameter to retrieve emails that are a part of conversations.
    • The value can be 
      • true, to retrieve threaded emails.
      • false, to retrieve all emails.
    • 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/view?folderId=9000000002014&threadedMails=true&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": [
       {
           "summary": "reply test  On Fri, 08 Mar 2024 07:31:31 +0000 rebecca<rebecca@zylker.com> wrote -",
           "sentDateInGMT": "1709867251000",
           "calendarType": 0,
           "subject": "Re: Hello ",
           "messageId": "1709887058769100001",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709883095364100001",
           "hasAttachment": "0",
           "size": "1190",
           "sender": "rebecca",
           "receivedTime": "1709887053409",
           "fromAddress": "rebecca@zylker.com",
           "status": "1"
       },
       {
           "summary": "",
           "sentDateInGMT": "1709863291000",
           "calendarType": 0,
           "subject": "ckjrjv rw",
           "messageId": "1709883097133100003",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "1",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709883095364100001",
           "hasAttachment": "0",
           "size": "550",
           "sender": "rebecca",
           "receivedTime": "1709883095346",
           "fromAddress": "rebecca@zylker.com",
           "status": "1"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856410000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876210189100007",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709876209452100005",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876210144",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856409000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876209452100005",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709876209452100005",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876209407",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856408000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876208302100003",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709876207719100001",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876208251",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856407000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876207719100001",
           "threadCount": "0",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "threadId": "1709876207719100001",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876207661",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856390000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876190693100009",
           "flagid": "info",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876190649",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856388000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876188821100007",
           "flagid": "important",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876188776",
           "fromAddress": "paula@zyiker.com",
           "status": "1"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856387000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876187841100005",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876187797",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       },
       {
           "summary": "Hello Sent using Zoho Mail",
           "sentDateInGMT": "1709856386000",
           "calendarType": 0,
           "subject": "Test",
           "messageId": "1709876186914100003",
           "flagid": "flag_not_set",
           "status2": "0",
           "priority": "3",
           "hasInline": "false",
           "toAddress": ""rebecca"<rebecca@zylker.com>",
           "folderId": "9000000002014",
           "ccAddress": "Not Provided",
           "hasAttachment": "0",
           "size": "873",
           "sender": "test csez",
           "receivedTime": "1709876186869",
           "fromAddress": "paula@zyiker.com",
           "status": "0"
       }
   ]
}