Policy - dylandoamaral/ggmail GitHub Wiki

What is a policy ?

A policy is a rule applied to a mailbox to retrieve a subset of messages.

When you retrieve messages, you don't necessarily want to retrieve all messages. you maybe want to only retrieve messages from a particular person, this is why policies exist.

List of policies

GGmail provides every available policies, here is the list of policies (explanations come from https://www.atmail.com/blog/imap-commands/):

from ggmail.policy import *
from ggmail.flag import Flag
from datetime import date

policy = all_ # All messages in the mailbox
policy = answered # Messages with the \Answered flag set
policy = deleted # Messages with the \Deleted flag set
policy = draft # Messages with the \Draft flag set
policy = flagged # Messages with the \Flagged flag set
policy = new # Messages that have the \Recent flag set but not the \Seen flag
policy = old # Messages that do not have the \Recent flag set
policy = recent # Messages that have the \Recent flag set
policy = seen # Messages that have the \Seen flag set
policy = unanswered # Messages that do not have the \Answered flag set
policy = undeleted # Messages that do not have the \Deleted flag set
policy = undraft # Messages that do not have the \Draft flag set
policy = unflagged # Messages that do not have the \Flagged flag set
policy = unseen # Messages that do not have the \Seen flag set

policy = bcc_contains("[email protected]") # Messages that contain the specified string in the envelope structure’s BCC field
policy = body_contains("body") # Messages that contain the specified string in the body of the message
policy = cc_contains("[email protected]") # Messages that contain the specified string in the envelope structure’s CC field
policy = from_contains("[email protected]") # Messages that contain the specified string in the envelope structure’s FROM field
policy = subject_contains("subject") # Messages that contain the specified string in the envelope structure’s SUBJECT field
policy = text_contains("text") # Messages that contain the specified string in the header or body of the message
policy = to_contains("[email protected]") # Messages that contain the specified string in the envelope structure’s TO field
policy = uid("22") # Messages with unique identifiers corresponding to the specified unique identifier set. Sequence set ranges are permitted

policy = larger_than(10) # Messages with a size larger than the specified number of octets
policy = smaller_than(10) # Messages with a size smaller than the specified number of octets

policy = before(date(2020, 12, 24)) # Messages whose internal date (disregarding time and timezone) is earlier than the specified date
policy = on(date(2020, 12, 24)) # Messages whose internal date (disregarding time and timezone) is within the specified date
policy = sent_before(date(2020, 12, 24)) # Messages whose Date: header (disregarding time and timezone) is earlier than the specified date
policy = sent_on(date(2020, 12, 24)) # Messages whose Date: header (disregarding time and timezone) is within the specified date
policy = sent_since(date(2020, 12, 24)) # Messages whose Date: header (disregarding time and timezone) is within or later than the specified date
policy = since(date(2020, 12, 24)) # Messages whose internal date (disregarding time and timezone) is within or later than the specified date

policy = header("key", "value") # Messages that have a header with the specified field-name and which contain the specified string in the text of the header (i.e. what comes after the colon). If the string to search is zero-length, this matches all messages that have a header line with the specified field-name, regardless of the contents.
policy = keyword(Flag.FLAGGED) # Messages with the specified keyword flag set
policy = unkeyword(Flag.FLAGGED) # Messages that do not have the specified keyword flag set

Operation on policy

Policies can be simple (retrieve the messages coming from a particular person) but they can also be more complexe by composing different policies. GGmail provides a way to write such complexe policies using operator overloading.

from ggmail.policy import from_contains, before
from datetime import date

# Retrieve emails from [email protected] and before 2020-12-24 
policy = from_contains("[email protected]") + before(date(2020, 12, 24))

# Retrieve emails from [email protected] and before 2020-12-24 (accumulation)
policy = from_contains("[email protected]")
policy += before(date(2020, 12, 24))

# Retrieve emails from [email protected] or before 2020-12-24
policy = from_contains("[email protected]") | before(date(2020, 12, 24))

# Retrieve emails from anyone except [email protected]
policy = ~from_contains("[email protected]")