YouPS documentation

Message object

class Message.Message(message_schema, imap_client, is_simulate=False)
add_labels(labels)

Add each of the label in a list of flags to the message

Examples:
>>> my_message.add_labels(["Todo", "Family"])
Args:

labels (string[]): a list of flags to be added

This method can also optionally take a single string as a flag.

aggregate_response()

Aggregate responses of messages in this thread and return a list of pairs of sender and their response

Examples:
>>> my_message.aggregate_response()
>>> [(Contact object: someone1@mail.com, "Hi all ..."), (Contact object: someone2@mail.com, "Dear all, ...")]
Returns:

t.List[(Contact, t.AnyStr)]: pairs of sender and their response

property bcc

Get the Contacts the message is bcced to

Examples:
>>> my_message.bcc 
>>> [Contact object: someone1@mail.com, Contact object: someone2@mail.com]
Returns:

t.List[Contact]: The contacts in the bcc field of the message

property cc

Get the Contacts the message is cced to

Returns:

t.List[Contact]: The contacts in the cc field of the message

contains(string)

check if a string is contained in the content of a message

Args:

string (str): string to check for

Returns:

bool: true if the passed in string is in the message content

property content

Get the content of the message

See also Message.contains

Returns:

dict {‘text’: t.AnyStr, ‘html’: t.AnyStr}: The content of the message

copy(dst_folder)

Copy the message to another folder.

Args:

dst_folder (str): a name of destination folder

property date

Get the date and time that the message was sent

Returns:

datetime: The date and time the message was sent

property deadline

Get the user-defined deadline of the message (Mutable). When the specified date time is come, user’s deadline handler will be executed.

Returns:

datetime: The deadline

delete(slient=False)

Move this message to your trash folder

extract_response()

For the thread messages, only take out a body of this message without previous headers and contetns

Returns:

t.AnyStr: extracted contents without previous messages contents in the thread

extract_time_entity()

return any time entity (e.g., tomorrow, 3/24 2pm) mentioned in this message body using NLP

Returns:

t.List[“body”: t.AnyStr, “start”: datetime, “end”: datetime]: list of {“body”: “text of the time entity” (string), “start”: “starting time” (datetime), “end”: “ending time” (datetime)}

property flags

Get the flags on the message

Returns:

List(str): List of flags on the message

property folder

Get the Folder the message is contained in

Returns:

Folder: the folder that the message is contained in

forward(to=[], cc=[], bcc=[], subject='', content='')

forward a message

Args:

to (str): cc (str): bcc (str): subject (str): if none is given, it will be “Fwd: ‘original subject’” content (str): You can add additional content on a body of this forwarded message

has_label(label)

Check if the message has a given label

Returns:

bool: True if the flag is on the message else false

property in_reply_to

Get the message ids in the in_reply_to field

Returns:

List(str): List of in_reply_to message ids on the message

property is_deleted

Get if the message has been deleted

Returns:

bool: True if the message has been deleted

property is_read

Get if the message has been read

Returns:

bool: True if the message has been read

property is_recent

Get if the message is recent

Returns:

bool: True if the message is recent

property is_replied

Get if the message is replied

Returns:

bool: True if the message is replied

property is_unread

Get if the message is unread

Returns:

bool: True if the message is unread

mark_read()

Mark a message as read.

mark_unread()

Mark a message as unread

move(dst_folder)

Move the message to another folder.

Args:

dst_folder (str): a name of destination folder

recent_messages(N=3)

Get the N Messages of this thread

Returns:

t.List[Message]: The messages in this thread before this message

property recipients

Shortcut method to get a list of all the recipients of an email.

Returns the people in the to field, cc field, and bcc field Useful for doing things like getting the total number of people a message is sent to

Returns:

t.List[Contact]: All the visible recipients of an email

property references

Get the message ids in the references field

Returns:

List(str): List of references message ids on the message

remove_labels(labels)

Remove each of the flags in a list of labels from the message

Args:

labels (string[]): a list of labels to be added

This method can also optionally take a single string as a label.

reply(to=[], cc=[], bcc=[], content='')

