Python API

ImapSmtp

class RPA.Email.ImapSmtp.Action

Bases: enum.Enum

Possible email actions.

glabel_add = 20
glabel_remove = 21
msg_attachment_save = 9
msg_copy = 1
msg_delete = 2
msg_flag = 4
msg_list = 3
msg_move = 10
msg_read = 6
msg_save = 8
msg_unflag = 5
msg_unread = 7
class RPA.Email.ImapSmtp.ImapSmtp(smtp_server: str = None, smtp_port: int = 587, imap_server: str = None, imap_port: int = 993, account: str = None, password: str = None, encoding: str = 'utf-8')

Bases: object

ImapSmtp is a library for sending, reading, and deleting emails. ImapSmtp is interfacing with SMTP and IMAP protocols.

*About criteria argument*

Various keywords like List Messages and Move Messages have keyword argument called criterion which can be used to filter emails according to given criteria.

Syntax needs to according to specification and more information about that can be read from https://robocorp.com/docs/development-guide/email/sending-emails-with-gmail-smtp#listing-email-messages-by-criteria

Troubleshooting

Examples

Robot Framework

It is highly recommended to secure your passwords and take care that they are not stored in version control by mistake. See RPA.Robocorp.Vault to see how to store secrets in Robocorp Vault.

When sending HTML content with IMG tags, the src filenames must match the base image name given with the images parameter.

*** Settings ***
Library     RPA.Email.ImapSmtp   smtp_server=smtp.gmail.com  smtp_port=587
Task Setup  Authorize  account=${GMAIL_ACCOUNT}  password=${GMAIL_PASSWORD}

*** Variables ***
${GMAIL_ACCOUNT}        ACCOUNT_NAME
${GMAIL_PASSWORD}       ACCOUNT_PASSWORD
${RECIPIENT_ADDRESS}    RECIPIENT
${BODY_IMG1}            ${IMAGEDIR}${/}approved.png
${BODY_IMG2}            ${IMAGEDIR}${/}invoice.png
${EMAIL_BODY}     <h1>Heading</h1><p>Status: <img src='approved.png' alt='approved image'/></p>
...               <p>INVOICE: <img src='invoice.png' alt='invoice image'/></p>

*** Tasks ***
Sending email
    Send Message  sender=${GMAIL_ACCOUNT}
    ...           recipients=${RECIPIENT_ADDRESS}
    ...           subject=Message from RPA Robot
    ...           body=RPA Robot message body

Sending HTML Email With Image
    [Documentation]     Sending email with HTML content and attachment
    Send Message
    ...                 sender=${GMAIL_ACCOUNT}
    ...                 recipients=${RECIPIENT_ADDRESS}
    ...                 subject=HTML email with body images (2) plus one attachment
    ...                 body=${EMAIL_BODY}
    ...                 html=${TRUE}
    ...                 images=${BODY_IMG1}, ${BODY_IMG2}
    ...                 attachments=example.png

Python

from RPA.Email.ImapSmtp import ImapSmtp

gmail_account = "ACCOUNT_NAME"
gmail_password = "ACCOUNT_PASSWORD"
sender = gmail_account

mail = ImapSmtp(smtp_server="smtp.gmail.com", smtp_port=587)
mail.authorize(account=gmail_account, password=gmail_password)
mail.send_message(
    sender=gmail_account,
    recipients="RECIPIENT",
    subject="Message from RPA Python",
    body="RPA Python message body",
)
ROBOT_LIBRARY_DOC_FORMAT = 'REST'
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
add_gmail_labels(labels, criterion, source_folder: str = None) → bool

Add GMail labels to messages matching criterion and if given, source folder

Parameters

  • labels – comma separated list of labels to add

  • criterion – label messages matching criterion

  • source_folder – look for messages in this folder, default all folders

Returns

status of the operation

Example:

Add Gmail Labels  customer1   SUBJECT "order confirmation"
Add Gmail Labels  wip         SUBJECT "order confirmation"   customerfolder
authorize(account: str = None, password: str = None, smtp_server: str = None, imap_server: str = None, smtp_port: int = None, imap_port: int = None) → None

Authorize user to SMTP and IMAP servers.

Parameters

  • account – user account as string, defaults to None

  • password – user password as string, defaults to None

  • smtp_server – SMTP server address, defaults to None

  • imap_server – IMAP server address, defaults to None

  • smtp_port – SMTP server port, defaults to None (587 for SMTP)

  • imap_port – IMAP server port, defaults to None

