Gmail.Users.Threads.get with metadata scope and metadata format not working

Question

I'm sure it's a pretty stupid thing I'm missing, but I can't quite see it. My Google Apps Script only needs mail headers so it has a very restrictive scope: "https://www.googleapis.com/auth/gmail.metadata". I really don't want to change this scope because it provides just what I need.

Because of this restrictive scope, many API calls will force you to select the METADATA format instead of the default FULL. This can be checked using the API explorer (https://developers.google.com/gmail/api/v1/reference/users/threads/get). Remember to Select JUST the metadata scope, otherwise it will work! :-)

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "forbidden",
    "message": "Metadata scope doesn't allow format FULL"
   }
  ],
  "code": 403,
  "message": "Metadata scope doesn't allow format FULL"
 }
}

Then, from the format drop down menu select "metadata" run again and it will work.

This simple code is enough to replicate the issue:

Code.gs

function getThread() {
  // get the most recent thread
  var thread = Gmail.Users.Threads.list('me', {maxResults: 1});
  Logger.log('thread: %s', thread);
  thread = JSON.parse(thread);
  var threadId = thread.threads[0].id;
  Logger.log('threadId: %s', threadId);
  // scope "https://www.googleapis.com/auth/gmail.metadata"
  // requires me to specify the metadata format
  // next line will error: Metadata scope doesn't allow format FULL
  var thread = Gmail.Users.Threads.get('me', {id: threadId, format: 'metadata'}); 
}

appsscript.json (View -> Show manifest file)

{
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.metadata"],
  "dependencies": {
    "enabledAdvancedServices": [{
      "userSymbol": "Gmail",
      "serviceId": "gmail",
      "version": "v1"
    }]
  },
  "exceptionLogging": "STACKDRIVER"
}

When getThread() function is run, it produces this error:

Metadata scope doesn't allow format FULL (line 10, file "Code.gs")

Gmail API, in particular Gmail.Users.Thread.get documentation (https://developers.google.com/gmail/api/v1/reference/users/threads/get) states:

Optional query parameters format string The format to return the messages in.

Acceptable values are:

"full": Returns the parsed email message content in the payload field and the raw field is not used. (default)
"metadata": Returns email headers with message metadata such as identifiers and labels.
"minimal": Only returns email message metadata such as identifiers and labels, it does not return the email headers, body, or payload.

So it's not clear to me how this API call should be written:

var thread = Gmail.Users.Threads.get('me', {id: threadId, format: 'metadata'});

I've tried all the possible combinations of quotes (single, double and no quotes) with case (upper and lower) and nothing has worked. It seems it's being ignored... :-(

I'm stumped... please help! :-)

Thanks!!

tehhowch tehhowch · Accepted Answer · 2018-04-17T17:36:09

Per the API documentation, Gmail.Users.Threads.get() requires 2 parameters, and has an optional 2 (the format object you indicate):

Path parameters
id string The ID of the thread to retrieve.
userId string The user's email address. The special value me can be used to indicate the authenticated user.

Optional query parameters
format string The format to return the messages in. Acceptable values are:
- "full": Returns the parsed email message content in the payload field and the raw field is not used. (default)
- "metadata": Returns email headers with message metadata such as identifiers and labels.
- "minimal": Only returns email message metadata such as identifiers and labels, it does not return the email headers, body, or payload.
metadataHeaders[] list When given and format is METADATA, only include headers specified.

In Apps Script's Advanced Services Gmail client library, 2 signatures are provided:

The parameters here should be:

userId - the user to request (for your case, "me")
id - the ID of the thread you want to obtain
your optional parameter object

Gmail.Users.Threads.get with metadata scope and metadata format not working

1 Answers