Skip to content

botcity.plugins.email.plugin.BotEmailPlugin

__init__(self) special

BotEmailPlugin

config_email(server, email, password) classmethod

Configures 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:

Type Description
BotEmailPlugin

A configured email instance.

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

Configures 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.

993
tls_ssl boolean

Whether tls/ssl protocols will be used.

False

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

Configures 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(self, 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.

delete(self, 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.

disconnect(self)

Close the connection with de IMAP and SMTP server.

download_attachments(self, 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(self, filter, value, timeout=0)

Searches 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]

The list of emails found.

Note

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

forward(self, 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_folders(self)

Get a list of available email folders.

Returns:

Type Description
List[str]

The list containing the name of the folders.

Note

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

login(self, 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(self, 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(self, 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(self, 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(self, 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(self, msg, text_content, attachments=None, use_html=False)

Replies 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(self, criteria='ALL', mark_read=False, timeout=0)

Searches 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]

The list of emails found.

Note

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

select_folder(self, 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(self, 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.