Get a message
Returns the full details of a specific message in the shared mailbox, including optional comments, invitees, and attachments.
Endpoint
Request URL
https://mail.zoho.com/api/v2/sharedmailbox/{mailboxIdentifier}/messages/{messageId} Copied!
Note:
Use the request URL with the domain that matches the DC where your account is hosted. Refer Multiple data centers section for data center information.
Scope
Request Parameters
- Path Parameters
Email address or numeric zgid (group ID) of the shared mailbox group.
Numeric ID of the message (long as string).
- Query Parameters
When true, returns all comments on the message. When false (default), returns only the most recent commentsCount comments.
Number of recent comments to include in the response. Defaults to -1. Ignored when allComments is true.
When true, the response includes private comments on this message: comments posted privately to the message (private-to-post) and private replies on each of the message's comments returned in the response. Private comments are visible only to the sender and the intended recipient. Defaults to false.
When true, attachment data for the message is included in the response. Defaults to false.
Comma-separated fields to include in response. When omitted, all fields are returned. Possible values: messageId, mailSpaceId, entityId, entityType, messageVia, senderId, senderName, latestSenderName, groupId, groupName, isGroup, streamsEnabled, content, title, summary, htmlSummary, fromAddress, toAddress, ccAddress, messageType, isConversation, lastReplyUserId, lastMessageId, sentOnly, folderDetails, displayImage, entitySize, threadId, threadEntities, threadUnreadCount, threadCount, conversationThreadId, timestamps, createdAt, lastModifiedAt, displayDate, displayTime, updatedTime, pinnedTime, draftSentTime, toTimezone, archived, draft, lockInvites, pinned, liked, spam, trash, unread, starred, watching, shared, autoShare, hasAttachments, isOwner, ownerId, accessLevel, accessLevelVsInvitees, subSpaceId, collectionSpace, allowComments, showInvite, showDelete, commentsCount, likesCount, likedBy, inviteesCount, chatlets, mentions, inviteeList, sharedGroups and other fields also.
Sample Request
curl --request GET \
--url 'https://mail.zoho.com/api/v2/sharedmailbox/support@zylker.com/messages/1001234567890?allComments=true&commentsCount=10&includePrivateComments=false&includeAttachments=true&fields=messageId%2Ctitle%2CfromAddress%2CtoAddress%2CcreatedAt%2Cunread' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52'import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;
public class Main {
public static void main(String[] args) throws Exception{
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://mail.zoho.com/api/v2/sharedmailbox/support@zylker.com/messages/1001234567890?allComments=true&commentsCount=10&includePrivateComments=false&includeAttachments=true&fields=messageId%2Ctitle%2CfromAddress%2CtoAddress%2CcreatedAt%2Cunread"))
.header("Authorization", "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
import http.client
conn = http.client.HTTPSConnection("mail.zoho.com")
headers = { 'Authorization': "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52" }
conn.request("GET", "/api/v2/sharedmailbox/support@zylker.com/messages/1001234567890?allComments=true&commentsCount=10&includePrivateComments=false&includeAttachments=true&fields=messageId%2Ctitle%2CfromAddress%2CtoAddress%2CcreatedAt%2Cunread", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
parameters = "allComments=true" + "&" + "commentsCount=10" + "&" + "includePrivateComments=false" + "&" + "includeAttachments=true" + "&" + "fields=messageId%2Ctitle%2CfromAddress%2CtoAddress%2CcreatedAt%2Cunread";
headersMap = Map();
headersMap.put("Accept", "application/json");
response = invokeUrl
[
url: "https://mail.zoho.com/api/v2/sharedmailbox/{mailboxIdentifier}/messages/{messageId}" + "?" + parameters
type: GET
headers: headersMap
connection: connection_name
]
info response;
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mail.zoho.com/api/v2/sharedmailbox/support@zylker.com/messages/1001234567890?allComments=true&commentsCount=10&includePrivateComments=false&includeAttachments=true&fields=messageId%2Ctitle%2CfromAddress%2CtoAddress%2CcreatedAt%2Cunread",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}Response Parameters
- HTTP code 200
Response Body - application/json
Response envelope for a single shared mailbox message.
Show Sub-Attributes
Full message detail including comments and attachments.
{
"userInfo": {
"600001": "Alice Johnson",
"600002": "Bob Smith",
"600003": "John Doe"
},
"comments": {
"totalComments": 3
},
"activity": {
"likesCount": 1,
"sharedGroups": [
{
"streamsEnabled": true,
"name": "Support Team",
"id": "800000002",
"isGroup": true
}
],
"inviteesCount": 2,
"likedBy": [
"600001"
],
"commentsCount": 3,
"mentions": [],
"chatlets": 0,
"inviteeList": [
"600001",
"800000002"
]
},
"timestamps": {
"createdAt": "1746172800000",
"displayTime": "1746172800000",
"lastModifiedAt": "1746172800000",
"displayDate": "FRI MAY 02",
"toTimezone": "IST"
},
"thread": {
"isConversation": false,
"lastReplyUserId": "-1"
},
"message": {
"messageType": "1",
"mailSpaceId": "800000001",
"messageId": "1001234567890",
"fromAddress": "john.doe@example.com",
"folderDetails": {
"folderName": "Inbox",
"folderId": "800000002"
},
"toAddress": "support@zylker.com",
"messageVia": "mail",
"entitySize": 4096,
"content": {
"summary": "Hi, I placed order #98765 last week and would like to request a refund due to a defective item...",
"title": "Order #98765 - Refund Request"
},
"ccAddress": "Not Provided"
},
"labels": {
"groupLabels": [
"3001234567890"
],
"userLabels": [
"3001234567891"
],
"tags": [
{
"from": 0,
"to": 35,
"text": "Hi, I placed order #98765 last week",
"type": "QUOTE"
}
]
},
"relationships": {
"associatedTo": [
{
"namespaceId": "100000001",
"entityType": 1,
"entityId": "1001234567891"
}
],
"sharedMailIds": [
"1001234567893"
],
"associatedFrom": [
{
"namespaceId": "100000001",
"entityType": 6,
"entityId": "1001234567892"
}
]
},
"ownership": {
"accountId": "100000001",
"assigneeList": [
"600002"
],
"accessLevel": 2,
"isOwner": false,
"accessLevelVsInvitees": {
"1": [
"600002"
],
"2": [
"600004",
"600005"
]
}
},
"sender": {
"senderId": "600003",
"senderName": "John Doe",
"latestSenderName": "John Doe"
},
"permissions": {
"allowComments": true,
"showDelete": false,
"showInvite": true
},
"state": {
"shared": false,
"pinned": false,
"unread": true,
"autoShare": false,
"lockInvites": false,
"watching": false,
"liked": false,
"trash": false,
"archived": false,
"starred": false,
"draft": false,
"spam": false,
"hasAttachments": "false",
"sentOnly": false
},
"group": {
"groupName": "Zylker Support",
"streamsEnabled": true,
"groupId": "705000001",
"isGroup": true
}
}Show Sub-Attributes
Map of ZUID to display name for users referenced in this message. Present when the streams new-flow flag is enabled.
Show Sub-Attributes
Unique identifier for the request, useful for support and tracing.
Request status code and description (200 on success).
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 400
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 401
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 403
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 404
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 429
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
- HTTP code 500
Response Body - application/json
Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.
Show Sub-Attributes
Unique identifier of the request, useful for support and tracing.
Details of a single error, present when the request fails with one error.
{
"errorMessage": "The 'view' path parameter must be one of: all, unread, unassigned, assigned, archived, spam, trash.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "view"
}Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
List of errors returned when a request fails validation on multiple parameters.
Show Sub-Attributes
Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.
Show Sub-Attributes
Human-readable description of the error.
Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).
Where the offending input was supplied. Omitted when 'location' is omitted.
Name of the path parameter, query parameter or request body field that caused the error. Omitted when the error is not tied to a specific input.
HTTP-like status code and human-readable description of the error.
{
"code": 200,
"description": "OK"
}Show Sub-Attributes
HTTP-style numeric status code returned by the API (e.g. 200 for success).
Human-readable text describing the outcome of the request.
Sample Response: HTTP 200
{
"data": {
"userInfo": {
"600001": "Alice Johnson",
"600002": "Bob Smith",
"600003": "John Doe"
},
"comments": {
"totalComments": 3
},
"activity": {
"likesCount": 1,
"sharedGroups": [
{
"streamsEnabled": true,
"name": "Support Team",
"id": "800000002",
"isGroup": true
}
],
"inviteesCount": 2,
"likedBy": [
"600001"
],
"commentsCount": 3,
"mentions": [],
"chatlets": 0,
"inviteeList": [
"600001",
"800000002"
]
},
"timestamps": {
"createdAt": "1746172800000",
"displayTime": "1746172800000",
"lastModifiedAt": "1746172800000",
"displayDate": "FRI MAY 02",
"toTimezone": "IST"
},
"thread": {
"isConversation": false,
"lastReplyUserId": "-1"
},
"message": {
"messageType": "1",
"mailSpaceId": "800000001",
"messageId": "1001234567890",
"fromAddress": "john.doe@example.com",
"folderDetails": {
"folderName": "Inbox",
"folderId": "800000002"
},
"toAddress": "support@zylker.com",
"messageVia": "mail",
"entitySize": 4096,
"content": {
"summary": "Hi, I placed order #98765 last week and would like to request a refund due to a defective item...",
"title": "Order #98765 - Refund Request"
},
"ccAddress": "Not Provided"
},
"labels": {
"groupLabels": [
"3001234567890"
],
"userLabels": [
"3001234567891"
],
"tags": [
{
"from": 0,
"to": 35,
"text": "Hi, I placed order #98765 last week",
"type": "QUOTE"
}
]
},
"relationships": {
"associatedTo": [
{
"namespaceId": "100000001",
"entityType": 1,
"entityId": "1001234567891"
}
],
"sharedMailIds": [
"1001234567893"
],
"associatedFrom": [
{
"namespaceId": "100000001",
"entityType": 6,
"entityId": "1001234567892"
}
]
},
"ownership": {
"accountId": "100000001",
"assigneeList": [
"600002"
],
"accessLevel": 2,
"isOwner": false,
"accessLevelVsInvitees": {
"1": [
"600002"
],
"2": [
"600004",
"600005"
]
}
},
"sender": {
"senderId": "600003",
"senderName": "John Doe",
"latestSenderName": "John Doe"
},
"permissions": {
"allowComments": true,
"showDelete": false,
"showInvite": true
},
"state": {
"shared": false,
"pinned": false,
"unread": true,
"autoShare": false,
"lockInvites": false,
"watching": false,
"liked": false,
"trash": false,
"archived": false,
"starred": false,
"draft": false,
"spam": false,
"hasAttachments": "false",
"sentOnly": false
},
"group": {
"groupName": "Zylker Support",
"streamsEnabled": true,
"groupId": "705000001",
"isGroup": true
}
},
"requestId": "zmreq-abc12345-def6-7890",
"status": {
"code": 200,
"description": "OK"
}
}
Sample Response: HTTP 400
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "The 'messageId' path parameter must be a numeric message ID.",
"errorCode": "INVALID_INPUT",
"locationType": "pathParam",
"location": "messageId"
},
"status": {
"code": 400,
"description": "Bad Request"
}
}
Sample Response: HTTP 401
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "The OAuth access token is missing, malformed or has expired.",
"errorCode": "INVALID_INPUT"
},
"status": {
"code": 401,
"description": "Unauthorized"
}
}
Sample Response: HTTP 403
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "The authenticated user does not have permission to perform this operation on this shared mailbox.",
"errorCode": "INVALID_INPUT"
},
"status": {
"code": 403,
"description": "Forbidden"
}
}
Sample Response: HTTP 404
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "Message '1001234567890' was not found in this shared mailbox.",
"errorCode": "INVALID_INPUT"
},
"status": {
"code": 404,
"description": "Not Found"
}
}
Sample Response: HTTP 429
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "The rate limit for this API has been exceeded. Retry after the lock period has elapsed.",
"errorCode": "INVALID_INPUT"
},
"status": {
"code": 429,
"description": "Too Many Requests"
}
}
Sample Response: HTTP 500
{
"requestId": "zmreq-abc12345-def6-7890",
"error": {
"errorMessage": "Something went wrong. Please try again later.",
"errorCode": "INTERNAL_SERVER_ERROR"
},
"status": {
"code": 500,
"description": "Internal Server Error"
}
}
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.