Reply to the sender of this message

Args:

to (str): cc (str): bcc (str): content (str):

reply_all(more_to=[], more_cc=[], more_bcc=[], content='')

Reply to every recipient of this message

Args:

to (str): cc (str): bcc (str): content (str):

property reply_to

Get the Contacts the message is replied to

These are the addresses the message is meant to be sent to if the client hits reply.

Returns:

t.List[Contact]: The contacts in the reply_to field of the message

see_later(later_at=60, hide_in='YouPS see later')

Hide a message to a folder and move it back to a original folder this function is equivalent to following:

def f(msg):

msg.move(‘original_location’)

my_message.on_time(now+later_at, f)

Args:

later_at (int): when to move this message back to inbox (in minutes) hide_in (string): a name of folder to hide this message temporarily

property sender

Get the Contact the message is addressed from

Returns:

Contact: The contact in the from field of the message

property subject

Get the Subject of the message

Returns:

str: The subject of the message

property task

Get the user-defined task of the message (Mutable)

Returns:

str: The tasks

property thread

Return a list of messages in this thread

Returns:

t.List[Message]: a list of Message instances

property to

Get the Contacts the message is addressed to

Returns:

t.List[Contact]: The contacts in the to field of the message

Property

class Message.Message(message_schema, imap_client, is_simulate=False)
add_labels(labels)

Add each of the label in a list of flags to the message

Examples:
>>> my_message.add_labels(["Todo", "Family"])
Args:

labels (string[]): a list of flags to be added

This method can also optionally take a single string as a flag.

aggregate_response()

Aggregate responses of messages in this thread and return a list of pairs of sender and their response

Examples:
>>> my_message.aggregate_response()
>>> [(Contact object: someone1@mail.com, "Hi all ..."), (Contact object: someone2@mail.com, "Dear all, ...")]
Returns:

t.List[(Contact, t.AnyStr)]: pairs of sender and their response

property bcc

Get the Contacts the message is bcced to

Examples:
>>> my_message.bcc 
>>> [Contact object: someone1@mail.com, Contact object: someone2@mail.com]
Returns:

t.List[Contact]: The contacts in the bcc field of the message

property cc

Get the Contacts the message is cced to

Returns:

t.List[Contact]: The contacts in the cc field of the message

contains(string)

check if a string is contained in the content of a message

Args:

string (str): string to check for

Returns:

bool: true if the passed in string is in the message content

property content

Get the content of the message

See also Message.contains

Returns:

dict {‘text’: t.AnyStr, ‘html’: t.AnyStr}: The content of the message

copy(dst_folder)

Copy the message to another folder.

Args:

dst_folder (str): a name of destination folder

property date

Get the date and time that the message was sent

Returns:

datetime: The date and time the message was sent

property deadline

Get the user-defined deadline of the message (Mutable). When the specified date time is come, user’s deadline handler will be executed.

Returns:

datetime: The deadline

delete(slient=False)

Move this message to your trash folder

extract_response()

For the thread messages, only take out a body of this message without previous headers and contetns

Returns:

t.AnyStr: extracted contents without previous messages contents in the thread

extract_time_entity()

return any time entity (e.g., tomorrow, 3/24 2pm) mentioned in this message body using NLP

Returns:

t.List[“body”: t.AnyStr, “start”: datetime, “end”: datetime]: list of {“body”: “text of the time entity” (string), “start”: “starting time” (datetime), “end”: “ending time” (datetime)}

property flags

Get the flags on the message

Returns:

List(str): List of flags on the message

property folder

Get the Folder the message is contained in

Returns:

Folder: the folder that the message is contained in

forward(to=[], cc=[], bcc=[], subject='', content='')

forward a message

Args:

to (str): cc (str): bcc (str): subject (str): if none is given, it will be “Fwd: ‘original subject’” content (str): You can add additional content on a body of this forwarded message

has_label(label)

Check if the message has a given label

Returns:

bool: True if the flag is on the message else false

property in_reply_to

Get the message ids in the in_reply_to field

Returns:

List(str): List of in_reply_to message ids on the message

property is_deleted

