E-mail Actions
E-mail Actions are used to interact with e-mail servers sending and receiving messages.
To send e-mails is necessary to have a SMTP credential to the Mail Server, and for receiving e-mails, you must have an IMAP ou POP3 credential to Mail Server.
Important: We strongly recomend to use IMAP connections for receiving e-mails, as this is a much newer protocol, and offer more functionalities and better control.
Actions
email.close
Closes the active connection with the Mail Server.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
quit (optional) - when using POP3 client, to persist all read e-mails and deletions, the quit parameter should be setter to True.
Returns:
This action gives no return.
Exceptions:
This action gives no exceptions.
email.create_imap_client
Create a new connection to the Mail Server, using IMAP protocol.
Parameters:
user - user to authenticate with the Mail Server
password - password to authenticate with Mail Server
host - IP or name to connect with Mail Server
port (optional) - port on Mail Server used for IMAP connection (default=995).
default_folder (optional) - name of the mailbox to start reading (deafult='inbox').
Returns:
email_client - email_client to be used on other email actions.
emails_count - return the total number of e-mails on default_folder.
current_folder - name of the current folder.
Exceptions:
This action gives no exceptions.
email.create_pop_client
Create a new connection to the Mail Server, using POP3 protocol.
Parameters:
user - user to authenticate with the Mail Server
password - password to authenticate with Mail Server
host - IP or name to connect with Mail Server
port (optional) - port on Mail Server used for IMAP connection (default=995).
Returns:
email_client - email_client to be used on other email actions.
email_count - return the total number of e-mails on default_folder.
Exceptions:
This action gives no exceptions.
email.delete
Deletes the current message.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
This action gives no return.
Exceptions:
This action gives no exceptions.
email.find_attachments
Permit to return all attachments on the current e-mail or search a specific attachment by name and/or mime type.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
attach_name (optional) - name or partial name of the attachment to look for (default=don't filter by name)
mime_type (optional) - mime type to filter attachments (default=don't filter by mime type)
only_attachments (optional) - Setted to True will include files setted as attachment. Setted to False will include all files, attachments and inline (default=True)
Returns:
attachments - list with all attachments that satisfy the search.
attachments_count - number of attachments that satisfy the search.
Exceptions:
This action gives no exceptions.
email.get_current_email
Return the e-mail message on current position at e-mail client.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
from - text with name (if defined) and e-mail address of the message sender.
from_address - return only the e-mail address of the message sender.
to - text with name (if defined) and e-mail address of recipients.
subject - subject of the e-mail message.
date - data and time when message was sent.
body - content of e-mail message as plain text.
html_body - content of e-mail message as HTML content.
attachments_count - number of attachments in message.
has_attachments - boolean variable setting if e-mail message has attachments or not.
Exceptions:
This action gives no exceptions.
email.list_folders
Return a list of all folder available on connected e-mail account.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
folders - list with the name of all folders of connected e-mail account.
Exceptions:
This action gives no exceptions.
email.move_to
Move the current e-mail to other existing folder of e-mail account.
This action is available only for IMAP clients.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
to_folder - name of the folder where the current message should be moved to.
Returns:
This action has no returns.
Exceptions:
This action gives no exceptions.
email.next_email
Move current position to next e-mail (next newer message).
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
from - text with name (if defined) and e-mail address of the message sender.
from_address - return only the e-mail address of the message sender.
to - text with name (if defined) and e-mail address of recipients.
subject - subject of the e-mail message.
date - data and time when message was sent.
body - content of e-mail message as plain text.
html_body - content of e-mail message as HTML content.
attachments_count - number of attachments in message.
has_attachments - boolean variable setting if e-mail message has attachments or not.
Exceptions:
This action gives no exceptions.
email.previous_email
Move current position to previous e-mail (next older message).
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
from - text with name (if defined) and e-mail address of the message sender.
from_address - return only the e-mail address of the message sender.
to - text with name (if defined) and e-mail address of recipients.
subject - subject of the e-mail message.
date - data and time when message was sent.
body - content of e-mail message as plain text.
html_body - content of e-mail message as HTML content.
attachments_count - number of attachments in message.
has_attachments - boolean variable setting if e-mail message has attachments or not.
Exceptions:
This action gives no exceptions.
email.save_attachment
Save attachments to a folder, maintaining the same attachment name as e-mail.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
file_path - path to foler where attachments should be saved.
attach_name (optional) - name or partial name of the attachment to look for (default=don't filter by name)
mime_type (optional) - mime type to filter attachments (default=don't filter by mime type)
only_attachments (optional) - Setted to True will include files setted as attachment. Setted to False will include all files, attachments and inline (default=True)
Returns:
saved_files - list with complete file path, to saved files
Exceptions:
FileNotFoundException - when no attach is found for the given filters
email.search
Save attachments to a folder, maintaining the same attachment name as e-mail.
This action is available only for IMAP clients.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
search_filter - search filter to apply on current folder, as defined in IMAP search specification. For futher information access https://tools.ietf.org/html/rfc3501#page-49
Returns:
emails_count - return the total number of e-mails on default_folder.
Exceptions:
This action gives no exceptions.
email.select_folder
Change current folder to the given folder name
This action is available only for IMAP clients.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
folder - name of new folder to point mailbox to
Returns:
current_folder - name of current folder, after folder change emails_count - return the total number of e-mails on new folder.
Exceptions:
This action gives no exceptions.
email.send_email
Send a e-mail message using SMTP protocol. To use this action, you must have a user and password allowed to send messages to your Mail Server.
Parameters:
sender - e-mail to insert on field FROM of the message.
to - e-mails to insert on field TO of message.
subject - subject of the message.
smtp_user - username to authenticate with SMTP server.
smtp_password - password to authenticate with SMTP server.
smtp_server - IP or hostname of the SMTP server.
smtp_port - port to connect on SMTP server (default=25).
tls - defines if TLS should be used on communication with server (default=False).
text - content of the message as plain text (default=no text message).
html - content of the message as HTML text (default=no html message).
attach_path - path to folder to be attached on the message (default=no attachment).
Returns:
saved_files - list with complete file path, to saved files
Exceptions:
AuthorizationException - when a problem with server authentication occurs
MarvinRuntimeException - when a problem with mail server communication occurs
email.store
Execute the IMAP store command, for other server specific actions. This allows to work with flags that are specific to the server or mail provider.
This action is available only for IMAP clients.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
message - store message to be sent to server.
value - value to be setted to message.
Returns:
emails_count - return the total number of e-mails on default_folder.
Exceptions:
This action gives no exceptions.
email.update_mailbox
Update information of e-mail count and list of e-mails inside the current folder.
Parameters:
email_client - client connection to Mail Server. Connections are created using email.create_imap_client or email.create_pop_client
Returns:
emails_count - return the total number of e-mails on default_folder.
Exceptions:
This action gives no exceptions.