Skip to content

E-mail

E-mail actions allow sending and receiving messages using SMTP/IMAP/POP3.

To send e-mail you need SMTP credentials; for receiving, use IMAP or POP3. We recommend IMAP when possible — newer protocol with better functionality.

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.

Important: We strongly recommend using IMAP for receiving e-mail.

Actions

email.close

Close the active connection.

Parameters:
  • email_client.
  • quit (optional) — for POP3 use quit=True to persist deletions/changes.
Return:

none.

email.create_imap_client

Create and connect an IMAP client.

Parameters:
  • user, password, host.
  • port (optional, default 995).
  • default_folder (optional, default 'inbox').
Return:
  • 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).
Return:
  • email_client — connection object.
  • emails_count — total number of emails.

email.delete

Delete the current message.

Parameters:
  • email_client.
Return:
  • emails_count — updated email count.

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).
Return:
  • attachments, attachments_count.

email.get_current_email

Return the email fields from the current position in the client.

Parameters:
  • email_client.
Return:
  • from, from_address, to, subject, date, body, html_body, attachments_count, has_attachments.

email.list_folders

List folders available in the connected account.

Parameters:
  • email_client.
Return:
  • folders — list of folder names.

email.move_to

Move the current message to another folder (IMAP only).

Parameters:
  • email_client, to_folder.
Return:
  • emails_count — updated count.

email.next_email

Move to the next message in the current mailbox and return its details.

Parameters:

email_client - client instance from email.create_imap_client or email.create_pop_client.

Return:

from - sender display name/address.

from_address - sender e-mail address.

to - recipients.

subject - message subject.

date - message date.

body - plain-text body.

html_body - HTML body.

attachments_count - number of attachments.

has_attachments - whether the message has attachments.

Exceptions:

This action gives no exceptions

email.previous_email

Move to the previous message in the current mailbox and return its details.

Parameters:

email_client - client instance from email.create_imap_client or email.create_pop_client.

Return:

Same keys as email.get_current_email.

Exceptions:

This action gives no exceptions

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).
Return:
  • saved_files — list of saved file paths.
Exceptions:
  • FileNotFoundException when no attachments match the filters.

email.search

Execute an IMAP search with the provided filter (IMAP only).

Parameters:
  • email_client, search_filter (IMAP RFC3501).
Return:
  • emails_count — total matching/after-refresh count.

email.select_folder

Change current folder (IMAP only).

Parameters:
  • email_client, folder.
Return:
  • current_folder, emails_count.

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).
Return:

none.

Exceptions:
  • AuthorizationException on SMTP auth failure.
  • MarvinRuntimeException on other SMTP errors.

email.store

Execute an IMAP STORE command for server-specific flags (IMAP only).

Parameters:
  • email_client, message, value.
Return:

none.

email.update_mailbox

Refresh mailbox information for the current folder.

Parameters:
  • email_client.
Return:
  • emails_count — total emails in current folder.