Get if the message has been deleted

Returns:

bool: True if the message has been deleted

property is_read

Get if the message has been read

Returns:

bool: True if the message has been read

property is_recent

Get if the message is recent

Returns:

bool: True if the message is recent

property is_replied

Get if the message is replied

Returns:

bool: True if the message is replied

property is_unread

Get if the message is unread

Returns:

bool: True if the message is unread

mark_read()

Mark a message as read.

mark_unread()

Mark a message as unread

move(dst_folder)

Move the message to another folder.

Args:

dst_folder (str): a name of destination folder

recent_messages(N=3)

Get the N Messages of this thread

Returns:

t.List[Message]: The messages in this thread before this message

property recipients

Shortcut method to get a list of all the recipients of an email.

Returns the people in the to field, cc field, and bcc field Useful for doing things like getting the total number of people a message is sent to

Returns:

t.List[Contact]: All the visible recipients of an email

property references

Get the message ids in the references field

Returns:

List(str): List of references message ids on the message

remove_labels(labels)

Remove each of the flags in a list of labels from the message

Args:

labels (string[]): a list of labels to be added

This method can also optionally take a single string as a label.

reply(to=[], cc=[], bcc=[], content='')

Reply to the sender of this message

Args:

to (str): cc (str): bcc (str): content (str):

reply_all(more_to=[], more_cc=[], more_bcc=[], content='')

Reply to every recipient of this message

Args:

to (str): cc (str): bcc (str): content (str):

property reply_to

Get the Contacts the message is replied to

These are the addresses the message is meant to be sent to if the client hits reply.

Returns:

t.List[Contact]: The contacts in the reply_to field of the message

see_later(later_at=60, hide_in='YouPS see later')

Hide a message to a folder and move it back to a original folder this function is equivalent to following:

def f(msg):

msg.move(‘original_location’)

my_message.on_time(now+later_at, f)

Args:

later_at (int): when to move this message back to inbox (in minutes) hide_in (string): a name of folder to hide this message temporarily

property sender

Get the Contact the message is addressed from

Returns:

Contact: The contact in the from field of the message

property subject

Get the Subject of the message

Returns:

str: The subject of the message

property task

Get the user-defined task of the message (Mutable)

Returns:

str: The tasks

property thread

Return a list of messages in this thread

Returns:

t.List[Message]: a list of Message instances

property to

Get the Contacts the message is addressed to

Returns:

t.List[Contact]: The contacts in the to field of the message

Events handler

class Message.Message(message_schema, imap_client, is_simulate=False)
on_response(handler)

add an event handler that is triggered everytime when there is a new message arrived at its thread

Examples:
>>> def f(msg):
>>>    msg.mark_read() # Replies of this message will be marked read
>>> my_message.on_response(f)
Args:

handler (function): A function to execute each time when there are messaged arrvied to this thread. The function provides the newly arrived message as an argument

on_time(handler, later_at=60)

The number of minutes to wait before executing the code. If omitted, the value 60 is used

Args:

handler (function): A function that will be executed. The function provides the newly arrived message as an argument

later_at (int): when to execute the handler (in minutes)

Contact object

class Contact.Contact(contact_schema, imap_client, is_simulate=False)
property aliases

Get all the names associated with this contact

Returns:

list: The names associated with this contact

property email

Get the email address associated with this contact

Returns:

str: The email address associated with this contact

property geolocation

Get the location of this contact (mutable)

Returns:

str: The location associated with this contact

messages(N=3)

Get the N Messages which are exchanged with this contact Examples:

>>> my_message.sender.messages()
>>> [Message object "Hello!", Message object "other message", Message object "another messages.."]
Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the from/to/cc/bcc field

messages_bcc(N=3)

Get the Messages which are bcc this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the bcc field

messages_cc(N=3)

Get the Messages which are cc this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the cc field

messages_from(N=3)

Get the Messages which are from this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the from field

messages_to(N=3)

Get the Messages which are to this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the to field

property name

Get the name associated with this contact

Returns:

str: The name associated with this contact

property organization

Get the organization of this contact (mutable)

Returns:

