platypush.plugins.mail.imap

class platypush.plugins.mail.imap.MailImapPlugin(server: str, port: Optional[int] = None, username: Optional[str] = None, password: Optional[str] = None, password_cmd: Optional[str] = None, access_token: Optional[str] = None, oauth_mechanism: Optional[str] = 'XOAUTH2', oauth_vendor: Optional[str] = None, ssl: bool = False, keyfile: Optional[str] = None, certfile: Optional[str] = None, timeout: Optional[int] = 60, **kwargs)[source]

Plugin to interact with a mail server over IMAP.

Requires:

  • imapclient (pip install imapclient)

__init__(server: str, port: Optional[int] = None, username: Optional[str] = None, password: Optional[str] = None, password_cmd: Optional[str] = None, access_token: Optional[str] = None, oauth_mechanism: Optional[str] = 'XOAUTH2', oauth_vendor: Optional[str] = None, ssl: bool = False, keyfile: Optional[str] = None, certfile: Optional[str] = None, timeout: Optional[int] = 60, **kwargs)[source]
Parameters
  • server – Server name/address.

  • port – Port (default: 143 for plain, 993 for SSL).

  • username – IMAP username.

  • password – IMAP password.

  • password_cmd – If you don’t want to input your password in the configuration, run this command to fetch or decrypt the password.

  • access_token – OAuth2 access token if the server supports OAuth authentication.

  • oauth_mechanism – OAuth2 mechanism (default: XOAUTH2).

  • oauth_vendor – OAuth2 vendor (default: None).

  • ssl – Use SSL (default: False).

  • keyfile – Private key file for SSL connection if client authentication is required.

  • certfile – SSL certificate file or chain.

  • timeout – Server connect/read timeout in seconds (default: 60).

add_flags(messages: List[int], flags: Union[str, List[str]], folder: str = 'INBOX', **connect_args)[source]

Add a set of flags to the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • flags

    List of flags to be added. Examples:

    ['Flagged']
    ['Seen', 'Deleted']
    ['Junk']
    

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

copy_messages(messages: List[int], dest_folder: str, source_folder: str = 'INBOX', **connect_args)[source]

Copy a set of messages IDs from a folder to another.

Parameters
  • messages – List of message IDs.

  • source_folder – Source folder.

  • dest_folder – Destination folder.

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

create_folder(folder: str, **connect_args)[source]

Create a folder on the server.

Parameters
  • folder – Folder name.

  • connect_args

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

delete_folder(folder: str, **connect_args)[source]

Delete a folder from the server.

Parameters
  • folder – Folder name.

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

delete_messages(messages: List[int], folder: str = 'INBOX', expunge: bool = True, **connect_args)[source]

Set a specified set of message IDs as deleted.

Parameters
  • messages – List of message IDs.

  • folder – IMAP folder (default: INBOX).

  • expunge – If set then the messages will also be expunged from the folder, otherwise they will only be marked as deleted (default: True).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

expunge_messages(folder: str = 'INBOX', messages: Optional[List[int]] = None, **connect_args)[source]

When messages is not set, remove all the messages from folder marked as Deleted.

Parameters
  • folder – IMAP folder (default: INBOX).

  • messages – List of message IDs to expunge (default: all those marked as Deleted).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

flag_message(message: int, folder: str = 'INBOX', **connect_args)[source]

Add a flag/star to the specified set of message ID.

Parameters
  • message – Message ID.

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

flag_messages(messages: List[int], folder: str = 'INBOX', **connect_args)[source]

Add a flag/star to the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

get_folders(folder: str = '', pattern: str = '*', **connect_args)List[Dict[str, str]][source]

Get the list of all the folders hosted on the server or those matching a pattern.

Parameters
  • folder – Base folder (default: root).

  • pattern – Pattern to search (default: None).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

Returns

Example:

[
    {
        "name": "INBOX",
        "flags": "\Noinferiors",
        "delimiter": "/"
    },
    {
        "name": "Archive",
        "flags": "\Noinferiors",
        "delimiter": "/"
    },
    {
        "name": "Spam",
        "flags": "\Noinferiors",
        "delimiter": "/"
    }
]
get_message(message: int, folder: str = 'INBOX', **connect_args)platypush.plugins.mail.Mail[source]

Get the full content of a message given the ID returned by search().