Will use separately set credentials or those given in keyword call.

Example:

Authorize    ${username}   ${password}  smtp_server=smtp.gmail.com  smtp_port=587
authorize_imap(account: str = None, password: str = None, imap_server: str = None, imap_port: int = None) → None

Authorize to IMAP server.

Parameters

  • account – IMAP account name, defaults to None

  • password – IMAP account password, defaults to None

  • imap_server – IMAP server address, defaults to None

  • imap_port – IMAP server port, defaults to None

Can be called without giving any parameters if library has been initialized with necessary information and/or keyword Set Credentials has been called.

Example:

Authorize IMAP    ${username}   ${password}  imap.gmail.com  993
authorize_smtp(account: str = None, password: str = None, smtp_server: str = None, smtp_port: int = None) → None

Authorize to SMTP server.

Parameters

  • account – SMTP account name, defaults to None

  • password – SMTP account password, defaults to None

  • smtp_server – SMTP server address, defaults to None

  • smtp_port – SMTP server port, defaults to None (587 for SMTP)

Can be called without giving any parameters if library has been initialized with necessary information and/or keyword Set Credentials has been called.

Example:

Authorize SMTP    ${username}   ${password}  smtp.gmail.com  587
create_folder(folder_name: str = None) → bool

Create email folder

Parameters

folder_name – name for the new folder

Returns

True if operation was successful, False if not

Example:

Create Folder   filtered
delete_folder(folder_name: str = None) → bool

Delete email folder

Parameters

folder_name – current folder name

Returns

True if operation was successful, False if not

Example:

Delete Folder   filtered
delete_message(criterion: str = '') → bool

Delete single message from server based on criterion.

Parameters

criterion – filter messages based on this, defaults to “”

Returns

True if success, False if not

If criterion does not return exactly 1 message then delete is not done.

Example:

Delete Message  SUBJECT "Greetings RPA developer"
delete_messages(criterion: str = '', limit: int = None) → bool

Delete messages from server based on criterion.

Parameters

  • criterion – filter messages based on this, defaults to “”

  • limit – maximum number of message to delete

Returns

True if success, False if not

Example:

Delete Messages  SUBJECT Greetings
do_message_actions(criterion: str = '', actions: list = None, source_folder: str = None, target_folder: str = None, labels: str = None, limit: int = None, overwrite: bool = False) → Any

Do actions to messages matching criterion and if given, source folder

Actions can be:

  • msg_copy

  • msg_delete

  • msg_flag

  • msg_unflag

  • msg_read

  • msg_unread

  • msg_save

  • msg_attachment_save

  • glabel_add

  • glabel_remove

Result object contains following attributes:

  • actions_done, number of messages on which action was performed

  • message_count, number of messages matching criterion

  • ids, message ids matching criterion

  • uids, dictionary of message uids and message content

Parameters

  • criterion – perform actions on messages matching this

  • actions – list of actions to perform on matching messages

  • source_folder – look for messages in this folder, default all folders

  • target_folder – can be file path or email folder (for example action: msg_copy)

  • labels – comma separated list of labels (for example action: glabel_add)

  • limit – maximum number of messages (for example action: msg_delete)

  • overwrite – to control if file should overwrite (for example action: msg_attachment_save)

Returns

result object

Example:

${actions}=   Create List  msg_unflag  msg_read  msg_save  msg_attachment_save
Do Message Actions    SUBJECT "Order confirmation"
...                   ${actions}
...                   source_folder=XXX
...                   target_folder=${CURDIR}
...                   overwrite=True
email_to_document(input_source: Union[str, pathlib.Path, BinaryIO, bytes], output_path: Union[str, pathlib.Path])

Convert a raw e-mail into a Word document.

This keyword extracts the HTML (or Text) content from the passed input e-mail and saves it into docx format at the provided output path.

Parameters

  • input_source – Path, bytes or file-like object with the input raw e-mail content

  • output_path – Where to save the output docx file

Example:

Robot Framework

Convert email to docx
    ${mail_file} =     Get Work Item File    mail.eml
    Email To Document    ${mail_file}    ${OUTPUT_DIR}${/}mail.docx

Python

