GMAIL API - Date search (timezone unclear)

According to https://developers.google.com/gmail/api/guides/filtering, if you search for a date, the PST timezone is used.

I have an email with:

 Date: Tue, 27 Jul 2021 06:07:49 GMT (06:07 AM)

If you convert this to the PST timezone, it should be:

Date: Mon, 26 Jul 2021 23:07:49 PST (11:07 PM)

Now when i use the query

after:2021/07/27

the email is found but shouldn't be according to the definition (also when i search directly on gmail.com).

For the query

before:2021/07/27

nothing is returned.

I didn't find a description yet on how to correctly search by a date and which timezones are really applied.

I'm using google-api-services-gmail-v1-rev110-1.25.0.jar.

Additional info:

String account = "myemail@gmail.com";

List<String> labelIds = new ArrayList<>();
labelIds.add("Label_mylabelid");
        
String query = "after:2021/07/27";
List<Message> timeZoneMsgs = gmail.users().messages().list(account).setQ(query).setLabelIds(labelIds).execute().getMessages();

I ran another test: I scheduled some emails to be sent between 11:30pm and 01:00am on the next day.

Here are the date headers (directly out of the payload) of the messages:

Scheduled mail 1
Date: Fri, 24 Dec 2021 23:30:00 +0100

Scheduled mail 2
Date: Fri, 24 Dec 2021 23:45:00 +0100

Scheduled mail 3
Date: Sat, 25 Dec 2021 00:00:00 +0100

Scheduled mail 4
Date: Sat, 25 Dec 2021 00:15:00 +0100

Scheduled mail 5
Date: Sat, 25 Dec 2021 00:30:00 +0100

Scheduled mail 6
Date: Sat, 25 Dec 2021 00:45:00 +0100

Scheduled mail 7
Date: Sat, 25 Dec 2021 01:00:00 +0100

If I search with

after:2021/12/25

directly on gmail.com - i get the messages 3 to 7 and if i search with

before:2021/12/25

I get 1 and 2, which is both correct.

BUT when I do the same with the java call, I only get message 7 (1am) for "after:2021/12/25" and messages 1-6 for "before:2021/12/25".

Another example:

I also tried searching with the epoch time in UTC:

Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"));
calendar.clear();
calendar.set(2021, Calendar.DECEMBER, 25);
long secondsSinceEpoch = calendar.getTimeInMillis() / 1000L; // 1640390400

Here, I get the same result for direct gmail.com search and java search: Message 7 (1pm) for "after:1640390400" and 1-6 for "before:1640390400".

If I try this for PST (1640419200), I get no messages for "after:1640419200" and all of them for "before:1640419200".

Solution

As the documentation states:

To specify accurate dates for other timezones pass the value in seconds instead.

This is a Java sample code, is tested and working .For the example I get all the messages from yesterday 23:00 to today 13:00. Tip: You can use me as a keyword to your email account:

long startTimeEpoch = LocalDateTime.parse("2021-12-27T23:00",
    DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm")).toEpochSecond(ZoneOffset.UTC);
long endTimeEpoch = LocalDateTime.parse("2021-12-28T13:00",
    DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm")).toEpochSecond(ZoneOffset.UTC);
String query = String.format("after:%s before:%s", startTimeEpoch, endTimeEpoch);
String account = "me";
System.out.println(query);
List < String > labelIds = new ArrayList < > ();
labelIds.add("Label_mylabelid");
List < Message > timeZoneMsgs = service.users().messages().list(account)
    .setQ(query)
    .execute()
    .getMessages();
System.out.println(timeZoneMsgs);

GMAIL API - Date search (timezone unclear)

Documentation: