IssueTracker

The problem:

Messages can be snoozed in Gmail, however, no information related to the snooze is accessible through the API.

Explanation

Firstly, When accessing the messages, snoozed messages does not have any indication as to when the message re-entered the inbox. This makes the messages seemingly appear out of order in the INBOX.

Secondly, messages in:snoozed do no share as to when they will reenter the INBOX, while the information still available in the web UI.

Lastly, as stated in issue #109952618, snooze is widespread amongst 3rd party clients and providing the API would enable those to integrate better with Gmail.

Implemenatation ideas

While the feature is prevalent, there is no common standard, so there are no bounds as to how to implement this.

Option 1: extra mail headers (X-Snoozed)

Add the snoozed information as extra mail headers, for example:

X-Snoozed: at <date-time>; until <date-time>
# or
X-Snoozed-At: <date-time>
X-Snoozed-Until: <date-time>

The at could be optional as that might not be as interesting as the until part.

• Pros:
  • compatible through IMAP and POP3 out of the box
  • does not need to change the API return object (new fields)
• Cons
  • harder for users to find the requested information
  • might break header checksums (if used)
  • could require an RFC to ensure to standardize

Option 1/a: additional Received

Add the information as an additional Received header.

This is is quite hacky, as that is not the purpose of the Received header. but wanted to mention as an alternative, since those headers contain the date the mail was received.

Option 2: new method on the endpoint

Add the information through a new method on the endpoint. For example:

GET https://www.googleapis.com/gmail/v1/users/me/messages/snoozed

and the returned object could have the "message" object, and next to it a "snoozed" object, like:

[{
  "message": { ... },
  "snoozed": {
    "at": "date-time or timestamp",
    "until": "date-time or timestamp"
  }
}, ...]

• Pros:
  • easily discoverable by users
  • easily consumed by applications
  • no need to touch the message headers
• Cons:
  • new method to add or at least
  • new/changed returned object type
  • not visible through IMAP or POP3

Option 2/a: variants

Obviously, the aforementioned object example can be refined based on what internal design principles:

• the snoozed object could be flattened to snoozedUntil and snoozedAt fields
  • again, snoozedAt being optional
• the snoozed information could reside inside the message object (in either form)
• the message (and/or thread) can be referenced by id instead of sending down the whole message (example below)

{
  "messageId": "<id>",
  "threadId": "<id>",
  "snoozedUntil": "<date-time>"
}

Option 1+2: why not both?

Provide the information both through Internet Message Headers X-Snoozed* and the REST API.

This needs extra work, but would provide with more consistency (between user agents) and less astonishment (for users and developers).

Closing thoughts

While this wasn't meant to be a specification, I hope that the effort put into implementation ideas was worth, and this issue will be picked up.