RPA.Email.Exchange
module RPA.Exchange
class RPA.Email.Exchange.Exchange
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
Python
OAuth2
The OAuth2 flow is the only way of authorizing at the moment as Microsoft disabled entirely the usage of passwords, even App Passwords. And since you have to work with tokens now and because this library has the capability to automatically refresh an expired token, please don’t forget to initialize the library with the following parameters: vault_name, vault_token_key and tenant.
Learn more on how to use the OAuth2 flow in this Portal robot example-oauth-email.
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.
Different criterion keys can be combined.
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.
variable ROBOT_LIBRARY_DOC_FORMAT
variable ROBOT_LIBRARY_SCOPE
variable TO_PROTECT
method authorize
Connect to Exchange account
Parameters
- username – account username
- password – account password (can be skipped with OAuth2)
- autodiscover – use autodiscover or set it off (on by default)
- access_type – default “DELEGATE”, other option “IMPERSONATION”
- server – required for configuration setting (with autodiscover off)
- primary_smtp_address – by default set to username, but can be set to be different from username
- is_oauth – use the OAuth2 authorization code flow (instead of basic auth)
- client_id – registered application ID
- client_secret – registered application secret (password)
- token – contains access and refresh tokens, type, scope, expiry etc.
method create_folder
Create email folder.
Parameters
- folder_name – name for the new folder (required)
- parent_folder – name for the parent folder, by default INBOX
method delete_folder
Delete email folder.
Parameters
- folder_name – current folder name (required)
- parent_folder – name for the parent folder, by default INBOX
method empty_folder
Empty email folder of all items
Parameters
- folder_name – current folder name (required)
- 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
method generate_oauth_url
Generates an authorization URL which must be opened by the user to start the OAuth2 flow and obtain an authorization code as response.
- Parameters: client_id – Client app ID. (generated by the provider)
- Returns: Authorization URL string not containing any sensitive info in it.
Example: Robot Framework
method get_oauth_token
Exchanges the code obtained previously with Generate OAuth URL for a
token.
Parameters
- client_secret – Client app secret. (generated by the provider)
- response_url – The final URL containing the authorization code found in the address bar after authenticating and authorizing the Client app through the authorization URL.
- Returns: A dictionary containing the access & refresh token, plus metadata.
Example: Robot Framework
method list_messages
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)
- items_only – return only list of Message objects (instead of dictionaries)
method list_unread_messages
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)
method move_message
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
method move_messages
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
method refresh_oauth_token
Refreshes the token as the access one usually expires after 1h and the refresh one never expires. (as long as it doesn’t get revoked)
Parameters
- client_id – Client app ID. (generated by the provider)
- client_secret – Client app secret. (generated by the provider)
- token – Full token dictionary previously obtained with
Get OAuth Token.
- Returns: A token dictionary containing a new access token and updated metadata.
Example: Robot Framework
method rename_folder
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
method save_attachments
Save attachments from message into given directory.
Parameters
- message – dictionary or .eml file path containing message details
- save_dir – file path where attachments will be saved
- attachments_from_emls – pass True if the attachment is an EML file (for saving attachments from that EML file instead), False otherwise (default)
- overwrite – overwrite existing downloaded attachments with the same name if set to True, False otherwise (default)
- Returns: list of saved attachments
method save_message
Save email as .eml file.
Parameters
- message – dictionary containing message details
- filename – name of the file to save message into
method send_message
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
- reply_to – email address to reply to
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.
method send_reply_message
Send reply to a message.
Parameters
- message – either Message object or ID of the message for the message which this is replying to
- body – message body for the reply
- subject – optional subject for the reply, defaults to None
- reply_all – if True then reply is sent to all recipients, defaults to False
Robot Framework example
method wait_for_message
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