Parameters
  • message – Message ID.

  • folder – Folder name (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

Returns

A message in the same format as search(), with an added payload attribute containing the body/payload.

get_sub_folders(folder: str = '', pattern: str = '*', **connect_args)List[Dict[str, str]][source]

Get the list of all the sub-folders hosted on the server or those matching a pattern.

Parameters
  • folder – Base folder (default: root).

  • pattern – Pattern to search (default: None).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

Returns

Example:

[
    {
        "name": "INBOX",
        "flags": "\Noinferiors",
        "delimiter": "/"
    },
    {
        "name": "Archive",
        "flags": "\Noinferiors",
        "delimiter": "/"
    },
    {
        "name": "Spam",
        "flags": "\Noinferiors",
        "delimiter": "/"
    }
]
move_messages(messages: List[int], dest_folder: str, source_folder: str = 'INBOX', **connect_args)[source]

Move a set of messages IDs from a folder to another.

Parameters
  • messages – List of message IDs.

  • source_folder – Source folder.

  • dest_folder – Destination folder.

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

remove_flags(messages: List[int], flags: Union[str, List[str]], folder: str = 'INBOX', **connect_args)[source]

Remove a set of flags to the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • flags

    List of flags to be added. Examples:

    ['Flagged']
    ['Seen', 'Deleted']
    ['Junk']
    

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

rename_folder(old_name: str, new_name: str, **connect_args)[source]

Rename a folder on the server.

Parameters
  • old_name – Previous name

  • new_name – New name

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

search(criteria: Union[str, List[str]] = 'ALL', folder: str = 'INBOX', attributes: Optional[List[str]] = None, **connect_args)List[platypush.plugins.mail.Mail][source]

Search for messages on the server that fit the specified criteria.

Parameters
  • criteria

    It should be a sequence of one or more criteria items. Each criteria item may be either unicode or bytes (default: ALL). Example values:

    ['UNSEEN']
    ['SMALLER', 500]
    ['NOT', 'DELETED']
    ['TEXT', 'foo bar', 'FLAGGED', 'SUBJECT', 'baz']
    ['SINCE', '2020-03-14T12:13:45+00:00']
    

    It is also possible (but not recommended) to pass the combined criteria as a single string. In this case IMAPClient won’t perform quoting, allowing lower-level specification of criteria. Examples of this style:

    'UNSEEN'
    'SMALLER 500'
    'NOT DELETED'
    'TEXT "foo bar" FLAGGED SUBJECT "baz"'
    'SINCE 03-Apr-2005'
    

    To support complex search expressions, criteria lists can be nested. The following will match messages that are both not flagged and do not have “foo” in the subject:

    ['NOT', ['SUBJECT', 'foo', 'FLAGGED']]
    

  • folder – Folder to search (default: INBOX).

  • attributes – Attributes that should be retrieved, according to RFC 3501 (default: ALL = [FLAGS INTERNALDATE RFC822.SIZE ENVELOPE]). Note that BODY will be ignored if specified here for performance reasons - use get_message() if you want to get the full content of a message known its ID from search().

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

Returns

List of messages matching the criteria. Example:

[
  {
    "id": 702,
    "seq": 671,
    "flags": [
      "nonjunk"
    ],
    "internal_date": "2020-08-30T00:31:52+00:00",
    "size": 2908738,
    "bcc": {},
    "cc": {},
    "date": "2020-08-30T00:31:52+00:00",
    "from": {
      "test123@gmail.com": {
        "name": "A test",
        "route": null,
        "email": "test123@gmail.com"
      }
    },
    "message_id": "<SOMETHING@mail.gmail.com>",
    "in_reply_to": "<SOMETHING@mail.gmail.com>",
    "reply_to": {},
    "sender": {
      "test123@gmail.com": {
        "name": "A test",
        "route": null,
        "email": "test123@gmail.com"
      }
    },
    "subject": "Test email",
    "to": {
      "me@gmail.com": {
        "name": null,
        "route": null,
        "email": "me@gmail.com"
      }
    }
  }
]
search_flagged_messages(folder: str = 'INBOX', **connect_args)List[platypush.plugins.mail.Mail][source]

Shortcut for search() that returns only the flagged/starred messages.

search_starred_messages(folder: str = 'INBOX', **connect_args)List[platypush.plugins.mail.Mail][source]

Shortcut for search() that returns only the flagged/starred messages.

search_unseen_messages(folder: str = 'INBOX', **connect_args)List[platypush.plugins.mail.Mail][source]

Shortcut for search() that returns only the unread messages.

set_flags(messages: List[int], flags: Union[str, List[str]], folder: str = 'INBOX', **connect_args)[source]

Set a set of flags to the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • flags

    List of flags to be added. Examples:

    ['Flagged']
    ['Seen', 'Deleted']
    ['Junk']
    

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

sort(folder: str = 'INBOX', sort_criteria: Union[str, List[str]] = 'ARRIVAL', criteria: Union[str, List[str]] = 'ALL', **connect_args)List[int][source]

Return a list of message ids from the currently selected folder, sorted by sort_criteria and optionally filtered by criteria. Note that SORT is an extension to the IMAP4 standard so it may not be supported by all IMAP servers.

Parameters
  • folder – Folder to be searched (default: INBOX).

  • sort_criteria

    It may be a sequence of strings or a single string. IMAPClient will take care any required conversions. Valid sort_criteria values:

    .. code-block:: python
    
      ['ARRIVAL']
      ['SUBJECT', 'ARRIVAL']
      'ARRIVAL'
      'REVERSE SIZE'
    

  • criteria – Optional filter for the messages, as specified in search().

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

Returns

A list of message IDs that fit the criteria.

undelete_messages(messages: List[int], folder: str = 'INBOX', **connect_args)[source]

Remove the Deleted flag from the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

unflag_message(message: int, folder: str = 'INBOX', **connect_args)[source]

Remove a flag/star from the specified set of message ID.

Parameters
  • message – Message ID.

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.

unflag_messages(messages: List[int], folder: str = 'INBOX', **connect_args)[source]

Remove a flag/star from the specified set of message IDs.

Parameters
  • messages – List of message IDs.

  • folder – IMAP folder (default: INBOX).

  • connect_args – Arguments to pass to _get_server_info() for server configuration override.