Users.labels: update

Updates the specified label. Try it now or see an example.

Request

HTTP request

PUT https://www.googleapis.com/gmail/v1/users/userId/labels/id

Parameters

Parameter name Value Description
Path parameters
id string The ID of the label to update.
userId string The user's email address. The special value me can be used to indicate the authenticated user.

Authorization

This request requires authorization with at least one of the following scopes:

Scope
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.labels

For more information, see the authentication and authorization page.

Request body

In the request body, supply a Users.labels resource with the following properties:

Property name Value Description Notes
Required Properties
id string The immutable ID of the label.
labelListVisibility string The visibility of the label in the label list in the Gmail web interface.

Acceptable values are:
  • "labelHide": Do not show the label in the label list.
  • "labelShow": Show the label in the label list. (Default)
  • "labelShowIfUnread": Show the label if there are any unread messages with that label.
writable
messageListVisibility string The visibility of messages with this label in the message list in the Gmail web interface.

Acceptable values are:
  • "hide": Do not show the label in the message list.
  • "show": Show the label in the message list. (Default)
writable
name string The display name of the label. writable
Optional Properties
color nested object The color to assign to the label. Color is only available for labels that have their type set to user. writable
color.backgroundColor string The background color represented as hex string #RRGGBB (ex #000000). This field is required in order to set the color of a label. Only the following predefined set of color values are allowed:
#000000, #434343, #666666, #999999, #cccccc, #efefef, #f3f3f3, #ffffff, #fb4c2f, #ffad47, #fad165, #16a766, #43d692, #4a86e8, #a479e2, #f691b3, #f6c5be, #ffe6c7, #fef1d1, #b9e4d0, #c6f3de, #c9daf8, #e4d7f5, #fcdee8, #efa093, #ffd6a2, #fce8b3, #89d3b2, #a0eac9, #a4c2f4, #d0bcf1, #fbc8d9, #e66550, #ffbc6b, #fcda83, #44b984, #68dfa9, #6d9eeb, #b694e8, #f7a7c0, #cc3a21, #eaa041, #f2c960, #149e60, #3dc789, #3c78d8, #8e63ce, #e07798, #ac2b16, #cf8933, #d5ae49, #0b804b, #2a9c68, #285bac, #653e9b, #b65775, #822111, #a46a21, #aa8831, #076239, #1a764d, #1c4587, #41236d, #83334c #464646, #e7e7e7, #0d3472, #b6cff5, #0d3b44, #98d7e4, #3d188e, #e3d7ff, #711a36, #fbd3e0, #8a1c0a, #f2b2a8, #7a2e0b, #ffc8af, #7a4706, #ffdeb5, #594c05, #fbe983, #684e07, #fdedc1, #0b4f30, #b3efd3, #04502e, #a2dcc1, #c2c2c2, #4986e7, #2da2bb, #b99aff, #994a64, #f691b2, #ff7537, #ffad46, #662e37, #ebdbde, #cca6ac, #094228, #42d692, #16a765
writable
color.textColor string The text color of the label, represented as hex string. This field is required in order to set the color of a label. Only the following predefined set of color values are allowed:
#000000, #434343, #666666, #999999, #cccccc, #efefef, #f3f3f3, #ffffff, #fb4c2f, #ffad47, #fad165, #16a766, #43d692, #4a86e8, #a479e2, #f691b3, #f6c5be, #ffe6c7, #fef1d1, #b9e4d0, #c6f3de, #c9daf8, #e4d7f5, #fcdee8, #efa093, #ffd6a2, #fce8b3, #89d3b2, #a0eac9, #a4c2f4, #d0bcf1, #fbc8d9, #e66550, #ffbc6b, #fcda83, #44b984, #68dfa9, #6d9eeb, #b694e8, #f7a7c0, #cc3a21, #eaa041, #f2c960, #149e60, #3dc789, #3c78d8, #8e63ce, #e07798, #ac2b16, #cf8933, #d5ae49, #0b804b, #2a9c68, #285bac, #653e9b, #b65775, #822111, #a46a21, #aa8831, #076239, #1a764d, #1c4587, #41236d, #83334c #464646, #e7e7e7, #0d3472, #b6cff5, #0d3b44, #98d7e4, #3d188e, #e3d7ff, #711a36, #fbd3e0, #8a1c0a, #f2b2a8, #7a2e0b, #ffc8af, #7a4706, #ffdeb5, #594c05, #fbe983, #684e07, #fdedc1, #0b4f30, #b3efd3, #04502e, #a2dcc1, #c2c2c2, #4986e7, #2da2bb, #b99aff, #994a64, #f691b2, #ff7537, #ffad46, #662e37, #ebdbde, #cca6ac, #094228, #42d692, #16a765
writable

Response

If successful, this method returns a Users.labels resource in the response body.

Examples

Note: The code examples available for this method do not represent all supported programming languages (see the client libraries page for a list of supported languages).

Java

Uses the Java client library.

import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.model.Label;

import java.io.IOException;

// ...

public class MyClass {

  // ...


