According to gmail's API docs, the limits are as follows:
API Limit Type Limit
Daily Usage 1,000,000,000 quota units per day
Per User Rate Limit 250 quota units per user per second, moving average (allows short bursts)
In the table further below, the docs say that a messages.get costs 5 quota units.
In my case, I am interesting in polling my inbox every second to check for new messages, and get the contents of those messages if there any.
Question 1: Does this mean that I'd be spending 5 quota units each second, and that I'd be well under my quota?
Question 2: How should check for only "new" messages? That is, messages that have arrived since the last time I made the API call? Would I need to add "read" labels to the messages after each API call (spending extra quota units on the "modify" API call), or is there an easier way?
Question 1:
That's right. You would spend (5 * 60 * 60 * 24 =) 432000 quota points on the polling, which is nowhere near the limit. You could also implement push notifications if you want Google to notify you of new messages rather than polling yourself.
Question 2:
Listing messages has an undocumented feature of querying for messages after a certain timestamp, given in seconds since the epoch.
If you would like to get messages after Sun, 29 May 2016 07:00:00 GMT, you would just give the the value after:1464505200 in the q query parameter.