botcity.plugins.email.BotEmailPlugin

__init__()

BotEmailPlugin.

config_email(server, email, password) classmethod

Configure the IMAP and SMTP with the default configuration from the server and login with an email account.

Parameters:

Name	Type	Description	Default
server	BotMailServers	The server defined in the BotMailServers class that will be used in the configuration.	required
email	str	The user email.	required
password	str	The user password.	required

Returns:

Name	Type	Description
BotEmailPlugin		A configured email instance.

configure_imap(host_address='imap.gmail.com', port=993, tls_ssl=False)

Configure the IMAP server.

Parameters:

Name	Type	Description	Default
host_address	str	The email host address to use. Defaults to Gmail server.	'imap.gmail.com'
port	int	The port that will be used by the IMAP server. Defaults to 993 if	993
tls_ssl	boolean	Whether tls/ssl protocols will be used.	False

configure_smtp(host_address='smtp.gmail.com', port=587, tls_ssl=True)

Configure the SMTP server.

Parameters:

Name	Type	Description	Default
host_address	str	The email host address to use. Defaults to Gmail server.	'smtp.gmail.com'
port	int	The port that will be used by the SMTP server. Defaults to 587.	587
tls_ssl	boolean	Whether tls/ssl protocols will be used.	True

copy(message, folder)

Copy a email message from current folder to a destination folder.

Parameters:

Name	Type	Description	Default
message	MailMessage	The message to be copied.	required
folder	str	The name of the destination folder.	required

Note

This method can only be used with an IMAP server configured.

create_folder(folder_name)

Create a new email folder.

Parameters:

Name	Type	Description	Default
folder_name	str	The name of the folder to be created.	required

Note

This method can only be used with an IMAP server configured.

delete(message)

Delete a email message from current folder.

Parameters:

Name	Type	Description	Default
message	MailMessage	The message to be deleted.	required

Note

This method can only be used with an IMAP server configured.

delete_folder(folder_name)

Delete a email folder.

Parameters:

Name	Type	Description	Default
folder_name	str	The name of the folder to be deleted.	required

Note

This method can only be used with an IMAP server configured.

disconnect()

Close the connection with de IMAP and SMTP server.

download_attachments(message, download_folder_path)

Download attachments from a given email message.

Parameters:

Name	Type	Description	Default
message	MailMessage	The message that contains the attachments.	required
download_folder_path	str	The path of the folder where the files will be saved.	required

filter_by(filter, value, timeout=0)

Search for all emails based on a specific filter.

Parameters:

Name	Type	Description	Default
filter	BotMailFilters	The attribute defined in the BotMailFilters class that will be used in the filter.	required
value		The value of the selected filter.	required
timeout	int	Wait for a new message until this timeout. Defaults to 0 seconds (don't wait for new messages).	0

Returns:

Type	Description
List[MailMessage]	List[MailMessage]: The list of emails found.

Note

This method can only be used with an IMAP server configured.

forward(msg, to_addrs, cc_addrs=None, bcc_addrs=None, include_attachments=True, use_html=False)

Forward a received email message.

Parameters:

Name	Type	Description	Default
msg	Message	The message to forward.	required
to_addrs	List[str]	The list of email addresses that will receive the message.	required
cc_addrs	List[str]	The list of email addresses that will receive the message as CC.	None
bcc_addrs	List[str]	The list of email addresses that will receive the message as BCC.	None
include_attachments	boolean	Include attachments from the original message.	True
use_html	bool	The boolean value when you want to use body in html format.	False

Note

This method can only be used with an SMTP server configured.

get_folder_status(folder_name)

Get folder status info.

Parameters:

Name	Type	Description	Default
folder_name	str	The name of the folder to get info.	required

Returns:

Type	Description
Dict[str, str]	Dict[str]: Folder status info.

Note

This method can only be used with an IMAP server configured.

get_folders()

Get a list of available email folders.

Returns:

Type	Description
List[str]	List[str]: The list containing the name of the folders.

Note

This method can only be used with an IMAP server configured.

login(email, password)

Log in with a valid email account.

Parameters:

Name	Type	Description	Default
email	str	The user email.	required
password	str	The user password.	required

mark_as_read(msg)

Mark a received email message as read.

Parameters:

Name	Type	Description	Default
msg	MailMessage	The message to mark.	required

Note

This method can only be used with an IMAP server configured.

mark_as_unread(msg)

Mark a received email message as unread.

Parameters:

Name	Type	Description	Default
msg	MailMessage	The message to mark.	required

Note

This method can only be used with an IMAP server configured.

move(message, folder)

Move a email message from current folder to a destination folder.

Parameters:

Name	Type	Description	Default
message	MailMessage	The message to be moved.	required
folder	str	The name of the destination folder.	required

Note

This method can only be used with an IMAP server configured.

reply(msg, text_content, attachments=None, to_addrs=None, cc_addrs=None, bcc_addrs=None, use_html=False)

Reply a received email message.

Parameters:

Name	Type	Description	Default
msg	MailMessage	The message to reply.	required
text_content	str	The content of the email body.	required
attachments	List[str]	The list with the paths of the files that will be sent as attachments.	None
to_addrs	List[str]	The list of email addresses that will receive the message.	None
cc_addrs	List[str]	The list of email addresses that will receive the message as CC.	None
bcc_addrs	List[str]	The list of email addresses that will receive the message as BCC.	None
use_html	bool	The boolean value when you want to use body in html format.	False

Note

This method can only be used with an SMTP server configured.

reply_to_all(msg, text_content, attachments=None, use_html=False)

Reply to all email addresses included in the original message.

Parameters:

Name	Type	Description	Default
msg	Message	The message to reply.	required
text_content	str	The content of the email body.	required
attachments	List[str]	The list with the paths of the files that will be sent as attachments.	None
use_html	bool	The boolean value when you want to use body in html format.	False

Note

This method can only be used with an SMTP server configured.

search(criteria='ALL', mark_read=False, timeout=0)

Search for all emails based on criteria.

See about search strings here: https://www.marshallsoft.com/ImapSearch.htm

Parameters:

Name	Type	Description	Default
criteria	str	The criteria to be used in the search. Defaults to 'ALL', in this case all emails in the folder will be returned.	'ALL'
mark_read	boolean	Whether the email should be marked as read. Defaults to False.	False
timeout	int	Wait for a new message until this timeout. Defaults to 0 seconds (don't wait for new messages).	0

Returns:

Type	Description
List[MailMessage]	List[MailMessage]: The list of emails found.

Note

This method can only be used with an IMAP server configured.

select_folder(folder='INBOX')

Select the folder that will be used as a reference.

Parameters:

Name	Type	Description	Default
folder	str	The folder name. Defaults to INBOX, to see the available folders use get_folders().	'INBOX'

Note

This method can only be used with an IMAP server configured.

send_message(subject, text_content, to_addrs, cc_addrs=None, bcc_addrs=None, attachments=None, use_html=False)

Send an email message through the SMTP protocol.

Parameters:

Name	Type	Description	Default
subject	str	The subject of the email.	required
text_content	str	The content of the email body.	required
to_addrs	List[str]	The list of email addresses that will receive the message.	required
cc_addrs	List[str]	The list of email addresses that will receive the message as CC.	None
bcc_addrs	List[str]	The list of email addresses that will receive the message as BCC.	None
attachments	List[str]	The list with the paths of the files that will be sent as attachments.	None
use_html	bool	The boolean value when you want to use body in html format.	False

Note

This method can only be used with an SMTP server configured.