  /**
   * Update an existing label.
   *
   * @param service Authorized Gmail API instance.
   * @param userId User's email address. The special value "me"
   * can be used to indicate the authenticated user.
   * @param labelId Id of the label to be updated.
   * @param newLabelName New name of the label.
   * @param showInMessageList Show or hide label in message.
   * @param showInLabelList Show or hide label in label list.
   * @throws IOException
   */
  public static void updateLabel(Gmail service, String userId, String labelId, String newLabelName,
      boolean showInMessageList, boolean showInLabelList) throws IOException {
    String messageListVisibility = showInMessageList ? "show" : "hide";
    String labelListVisibility = showInLabelList ? "labelShow" : "labelHide";
    Label newLabel = new Label().setName(newLabelName)
        .setMessageListVisibility(messageListVisibility)
        .setLabelListVisibility(labelListVisibility);
    newLabel = service.users().labels().update(userId, labelId, newLabel).execute();

    System.out.println("Label id: " + newLabel.getId());
    System.out.println(newLabel.toPrettyString());
  }

  // ...

}

.NET

Uses the .NET client library.

using Google.Apis.Gmail.v1;
using Google.Apis.Gmail.v1.Data;

// ...

public class MyClass {

  // ...

  /// <summary>
  /// Update an existing Label.
  /// </summary>
  /// <param name="service">Gmail API service instance.</param>
  /// <param name="userId">User's email address. The special value "me"
  /// can be used to indicate the authenticated user.</param>
  /// <param name="labelId">Id of the label to be updated.</param>
  /// <param name="newLabelName">Name of the new Label.</param>
  /// <param name="showInMessageList">Show or hide label in message.</param>
  /// <param name="showInLabelList">Show or hide label in label list.</param>
  public static Label UpdateLabel(GmailService service, String userId, String labelId,
      String newLabelName,Boolean showInMessageList, Boolean showInLabelList)
  {
      String messageListVisibility = showInMessageList ? "show" : "hide";
      String labelListVisibility = showInLabelList ? "labelShow" : "labelHide";

      Label label = new Label();
      label.Name = newLabelName;
      label.MessageListVisibility = messageListVisibility;
      label.LabelListVisibility = labelListVisibility;

      try
      {
          return service.Users.Labels.Update(label, userId, labelId).Execute();
      }
      catch (Exception e)
      {
          Console.WriteLine("An error occurred: " + e.Message);
      }
      return null;
  }

  // ...

}

PHP

Does not use a client library.

/**
 * Update an existing Label.
 *
 * @param  Google_Service_Gmail $service Authorized Gmail API instance.
 * @param  string $userId User's email address. The special value 'me'
 * can be used to indicate the authenticated user.
 * @param  string $labelId ID of Label to update.
 * @param  string $labelName Updated name.
 * @param  string $labelListVisibility Updated Label list visibility.
 * @param  string $messageListVisibility Updated Message list visibility.
 * @return Google_Service_Gmail_Label updated Label.
 */
function updateLabel($service, $userId, $labelId, $labelName,
  $labelListVisibility, $messageListVisibility) {
  $label = new Google_Service_Gmail_Label();
  $label->setName($labelName);
  $label->setLabelListVisibility($labelListVisibility);
  $label->setMessageListVisibility($messageListVisibility);
  try {
    $label = $service->users_labels->update($userId, $labelId, $label);
    print 'Label with ID: ' . $labelId . ' successfully updated.';
  } catch (Exception $e) {
    print 'An error occurred: ' . $e->getMessage();
  }
  return $label;
}

Python

Uses the Python client library.

"""Update a particular Label in the user's mailbox.
"""

from apiclient import errors


def UpdateLabel(service, user_id, label_id, updated_label_object):
  """Update an existing Label.

  Args:
    service: Authorized Gmail API service instance.
    user_id: User's email address. The special value "me"
    can be used to indicate the authenticated user.
    label_id: ID of the Label to update.
    updated_label_object: Updated Label.

  Returns:
    Updated Label.
  """
  try:
    updated_label_object['id'] = label_id
    updated_label = (service.users().labels()
                     .update(userId=user_id, id=label_id,
                             body=updated_label_object).execute())
    print 'label id: %s - label name: %s' % (updated_label['id'],
                                             updated_label['name'])
    return updated_label
  except errors.HttpError, error:
    print 'An error occurred: %s' % error


def MakeLabel(label_name, mlv='show', llv='labelShow'):
  """Create Label object.

  Args:
    label_name: The name of the Label.
    mlv: Message list visibility, show/hide.
    llv: Label list visibility, labelShow/labelHide.

  Returns:
    Created Label.
  """
  label = {'messageListVisibility': mlv,
           'name': label_name,
           'labelListVisibility': llv}
  return label

JavaScript

Does not use a client library.

/**
 * Update an existing Label.
 *
 * @param  {String} userId User's email address. The special value 'me'
 * can be used to indicate the authenticated user.
 * @param  {String} labelId ID of Label to be updated.
 * @param  {String} labelName Updated name.
 * @param  {String} labelListVisibility Updated Label list visibility.
 * @param  {String} messageListVisibility Updated Message list visibility.
 * @param  {Function} callback Function to call when the request is complete.
 */
function updateLabel(userId, labelId, labelName, labelListVisibility, messageListVisibility, callback) {
  var request = gapi.client.gmail.users.labels.update({
    'userId': userId,
    'id': labelId,
    'resource': {
      'id': labelId,
      'name': labelName,
      'labelListVisibility': labelListVisibility,
      'messageListVisibility': messageListVisibility
    }
  });
  request.execute(callback);
}

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.