from pathlib import Path
from RPA.Email.ImapSmtp import ImapSmtp
from RPA.Robocorp.WorkItems import WorkItems

lib_work = WorkItems()
lib_mail = ImapSmtp()

def convert_email_to_docx():
    lib_work.get_input_work_item()
    mail_file = lib_work.get_work_item_file("mail.eml")
    lib_mail.email_to_document(mail_file, Path("./output") / "mail.docx")

convert_email_to_docx()
flag_messages(criterion: str = None, unflag: bool = False) → Any

Mark messages as flagged

Parameters

  • criterion – mark messages matching criterion

  • unflag – to mark messages as not flagged

Returns

successful operations (int), matching messages (int)

Example:

${flagged}  ${oftotal}    Flag Messages   SUBJECT rpa
${unflagged}  ${oftotal}  Flag Messages   SUBJECT rpa  unflag=True
get_decoded_email_body(message, html_first: bool = False) → Tuple[str, bool]

Decodes email body and extracts its text/html content.

Automatically detects character set if the header is not set.

Parameters

  • message – Raw 7-bit message body input e.g. from imaplib. Double encoded in quoted-printable and latin-1

  • html_first – Prioritize html extraction over text when this is True

Returns

Message body as unicode string and a boolean telling if the message has attachments

get_folder_list(subdirectory: str = None, pattern: str = None) → list

Get list of folders on the server

Parameters

  • subdirectory – list subdirectories for this folder

  • pattern – list folders matching this pattern

Returns

list of folders

Example:

@{folders}  Get Folder List
@{folders}  Get Folder List  pattern=important
@{folders}  Get Folder List  subdirectory=sub
list_messages(criterion: str = '', source_folder: str = None, readonly: bool = True) → Any

Return list of messages matching criterion.

Parameters

  • criterion – list emails matching this, defaults to “”

  • source_folder – list messages from this folder

  • readonly – set False if you want to mark matching messages as read

Returns

list of messages

Note. listing messages without source_folder might take a long time

Example:

@{emails}  List Messages  SUBJECT "rpa task"
FOR  ${email}  IN  @{EMAILS}
    Log  ${email}[Subject]
    Log  ${email}[From]
    Log  ${email}[Date]
    Log  ${email}[Delivered-To]
    Log  ${email}[Received]
    Log  ${email}[Has-Attachments]
    Log  ${email}[uid]
END
mark_as_read(criterion: str = None, unread: bool = False) → Any

Mark messages as read

Parameters

  • criterion – mark messages matching criterion

  • unread – to mark messages as not read

Returns

successful operations (int), matching messages (int)

Example:

${read}  ${oftotal}  Mark As Read   SUBJECT rpa
mark_as_unread(criterion: str = None) → Any

Mark messages as not read

Parameters

criterion – mark messages matching criterion

Returns

successful operations (int), matching messages (int)

Example:

${unread}  ${oftotal}  Mark As Unread   SUBJECT rpa
move_messages(criterion: str = None, target_folder: str = None, source_folder: str = None) → bool

Move messages from source folder to target folder

Parameters

  • criterion – move messages matching criterion

  • source_folder – location of the messages, default INBOX

  • target_folder – where messages should be move into

Returns

True if all move operations succeeded, False if not

Example:

${result}=    Move Messages
...    criterion=SUBJECT "order confirmation 32"
...    target_folder=yyy

${result}=    Move Messages
...    criterion=ALL
...    source_folder=yyy
...    target_folder=XXX
move_messages_by_ids(message_ids: Union[str, List], target_folder: str, source_folder: str, use_gmail_search: bool = False) → bool

Move message by their Message-ID’s from source folder to target folder

Parameters

  • message_ids – one Message-ID as string or list of Message-IDs

  • source_folder – location of the messages, default INBOX

  • target_folder – where messages should be move into

  • use_gmail_search – set to True to use Rfc822msgid search, default is HEADER Message-ID search

Returns

True if all move operations succeeded, False if not

remove_gmail_labels(labels, criterion, source_folder: str = None) → bool

Remove GMail labels to messages matching criterion and if given, source folder

Parameters

  • labels – comma separated list of labels to remove

  • criterion – unlabel messages matching criterion

  • source_folder – look for messages in this folder, default all folders

Returns

status of the operation

Example:

Remove Gmail Labels  wip  SUBJECT "order confirmation"
Remove Gmail Labels  wip  SUBJECT "order confirmation"  customerfolder
rename_folder(oldname: str = None, newname: str = None, suppress_error: bool = False) → bool

Rename email folder

Parameters

  • oldname – current folder name

  • newname – new name for the folder

  • suppress_error – to silence warning message, defaults to False

Returns

True if operation was successful, False if not

Example:

Rename Folder   subfolder   filtered
save_attachment(message: Union[dict, email.message.Message], target_folder: str, overwrite: bool)

Save mail attachment of single given email into local folder

Parameters

  • message – message item

  • target_folder – local folder for saving attachments to (needs to exist), defaults to user’s home directory if None

  • overwrite – overwrite existing file is True, defaults to False

Example:

@{emails}  List Messages  SUBJECT "rpa task"
FOR  ${email}  IN  @{emails}
    Run Keyword If   ${email}[Has-Attachments] == True
    ...              Save Attachment  ${email}  target_folder=${CURDIR}  overwrite=True
END
save_attachments(criterion: str = '', target_folder: str = None, overwrite: bool = False) → List

Save mail attachments of emails matching criterion into local folder.

Parameters

  • criterion – attachments are saved for mails matching this, defaults to “”

  • target_folder – local folder for saving attachments to (needs to exist), defaults to user’s home directory if None

  • overwrite – overwrite existing file is True, defaults to False

Returns

list of saved attachments

Example:

${numsaved}  Save Attachments   SUBJECT "rpa task"
...          target_folder=${CURDIR}${/}messages  overwrite=True
save_messages(criterion: str = '', target_folder: str = None) → bool

Save messages based on criteria and store them to target folder with attachment files.

Does not save message if target_folder is not given.

Parameters

  • criterion – filter messages based on this, defaults to “”

  • target_folder – path to folder where message are saved, defaults to None

Returns

True if success, False if not

Example:

Save Messages  SUBJECT Important message  target_folder=${USERDIR}${/}messages
select_folder(folder_name: str = 'INBOX', readonly: bool = False) → int

Select folder by name

Parameters

  • folder_name – name of the folder to select

  • readonly – if set to True then message flags are not modified

Returns

message count in the selected folder

Returns number of messages in the folder or exception if folder does not exist on the server.

Example:

Select Folder   subfolder
send_message(sender: str, recipients: str, subject: str = '', body: str = '', attachments: Union[List[str], str] = None, html: bool = False, images: str = None) → bool

Send SMTP email

Parameters

  • sender – who is sending, ie. ‘from’

  • recipients – who is receiving, ie. ‘to’

  • subject – mail subject field

  • body – mail body content

  • attachments – list of filepaths to attach, defaults to []

  • html – if message content is in HTML, default False

  • images – list of filepaths for inline use, defaults to []

Valid sender values:

Example:

Send Message  sender@domain.com  recipient@domain.com
...           subject=Greetings Software Robot Developer
...           body=${email_body}
...           attachments=${CURDIR}${/}report.pdf
send_smtp_hello() → None

Send hello message to SMTP server.

Required step when creating SMTP connection.

set_credentials(account: str = None, password: str = None) → None

Set credentials

Parameters

  • account – user account as string, defaults to None

  • password – user password as string, defaults to None

Example:

Set Credentials   ${username}   ${password}
Authorize
unflag_messages(criterion: str = None) → Any

Mark messages as not flagged

Parameters

criterion – mark messages matching criterion

Returns

successful operations (int), matching messages (int)

Example:

${unflagged}  ${oftotal}  Unflag Messages   SUBJECT rpa
wait_for_message(criterion: str = '', timeout: float = 5.0, interval: float = 1.0, readonly: bool = True) → Any

Wait for email matching criterion to arrive into mailbox.

Parameters

  • criterion – message filter to wait for, defaults to “”

  • timeout – total time in seconds to wait for email, defaults to 5.0

  • interval – time in seconds for new check, defaults to 1.0

  • readonly – set False if you want to mark matching messages as read

Returns

list of messages

Example:

@{emails}  Wait For Message  SUBJECT "rpa task"  timeout=300  interval=10
RPA.Email.ImapSmtp.get_part_filename(msg)
RPA.Email.ImapSmtp.imap_connection(f)
RPA.Email.ImapSmtp.smtp_connection(f)
RPA.Email.ImapSmtp.to_action(value)

Convert value to Action enum.