str: The organization associated with this contact

Property

class Contact.Contact(contact_schema, imap_client, is_simulate=False)
property aliases

Get all the names associated with this contact

Returns:

list: The names associated with this contact

property email

Get the email address associated with this contact

Returns:

str: The email address associated with this contact

property geolocation

Get the location of this contact (mutable)

Returns:

str: The location associated with this contact

messages(N=3)

Get the N Messages which are exchanged with this contact Examples:

>>> my_message.sender.messages()
>>> [Message object "Hello!", Message object "other message", Message object "another messages.."]
Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the from/to/cc/bcc field

messages_bcc(N=3)

Get the Messages which are bcc this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the bcc field

messages_cc(N=3)

Get the Messages which are cc this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the cc field

messages_from(N=3)

Get the Messages which are from this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the from field

messages_to(N=3)

Get the Messages which are to this contact

Args:

N (int): a number of recent messages you want (max:50)

Returns:

t.List[Message]: The messages where this contact is listed in the to field

property name

Get the name associated with this contact

Returns:

str: The name associated with this contact

property organization

Get the organization of this contact (mutable)

Returns:

str: The organization associated with this contact

Events handler

class Contact.Contact(contact_schema, imap_client, is_simulate=False)
on_message(handler)

add an event handler that is triggered everytime when there is a new message arrived from this contact

Args:

handler (function): A function to execute each time when there are messaged arrvied to this thread. The function provides the newly arrived message as an argument

on_time(handler, later_at=60)

The number of minutes to wait before executing the handler.

Args:

handler (function): A function that will be executed. The function provides the contact object as an argument

later_at (int): when to execute the handler (in minutes)

Utility methods

class mailbox.MailBox(imap_account, imap_client, is_simulate=False)
property ME

Return my Contact object

Examples:
>>> ME 
>>> Contact object: myemail@mail.com
Returns:

Contact: The contact in the from field of the message

create_draft(subject='', to='', cc='', bcc='', content='')

Create a draft message and save it to user’s draft folder

Args:

subject (string): the subject line of the draft message

to (a single instance|list of string|Contact): addresses that go in to field

cc (a single instance|list of string|Contact): addresses that go in cc field

bcc (a single instance|list of string|Contact): addresses that go in bcc field

content (string): content of the draft message

create_folder(folder_name)

Create a new folder

Args:

folder_name (string): a name of a new folder

get_current_events()

Get calendar events happening right now, if any

Examples:
>>> get_current_events()
>>> [{"name": "my event", "start": datetime.datetime(2020, 3, 8, 7, 30), "end": datetime.datetime(2020, 3, 8, 8, 30),             "start_text": "2020-03-08 07:30", "end_text": "2020-03-08 08:30"}, ..] # a list of events happening right now
Returns:

t.List[{“name”: t.AnyStr, “start”: datetime, “end”: datetime, “start_text”: t.AnyStr, “end_text”: t.AnyStr}]: a list of event information

get_email_mode()

Get name and uid of the your current mode

Examples:
>>> get_email_mode()
>>> ("my meeting mode", 172)
get_upcoming_events()

Get upcoming calendar events, if any

Examples:
>>> get_upcoming_events()
>>> [] # no upcoming events
Returns:

t.List[{“name”: t.AnyStr, “start”: datetime, “end”: datetime, “start_text”: t.AnyStr, “end_text”: t.AnyStr}]: a list of event information

rename_folder(old_name, new_name)

Rename a folder

Args:

old_name (string): a current name of a folder new_name (string): a new name for the folder

send(subject='', to='', cc='', bcc='', body='', body_html='', smtp='')

Send a message

Args:

subject (string): the subject line of the draft message

to (a single instance|list of string|Contact): addresses that go in to field

cc (a single instance|list of string|Contact): addresses that go in cc field

bcc (a single instance|list of string|Contact): addresses that go in bcc field

body (string): plain text body of a message

body_html (string): html body of a message. Either body or body_html is required

smtp (string): a name of draft folder (optional)

set_email_mode(uid)

Set your current mode to the given mode

Args:

uid (int): uid of one of your email mode