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:
E-mail Actions
E-mail actions allow sending and receiving messages using SMTP/IMAP/POP3.
Note: only methods decorated with @decorators.robotaction are documented here. Action returns are mapped to robot state variables — for example, if an action returns {'emails_count': 10} you access it with $emails_count.
Use SMTP for sending and IMAP for receiving when possible; some actions are IMAP-only (noted where applicable).
Exposed methods
email.send_email
Send an e-mail using SMTP.
Parameters:
- sender — FROM address.
- to — recipients (string with ; or a list).
- subject — message subject.
- smtp_user, smtp_password, smtp_server — SMTP credentials/host.
- smtp_port (optional, default 25) — server port.
- tls (optional, default False) — use STARTTLS when True (otherwise uses SSL).
- text / html (optional) — message body.
- attach_path (optional) — path or list of paths to attachments (assets).
- signature_img (optional) — image asset to embed in HTML signature.
- no_auth (optional) — if True skip server login.
- to_cc / to_bcc (optional) — CC / BCC recipients (string or list).
Returns: none.
Exceptions:
- AuthorizationException on SMTP auth failure.
- MarvinRuntimeException on other SMTP errors.
email.create_imap_client
Create and connect an IMAP client.
Parameters:
- user, password, host.
- port (optional, default 995).
- default_folder (optional, default 'inbox').
Returns (state variables):
- email_client — connection object.
- emails_count — total number of emails in the default folder.
- current_folder — folder name (usually default_folder).
email.create_pop_client
Create and connect a POP3 client.
Parameters:
- user, password, host.
- port (optional, default 995).
Returns:
- email_client — connection object.
- emails_count — total number of emails.
email.get_current_email
Return the email fields from the current position in the client.
Parameters:
- email_client.
Returns (state variables):
- from, from_address, to, subject, date, body, html_body, attachments_count, has_attachments.
email.next_email / email.previous_email
Move to next/previous message and return the same fields as get_current_email.
Parameters:
- email_client.
Returns: same keys as get_current_email.
email.update_mailbox
Refresh mailbox information for the current folder.
Parameters:
- email_client.
Returns:
- emails_count — total emails in current folder.
email.delete
Delete the current message.
Parameters:
- email_client.
Returns:
- emails_count — updated email count.
email.close
Close the active connection.
Parameters:
- email_client.
- quit (optional) — for POP3 use quit=True to persist deletions/changes.
Returns: none.
email.list_folders
List folders available in the connected account.
Parameters:
- email_client.
Returns:
- folders — list of folder names.
email.select_folder
Change current folder (IMAP only).
Parameters:
- email_client, folder.
Returns:
- current_folder, emails_count.
email.search
Execute an IMAP search with the provided filter (IMAP only).
Parameters:
- email_client, search_filter (IMAP RFC3501).
Returns:
- emails_count — total matching/after-refresh count.
email.move_to
Move the current message to another folder (IMAP only).
Parameters:
- email_client, to_folder.
Returns:
- emails_count — updated count.
email.store
Execute an IMAP STORE command for server-specific flags (IMAP only).
Parameters:
- email_client, message, value.
Returns: none.
email.find_attachments
Return attachments from the current email, filtered by name and/or mime type.
Parameters:
- email_client, attach_name (optional), mime_type (optional), only_attachments (optional, default True).
Returns:
- attachments, attachments_count.
email.save_attachment
Save attachments from the current email to disk.
Parameters:
- email_client, file_path, attach_name (optional), mime_type (optional), only_attachments (optional, default True).
Returns:
- saved_files — list of saved file paths.
Exceptions:
- FileNotFoundException when no attachments match the filters.
If you want, I can add short usage examples (e.g. how to read $saved_files or $attachments_count) or propose small safe fixes for email.py.