Python API¶
Exchange¶
-
class
RPA.Email.Exchange.
Exchange
¶ Bases:
object
Exchange is a library for sending, reading, and deleting emails. Exchange is interfacing with Exchange Web Services (EWS).
For more information about server settings, see this Microsoft support article.
Examples
Robot Framework
*** Settings *** Library RPA.Email.Exchange Task Setup Authorize username=${ACCOUNT} password=${PASSWORD} *** Variables *** ${ACCOUNT} ACCOUNT_NAME ${PASSWORD} ACCOUNT_PASSWORD ${RECIPIENT_ADDRESS} RECIPIENT ${IMAGES} myimage.png ${ATTACHMENTS} C:${/}files${/}mydocument.pdf *** Tasks *** Task of sending email Send Message recipients=${RECIPIENT_ADDRESS} ... subject=Exchange Message from RPA Robot ... body=<p>Exchange RPA Robot message body<br><img src='myimage.png'/></p> ... save=${TRUE} ... html=${TRUE} ... images=${IMAGES} ... cc=EMAIL_ADDRESS ... bcc=EMAIL_ADDRESS ... attachments=${ATTACHMENTS} Task of listing messages # Attachments are saved specifically with a keyword Save Attachments ${messages}= List Messages FOR ${msg} IN @{messages} Log Many ${msg} ${attachments}= Run Keyword If "${msg}[subject]"=="about my orders" ... Save Attachments ... ${msg} ... save_dir=${CURDIR}${/}savedir END # Using save_dir all attachments in listed messages are saved ${messages}= List Messages ... INBOX/Problems/sub1 ... criterion=subject:'about my orders' ... save_dir=${CURDIR}${/}savedir2 FOR ${msg} IN @{messages} Log Many ${msg} END Task of moving messages Move Messages criterion=subject:'about my orders' ... source=INBOX/Processed Purchase Invoices/sub2 ... target=INBOX/Problems/sub1
Python
from RPA.Email.Exchange import Exchange ex_account = "ACCOUNT_NAME" ex_password = "ACCOUNT_PASSWORD" mail = Exchange() mail.authorize(username=ex_account, password=ex_password) mail.send_message( recipients="RECIPIENT", subject="Message from RPA Python", body="RPA Python message body", )
About criterion parameter
Following table shows possible criterion keys that can be used to filter emails. There apply to all keywords which have
criterion
parameter.Key
Effective search
subject
subject to match
subject_contains
subject to contain
body
body to match
body_contains
body to contain
sender
sender (from) to match
sender_contains
sender (from) to contain
before
received time before this time
after
received time after this time
between
received time between start and end
category
categories to match
category_contains
categories to contain
importance
importance to match
Keys before, after and between at the moment support two different timeformats either %d-%m-%Y %H:%M or %d-%m-%Y. These keys also support special string NOW which can be used especially together with keyword
Wait for message criterion=after:NOW
.When giving time which includes hours and minutes then the whole time string needs to be enclosed into single quotes.
before:25-02-2022 after:NOW between:'31-12-2021 23:50 and 01-01-2022 00:10'
Different criterion keys can be combined.
subject_contains:'new year' between:'31-12-2021 23:50 and 01-01-2022 00:10'
Please note that all values in the criterion that contain spaces need to be enclosed within single quotes.
In the following example the email subject is going to matched only against new not new year.
subject_contains:new year
-
ROBOT_LIBRARY_DOC_FORMAT
= 'REST'¶
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
Connect to Exchange account
- Parameters
username – account username
password – account password
autodiscover – use autodiscover or set it off
accesstype – default “DELEGATE”, other option “IMPERSONATION”
server – required for configuration options
primary_smtp_address – by default set to username, but can be set to be different than username
-
create_folder
(folder_name: Optional[str] = None, parent_folder: Optional[str] = None) → bool¶ Create email folder
- Parameters
folder_name – name for the new folder
parent_folder – name for the parent folder, by default INBOX
- Returns
True if operation was successful, False if not
-
delete_folder
(folder_name: Optional[str] = None, parent_folder: Optional[str] = None) → bool¶ Delete email folder
- Parameters
folder_name – current folder name
parent_folder – name for the parent folder, by default INBOX
- Returns
True if operation was successful, False if not
-
empty_folder
(folder_name: Optional[str] = None, parent_folder: Optional[str] = None, delete_sub_folders: Optional[bool] = False) → bool¶ Empty email folder of all items
- Parameters
folder_name – current folder name
parent_folder – name for the parent folder, by default INBOX
delete_sub_folders – delete sub folders or not, by default False
- Returns
True if operation was successful, False if not
-
list_messages
(folder_name: Optional[str] = None, criterion: Optional[str] = None, contains: Optional[bool] = False, count: Optional[int] = 100, save_dir: Optional[str] = None) → list¶ List messages in the account inbox. Order by descending received time.
- Parameters
folder_name – name of the email folder, default INBOX
criterion – list messages matching criterion
contains – if matching should be done using contains matching and not equals matching, default False is means equals matching
count – number of messages to list
save_dir – set to path where attachments should be saved, default None (attachments are not saved)
-
list_unread_messages
(folder_name: Optional[str] = None, criterion: Optional[str] = None, contains: Optional[bool] = False, count: Optional[int] = 100, save_dir: Optional[str] = None) → list¶ List unread messages in the account inbox. Order by descending received time.
- Parameters
folder_name – name of the email folder, default INBOX
criterion – list messages matching criterion
contains – if matching should be done using contains matching and not equals matching, default False is means equals matching
count – number of messages to list
save_dir – set to path where attachments should be saved, default None (attachments are not saved)
-
move_message
(msg: Optional[dict], target: Optional[str])¶ Move a message into target folder
- Parameters
msg – dictionary of the message
target – path to target folder
- Raises
AttributeError – if msg is not a dictionary containing id and changekey attributes
Example:
${messages}= List Messages ... INBOX ... criterion=subject:about my orders FOR ${msg} IN @{messages} Run Keyword If "${msg}[sender][email_address]"=="${priority_account}" ... Move Message ${msg} target=INBOX / Problems / priority END
-
move_messages
(criterion: Optional[str] = '', source: Optional[str] = None, target: Optional[str] = None, contains: Optional[bool] = False) → bool¶ Move message(s) from source folder to target folder
- Parameters
criterion – move messages matching this criterion
source – source folder
target – target folder
contains – if matching should be done using contains matching and not equals matching, default False is means equals matching
- Returns
boolean result of operation, True if 1+ items were moved else False
Criterion examples:
subject:my message subject
body:something in body
sender:sender@domain.com
-
rename_folder
(oldname: Optional[str] = None, newname: Optional[str] = None, parent_folder: Optional[str] = None) → bool¶ Rename email folder
- Parameters
oldname – current folder name
newname – new name for the folder
parent_folder – name for the parent folder, by default INBOX
- Returns
True if operation was successful, False if not
-
save_attachments
(message: Union[dict, str], save_dir: Optional[str] = None, attachments_from_emls: Optional[bool] = False) → list¶ Save attachments in message into given directory
- Parameters
message – dictionary or .eml filepath containing message details
save_dir – filepath where attachments will be saved
attachments_from_emls – if attachment is a EML file, set to True to save attachments from that EML file, default False
- Returns
list of saved attachments
Example.
${messages}= List Messages FOR ${msg} IN @{messages}} Save Attachments ${msg} %{ROBOT_ARTIFACTS} True END ${attachments}= Save Attachments ${CURDIR}${/}saved.eml %{ROBOT_ARTIFACTS}
-
save_message
(message: dict, filename: str) → list¶ Save email as .eml file
- Parameters
message – dictionary containing message details
filename – name of the file to save message into
-
send_message
(recipients: Union[List[str], str, None] = None, subject: Optional[str] = '', body: Optional[str] = '', attachments: Union[List[str], str, None] = None, html: Optional[bool] = False, images: Union[List[str], str, None] = None, cc: Union[List[str], str, None] = None, bcc: Union[List[str], str, None] = None, save: Optional[bool] = False) → None¶ Keyword for sending message through connected Exchange account.
- Parameters
recipients – list of email addresses
subject – message subject, defaults to “”
body – message body, defaults to “”
attachments – list of filepaths to attach, defaults to None
html – if message content is in HTML, default False
images – list of filepaths for inline use, defaults to None
cc – list of email addresses
bcc – list of email addresses
save – is sent message saved to Sent messages folder or not, defaults to False
Email addresses can be prefixed with
ex:
to indicate an Exchange account address.At least one target needs to exist for recipients, cc or bcc.
-
wait_for_message
(criterion: Optional[str] = '', timeout: Optional[float] = 5.0, interval: Optional[float] = 1.0, contains: Optional[bool] = False, save_dir: Optional[str] = None) → Any¶ Wait for email matching criterion to arrive into INBOX.
- Parameters
criterion – wait for message matching criterion
timeout – total time in seconds to wait for email, defaults to 5.0
interval – time in seconds for new check, defaults to 1.0 (minimum)
contains – if matching should be done using contains matching and not equals matching, default False is means equals matching THIS PARAMETER IS DEPRECATED AS OF rpaframework 12.9.0
save_dir – set to path where attachments should be saved, default None (attachments are not saved)
- Returns
list of messages
-
-
exception
RPA.Email.Exchange.
NoRecipientsError
¶ Bases:
ValueError
Raised when email to be sent does not have any recipients, cc or bcc addresses.
-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
RPA.Email.Exchange.
mailbox_to_email_address
(mailbox)¶