Add tags to a message

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Adds one or more tags to a single shared mailbox message. Provide either tagIds or tagNames (mutually exclusive, up to 50 each). Tag names are resolved server-side.

Request URL

https://mail.zoho.com/api/v2/sharedmailbox/{mailboxIdentifier}/messages/{messageId}/tags/add 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

ZohoMail.messages.UPDATECopied!
(or)
ZohoMail.messages.ALLCopied!

Request Parameters

- Path Parameters

mailboxIdentifierstringMandatory

Email address or numeric zgid (group ID) of the shared mailbox group.

Example
support@zylker.com
Maximum Length :256Copied!
messageIdstring(matches: ^[0-9]+$)Mandatory

Numeric ID of the message (long as string).

Example
1001234567890
Maximum Length :19Copied!

- Request Body

application/json
JSON Object

Request body for adding or removing tags from a single message. Provide either tagIds or tagNames - they are mutually exclusive.

Show Sub-Attributes
tagIdsarray[string]Optional

Numeric tag IDs (long as string each). Mutually exclusive with tagNames.

Range :[0 .. 50][0 .. 50]
tagNamesarray[string]Optional

Tag names; resolved server-side to IDs. Mutually exclusive with tagIds.

Range :[0 .. 50][0 .. 50]

Sample Request

Curl
Java
Python
Deluge
Php
Copied!
curl --request PUT \
  --url https://mail.zoho.com/api/v2/sharedmailbox/support@zylker.com/messages/1001234567890/tags/add \
  --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
  --header 'content-type: application/json' \
  --data '{"tagIds":["3001234567890","3001234567891"]}'

Sample Request Body

Copied!
  {
    "tagIds": [
      "3001234567890",
      "3001234567891"
    ]
  }
                
▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Standard response for write/action operations that do not return a specific resource.

Show Sub-Attributes
dataJSON Object

Operation result data. May include entityId or a status indicator depending on the operation.

Show Sub-Attributes
entityIdstring

ID of the affected entity, when applicable (long as string).

Maximum Length :19Copied!
statusstring

Operation outcome indicator (e.g. 'success').

requestIdstring

Unique identifier for the request, useful for support and tracing.

statusJSON Object

Request status code and description (200 on success).

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 400

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 401

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 403

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 404

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 429

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

- HTTP code 500

Response Body - application/json
JSON Object

Standard error envelope returned for failed requests. Exactly one of 'error' (single error) or 'errors' (multiple validation errors) is present.

Show Sub-Attributes
requestIdstring

Unique identifier of the request, useful for support and tracing.

errorJSON Object

Details of a single error, present when the request fails with one error.

Example
{
  "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
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

errorsJSON Array

List of errors returned when a request fails validation on multiple parameters.

Show Sub-Attributes
JSON Object

Details of a single error. 'location' and 'locationType' are present only when the error is attributable to a specific input.

Show Sub-Attributes
errorMessagestring

Human-readable description of the error.

errorCodestring

Application-level error code. INVALID_INPUT for client-side failures (400, 401, 403, 404); INTERNAL_SERVER_ERROR for unexpected server failures (500).

locationTypestring

Where the offending input was supplied. Omitted when 'location' is omitted.

Allowed Values :
Show Values ▾
pathParamCopied!
queryParamCopied!
requestBodyCopied!
headerCopied!
Copied!Copy all as JSON Array
locationstring

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.

statusJSON Object

HTTP-like status code and human-readable description of the error.

Example
{
  "code": 200,
  "description": "OK"
}
Show Sub-Attributes
codeinteger

HTTP-style numeric status code returned by the API (e.g. 200 for success).

descriptionstring

Human-readable text describing the outcome of the request.

Sample Response: HTTP 200

Copied!
  {
    "data": {
      "entityId": "1001234567890",
      "status": "success"
    },
    "requestId": "zmreq-abc12345-def6-7890",
    "status": {
      "code": 200,
      "description": "OK"
    }
  }
                
▼ Show full

Sample Response: HTTP 400

Copied!
  {
    "requestId": "zmreq-abc12345-def6-7890",
    "error": {
      "errorMessage": "Provide either 'tagIds' or 'tagNames' with at least one entry.",
      "errorCode": "INVALID_INPUT",
      "locationType": "requestBody",
      "location": "tagIds"
    },
    "status": {
      "code": 400,
      "description": "Bad Request"
    }
  }
                
▼ Show full

Sample Response: HTTP 401

Copied!
  {
    "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"
    }
  }
                
▼ Show full

Sample Response: HTTP 403

Copied!
  {
    "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"
    }
  }
                
▼ Show full

Sample Response: HTTP 404

Copied!
  {
    "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"
    }
  }
                
▼ Show full

Sample Response: HTTP 429

Copied!
  {
    "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"
    }
  }
                
▼ Show full

Sample Response: HTTP 500

Copied!
  {
    "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"
    }
  }
                
▼ Show full