Search code examples
apigoogle-apigmail-api

How to use the fields parameter when calling the Gmail API

I am using the Gmail API in Google Apps Script (which is basically Javascript), and I need to make as few calls to the API as possible, for efficiency and speed.

I'm using Users.messages: list to list the messages in a user's mailbox, and the response includes an array called messages, and for each message it includes an id and a threadId, like so: 

 "messages": [
  {
   "id": "152b93b1111c33e2",
   "threadId": "152b922266c33e2"
  },
  {
   "id": "152b93338c98cb3",
   "threadId": "152b922266c33e2"
  } ...

But I need the response to include more information about each message, so that I don't have to make a separate Users.messages:get call for each message.

The APIs Explorer on the Users.messages: list page says you can use the fields parameter to "specify which fields to include in a partial response."

When I click "Use fields editor" to select the three items I need, it fills the following in to the field: 

messages(id,internalDate,payload)

Then when I execute the command, it shows that the GET command should look like this: 

https://www.googleapis.com/gmail/v1/users/[email protected]/messages?fields=messages(id%2CinternalDate%2Cpayload)&key={YOUR_API_KEY}

However, the messages array in the results does not include the internalDate or the payload fields. It just includes the message id only, like so: 

 "messages": [
  {
   "id": "152b93b1111c33e2"
  },
  {
   "id": "152b93338c98cb3"
  } ...

It also does not include the threadId anymore, but it DOES continue to include the threadId if I select that as one of the fields, like so: 

messages(id,threadId)

and the URL looks like this... 

https://www.googleapis.com/gmail/v1/users/[email protected]/messages?fields=messages(id%2CthreadId)&key={YOUR_API_KEY}

And the result looks exactly like the first result above, where we weren't using the fields parameter.

So I know the fields parameter is actually doing something.

Thinking this might just be a limitation of the APIs Explorer, I tried making the API call in Google Apps script, but it still does not include the fields I need.

Solution

  • You are almost there.

    When listing messages, theid and threadId of each message is all you get. You then have to get each message separately.

    If you e.g. just want the internalDate of the message, it is in this request it should be specified in the fields parameter.

    Request

    GET https://www.googleapis.com/gmail/v1/users/me/messages/152b792a91c9c391?fields=internalDate&key={YOUR_API_KEY}

    Response

    {
 "internalDate": "1454778787000"
}